home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / oberon / jacob-v0.1 / jacob-v0 / jacob / README < prev    next >
Encoding:
Text File  |  1996-04-04  |  9.1 KB  |  261 lines
  1.  
  2.                                    J A C O B
  3.  
  4.                          (Just A Compiler for OBeron-2)
  5.  
  6.  
  7.                                 Version 0.1.1
  8.  
  9.                                    04/04/96
  10.  
  11.         
  12. Introduction
  13. ------------
  14.  
  15. This is the second public release of our Oberon-2 compiler Jacob. Jacob (as
  16. the name says ;-) is a stand-alone Oberon-2 compiler under Linux. It compiles a
  17. single Oberon-2 module together with its imported modules and links all the
  18. stuff together to an executable program whose name is the module name.
  19.  
  20. As the practical result of our diploma thesis, Jacob owes its existance from
  21. the use of compiler generating tools: The front-end was generated with the
  22. Compiler Construction Tool Box "Cocktail" (Version 9209) of Dr. J. Grosch. In
  23. particular the tools Rex, Lalr, Puma, Ast and Ag were used. For the back-end we
  24. used Beg (Version 1.75) of H. Emmelmann to produce GNU assembler code.
  25.  
  26. There is still a lot of debug code in Jacob so the execution speed is not
  27. optimal. The various command-line options allows tracing of the compile phase
  28. and looking at intermediate results which are often hidden within a compiler.
  29.  
  30.  
  31. Features
  32. --------
  33.  
  34.  - Jacob implements the full Oberon-2 language as reported in 
  35.    "The Programming Language Oberon-2" (March 1995).
  36.  
  37.  - External modules allow to write library modules in other Languages.
  38.  
  39.  - Instead of an explicit dispose function a garbage collector is implemented
  40.    using a mark-and-sweep algorithm.
  41.  
  42.  - Command-line options for enabling and disabling NIL, index, range 
  43.    and assertion checks.
  44.  
  45.  
  46. Implementation extensions/restrictions
  47. --------------------------------------
  48.  
  49.  - The underscore character is legal in identifiers.
  50.  
  51.  - The maximum length of identifiers is 255.
  52.  
  53.  - Procedures can be nested up to a maximum of 30.
  54.  
  55.  - A type extension hierarchy can have a maximum depth of 8.
  56.  
  57.  - The difference between the smallest and the largest case label may not be
  58.    greater than 4096.
  59.    
  60.  - SYSTEM.NEW is only valid for pointers which base type doesn't contain any
  61.    pointer.
  62.  
  63.  
  64. Disclaimer
  65. ----------
  66.  
  67. This software package is FREE, so you can do with it whatever is in your mind, 
  68. BUT: whatever you do with this package, YOU are responsible and you do it ON
  69. YOUR OWN RISK. This simply means we disclaim warranties of any kind.
  70.  
  71. Because of the early version of Jacob it is definitely possible that there are
  72. bugs in the implementation. If you find one (or several) don't despair. Please
  73. let us know about it (see section Bug Report below).
  74.  
  75.  
  76. Requirements
  77. ------------
  78.  
  79. Jacob only requires the GNU assembler as. We use version 2.2 (i486-linux).
  80.  
  81.  
  82. Installation
  83. ------------
  84.  
  85. Un-tar the package wherever you want (/usr is recommended).
  86. This will result in the subdirectory tree:
  87.  
  88.    jacob
  89.    jacob/lib
  90.    jacob/sys
  91.    jacob/test
  92.    
  93. If you decide to use a home directory other than /usr
  94. you have to edit the script files oc and sys/oc.linker and
  95. to adjust the directory specifications in these scripts.
  96.  
  97. Copy, move or link the script oc into a directory which is included
  98. by your PATH environment variable.
  99.  
  100. To test your installation change the current work directory to 
  101. jacob/test, compile the Test module by "oc Test". This will also
  102. generate the object files of the library modules, if you have
  103. write permissions to jacob/lib.
  104.  
  105.  
  106. Invocation
  107. ----------
  108.  
  109. By typing jacob -h you get the usual description of the usage with a short
  110. explanation of the available command-line options. 
  111.  
  112. Assembler and object files are written into the directory which
  113. contains the source file.
  114.  
  115.  
  116. Library Modules
  117. ---------------
  118.  
  119. We have (up to now) implemented a (very) quick'n'dirty set of library modules. 
  120. These are:
  121.  
  122.  - Out      : output of some basic types
  123.  - Storage  : heap and garbage collector functions
  124.  - SysLib   : interface to the linux os
  125.  - RawFiles : basic file i/o
  126.  - Lib      : command-line arguments, random numbers and others
  127.  - Str      : string Handling
  128.  
  129. A more detailed description can be found at the end of this file.
  130.  
  131.  
  132. Bug Report
  133. ----------
  134.  
  135. If you find an error in the implementation or you have comments regarding
  136. Jacob, PLEASE send it to us. Help us to improve Jacob by sending e-mail to the
  137. following address:
  138.     
  139.      sepp@cs.tu-berlin.de
  140.  
  141. It is useful to send a small example program which shows the bug.
  142.  
  143.  
  144. Future Work
  145. -----------
  146.  
  147. As future work we plan:
  148.  
  149.  - A hand-written front-end which is implemented using Jacob itself
  150.  
  151.  - More sufficient library modules
  152.  
  153.  - The use of symbol files to speed up the import stage
  154.  
  155.  - An improved memory management especially a faster mark algorithm
  156.  
  157. Changes from Version 0.1 to 0.1.1
  158. ---------------------------------
  159.  
  160.  - Small bug fix: Changed /lib/elf/ld-linux.so.1 to /lib/ld-linux.so.1
  161.  
  162. Changes from Version 0 to 0.1
  163. -----------------------------
  164.  
  165.  - Jacob runs now as ELF executable and produces ELF output.
  166.  
  167.  - External modules (former "foreign" modules):
  168.  
  169.    - Changed syntax (with respect to the Oakwood Guidelines):
  170.  
  171.         Module      = MODULE ident ';' 
  172.                       [ImportList] 
  173.                       DeclSeq 
  174.                       [BEGIN StatementSeq] END ident 
  175.                     | XModule .
  176.         ...
  177.         XModule     = MODULE ident EXTERNAL '[' string ']' ';' 
  178.                       [ImportList] 
  179.                       XDeclSeq 
  180.                       END ident '.' .
  181.         XDeclSeq    = { CONST     {ConstDecl ';'} 
  182.                       | TYPE      {TypeDecl  ';'} 
  183.                       | VAR       {VarDecl   ';'}
  184.                       | PROCEDURE IdentDef [XFormalPars] ';' 
  185.                       } .
  186.         XFormalPars = '(' [XFPSections] ')' [':' Qualident] .
  187.         XFPSections = FPSection {';' FPSection} [';' '..'] .
  188.         
  189.      External modules are identified by the keyword EXTERNAL following the
  190.      module's name. The following bracket-enclosed string will be passed
  191.      unchanged to the linker.
  192.      
  193.      Constants, types, variables and procedures may be declared in any order.
  194.      This allows grouping of types and functions which belong together,
  195.      e.g. for writing interfaces for large libraries. Type-bound procedures
  196.      aren't allowed.
  197.      
  198.      A procedure declaration consists only of the procedure header. The last
  199.      formal parameter of a non-empty formal parameter list may be '..', in
  200.      which case any non-empty actual parameter list starting at the 
  201.      corresponding position is legal. 
  202.    
  203.    - Changed parameter passing mechanisms for external procedures:
  204.      - No hidden parameters (type tags, array lengths) will be passed.
  205.      
  206.      - The following "objects" will be passed according the kind/type of
  207.        the formal/actual parameter ('..' is treated like an open-array
  208.        value parameter):
  209.  
  210.        formal parameter     | actual parameter         | passed object
  211.        ===================================================================
  212.        variable parameter   | any                      | address of actual 
  213.                             |                          | parameter
  214.        -------------------------------------------------------------------
  215.        non-open-array value | any                      | value of actual
  216.        parameter            |                          | parameter
  217.        -------------------------------------------------------------------
  218.        open-array value     | character constant;      | address of actual
  219.        parameter            | string constant; array   | parameter
  220.        -------------------------------------------------------------------
  221.        open-array value     | SYSTEM.BYTE; SYSTEM.PTR; | value of actual
  222.        parameter            | BOOLEAN; CHAR variable;  | parameter
  223.                             | SET; integer type; real  |
  224.                             | type; NIL; pointer,      |
  225.                             | procedure or record type |
  226.        -------------------------------------------------------------------
  227.        ..                   | character constant;      | address of actual
  228.                             | string constant; array   | parameter
  229.        -------------------------------------------------------------------
  230.        ..                   | SYSTEM.BYTE; SYSTEM.PTR; | value of actual
  231.                             | BOOLEAN; CHAR variable;  | parameter
  232.                             | SET; integer type; real  |
  233.                             | type; NIL; pointer,      |
  234.                             | procedure or record type |
  235.        ---------------------+--------------------------+------------------
  236.  
  237.    - External variables declarable and accessible.
  238.  
  239.    - There are no type descriptors for records.
  240.    
  241.    - If external procedures are assigned to procedure variables, the
  242.      programmer should exactly know what (s)he's doing...
  243.  
  244.  - Code improvements:
  245.    - Displays in stack frames are more compact.
  246.    - Jump optimization (not only) for boolean short-circuit.
  247.    
  248.  - Improved memory handling at compile-time.
  249.  
  250.  - New command line options.
  251.    
  252.  - Various bug fixes:
  253.    - Comparison of two function results with a real type.
  254.    - Recompilation if a indirectly imported module is younger than
  255.      the client module.
  256.    - A SYSTEM.VAL at a variable parameter position gets now coded correctly.
  257.    - ...
  258.  
  259.  - Library modules:
  260.    - argc, argv, env and errno now directly accessible through module SysLib.
  261.