home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / pasos2c1.zip / pasos2.man < prev    next >
Text File  |  1993-12-17  |  17KB  |  368 lines
  1.  
  2.     PASCAL compiler, ALPHA 0.1c release for OS/2
  3.  
  4.                                                     Eindhoven, 16 december 1993
  5.       
  6.     COMMAND
  7.             pc  [options] <filename>.<ext>
  8.             pas [options] <filename>.<ext>
  9.  
  10.     DESCRIPTION
  11.  
  12.         This is the temporary manual page for 
  13.     
  14.              the pascal compiler frontend,
  15.              the pascal compiler.
  16.  
  17.         In general it should be sufficient to use the compiler in the following 
  18.         way:
  19.             'pc file.pas'
  20.             'pc otherfile.s'
  21.             'pc stillotherfile.o'
  22.             
  23.         This creates a file 'file.exe' which can be executed.
  24.     
  25.         The PASCAL 'version' implemented is as close to the standard level(0)
  26.         as possible. There are a few extentions, a few ommisions, plenty of 
  27.         bugs, and some not yet implemented areas.
  28.  
  29.         Currently is it not possible to create seperate modules without 
  30.         changing the intermediate assembler file. If object-modules need to be 
  31.         made, then make a program of every module, with an empty main program 
  32.         body. Create the assembly files, from which the '$Pmain'-routine should
  33.         be deleted. This file can then be assembled.
  34.         There is currently no supported way to use variables which are declared 
  35.         in other modules. For procedures and routines is the attribute 
  36.         'EXTERNAL' available. 
  37.             Eg.: 'Procedure SomeWhereElse(i;integer); EXTERNAL'
  38.  
  39.         The actual code is transformed in several steps:
  40.                 1)    The user code is passed through the preprocessor.
  41.                       Currently is this the C-preprocessor, which complains
  42.                       about unterminated strings ' in PASCAL comments.
  43.                       You'll have to change your comments.
  44.                 2)    Then 'pas' is used to transform the resulting PASCAL into 
  45.                       assembly. Currently Microsoft MASM/ML is the only 
  46.                       assembly language supported.
  47.                 3)    The assembly code is used to create the objectcode for 
  48.                       the module.
  49.                 4)    Which is linked together with the PASCAL library, p.lib,
  50.                       and creates a the resulting executable.
  51.                       
  52.         To watch these steps, just add the -v switch to the pc command.              
  53.     
  54.     OPTIONS for pc
  55.             -v*     Show command the frontend executes.
  56.             -Dname 
  57.             -Dname=def Set definitions for the preprocessor.
  58.             -Uname  Instruct the preprocessor to undefine 'name'.
  59.             -S      Generate an assembly file and terminate
  60.             -c      Generate an object file, but do not link.
  61.             -E      Only run the preprocessor on the file, and write results to
  62.                     standard ouput.
  63.             -o <file>        Specify the file in which the result should be 
  64.                     written.
  65.             -h      Runtime help information.
  66.             -Q      Suppress the copyright info when pc starts
  67.             -x      Generate a crossreference in <filename>.xrf
  68.             -m      Generate MASM typical code and possibly use MASM.
  69.             -t      Generate TASM typical code and possibly use TASM.
  70.             -G      Generate GAS typical code and use GAS to assemble.                    
  71.     
  72.     OPTIONS for pas
  73.             -v*     Switch verbosity one level higher.
  74.             -h      Runtime help information.
  75.             -x      Generate a crossreference in <filename>.xrf
  76.             -m      Generate MASM typical code and possibly use MASM.
  77.             -t      Generate TASM typical code and possibly use TASM.
  78.             -G      Generate GAS typical code and use GAS to assemble.                    
  79.     
  80.             -d      Debugging options.
  81.                         bEePprsTt
  82.                 r     List the tokens found by the scanner 
  83.                 p     Show which rules are matched in the parser
  84.                 i     dump the identifier table to <filename>.ids
  85.                 t/T*  dump the AST/defs tree (or more Tree) 
  86.                             to <filename>.tre for AST trees
  87.                             to <filename>.syt for defs-trees
  88.                 s     write a trace of the semantic evaluation to <filename>.sem
  89.                 P     Dump the environment as it is Predefined
  90.                 e/E*  List the environments on numerous ocassions
  91.     
  92.              * indicates that a switch know levels, multiple time specification
  93.                of the switch indicates "more" of that switch
  94.                Capitalisations of those switches increments the debuggin level 
  95.                with five lowercase's.
  96.  
  97.     ASSEMBLERS
  98.     
  99.     NOTE: IMPORTANT.
  100.         This compiler does not include an assembler, but it does require one.
  101.         This third release can either use:
  102.             Microsoft MASM or 
  103.             Borland TASM for OS/2
  104.             
  105.          OR GNU/GAS which can run on the EMX environment for DOS and OS2.
  106.          (Note that for execution undr DOS a CO-processor is required.
  107.           The Pascal compiler uses floating point at some places.
  108.           This will be changed in the near future.)
  109.  
  110.         And currently the MASM part is very picky. 
  111.         It only generates code for MASM 6.0A (note the A !!)
  112.         I had severe problems when using the regular MASM 6.0, The major
  113.         reason was wrong address/offset calculations.
  114.         I haven't tried it with MASM 5.x, since I don't have it.
  115.       
  116.         If you can't get it to run with MASM 6.0, go and yell at MS to make
  117.         MASM 6.0A more freely available. So people can buy it.
  118.         
  119.         Or buy Borlands TASM, which unfortunately is included in a rather large
  120.         package, and ain't cheap either.
  121.         
  122.         If you have installed the EMX gnu compiler tools, you can use GNU/GAS
  123.         which is the default. If you have installed only the emx-runtime 
  124.         environment installed you'll need to add some extra tools.
  125.  
  126.                Install emxrt
  127.                emxdev
  128.                gnudev. (See the install.emx file)
  129.  
  130.         These files are part of the EMX distribution which include GNU/GCC.
  131.     
  132.     DEBUGGING
  133.  
  134.         Not much attention has (yet) been given to debugging and creating 
  135.         debugging information. I debug the programs on assembly language level 
  136.         using IBM's IPMD. 
  137.         You don't want to do this, unless you're familiar with the 386-code, 
  138.         since no PASCAL code is included. And it can be mind boggling to find 
  139.         out what is going on.
  140.     
  141.     EXTENTIONS
  142.         Several extenstions have been implemented to make life a little easier.
  143.     
  144.         Comments:       A comment started by one version of the comments 
  145.                         starter, has to be terminated by the matching comment 
  146.                         close combination. They cannot be nested.
  147.                         Thus the following are complete comments:
  148.                         {(**)}, (*{}*). (*}*) {*)}
  149.                         Not correct are:
  150.                         {*), (*}, (*{*), {(*} or {(*{}*)}
  151.         
  152.         Identifiers:    Identifiers can contain '_' and '$' as valid characters.
  153.                         if '_' of '$' is used a starting character then the 
  154.                         second character has to be one from the 
  155.                         set ['a'..'z','A'..'Z'].
  156.                         Identifiers are case insensitive.
  157.     
  158.         Declaration order    The declaration order of constants, types, 
  159.                         variables and routines is not required. These 
  160.                         declaration blocks can be repeated multiple times in 
  161.                         any order. The only restriction is that only 
  162.                         pointer-type definitions can refer to types yet to be 
  163.                         declared.
  164.         
  165.         EXTERNAL        Net to the 'FORWARD' directive for routines, is the 
  166.                         'EXTERNAL' directive available as an indication to the 
  167.                         compiler/assembler that code for this routine is to be 
  168.                         found elsewhere.
  169.                     
  170.         CASE-statement  The CASE-statement has been expanded with a default 
  171.                         clause. Both OTHERWISE and ELSE are recognised as 
  172.                         default selectors. This is the grammar for the 
  173.                         extention:
  174.                     
  175.       statement9a    =  'CASE' expression 'OF' case_list case_default case_end.
  176.         
  177.       case_default     =  <  
  178.         /* And these 2 are definitly not in the ISO standard.
  179.          */
  180.         
  181.         /* A Microsoft extention */
  182.         case_default1  =  'OTHERWISE' statement  .
  183.         case_default1a =  ';' 'OTHERWISE' statement  .
  184.         
  185.         /* A Turbo Pascal extention 
  186.         /* Hopefully it does not conflict with the regular treatment of an
  187.         /* If-Then-Else statement.
  188.          */
  189.         case_default2  =  'ELSE' statement .
  190.       >.
  191.       
  192.         MinInt          Next to the constant MaxInt (2147483647) is also the 
  193.                         constant MinInt (-2147483648) available.
  194.     
  195.         Assign          To be able to interact with the filesystem, it is 
  196.                         possible to use the procedure 
  197.                             ASSIGN(Var f: anyfile, s :string),
  198.                         an associate an external filename with an internal file.
  199.  
  200.     OMMISIONS
  201.         
  202.         PACKED          The keyword 'PACKED' is allowed in declaration but is 
  203.                         ignored. Using it does not give any allocation 
  204.                         advantages. The accompanying routines 'PACK' and 
  205.                         'UNPACK' are not implemented. They are recognised by 
  206.                         the scanner/parser.
  207.                     
  208.         CONFORMANT ARRAY    Conformant array are not include with a PASCAL 
  209.                         level(0) implementation.
  210.                     
  211.     FEATURES
  212.  
  213.         SET             A set can be as big as 64K elements, and the 
  214.                         limits are -32768..32767.
  215.  
  216.     NOT YET IMPLEMENTED
  217.     
  218.         REAL           The major ommision to this release is the lack of 
  219.                        floating point. The compiler recognises floating point 
  220.                        PASCAL, but is not able to generate any floating point 
  221.                        code. This will be one of the first next items to be 
  222.                        fixed.
  223.     
  224.         ROUTINES as parameters.
  225.                        The standard allows routines to passed a parameters to 
  226.                        other routines. Again the parser recognises it, but 
  227.                        during semantic analysis, strange things could happen.
  228.                    
  229.     BUGS
  230.  
  231.         To many to report here. That is why this version is an ALPHA release.
  232.         There are several flaws in the code generation. And although many case 
  233.         have been tested in isolation, complex situations can cause wrong code 
  234.         to be generated.
  235.         Please report these to the author, so that they can be fixed. 
  236.         (Or at least mentioned in the buglist)
  237.     
  238.         The compiler is sometimes able to recognise the fact that it is in an
  239.         inconsistent state. Or worse, it could even dump core :-(
  240.         Then usually strange looking text is written to the screen.
  241.         This output, your input, and possibly the core dump, can be of help to 
  242.         me. Prefably stripped to the smallest code-chunk which still exhibits 
  243.         the behaviour.
  244.     
  245.         
  246.         These messages can look like:
  247.                  "Houston, Code generation problem.
  248.                   Program aborted."
  249.             Or:
  250.                  "Houston, we've got a serious problem with the register 
  251.                       allocation.
  252.                   Program aborted."
  253.  
  254.         Which means that yor programmed a program sequence which confuses the
  255.         codegenerator part of the compiler. This should not happen, so it is
  256.         a compiler bug. Please report this bug.
  257.         Sometimes it is possible to rewrite the expression or statement 
  258.         causing the trouble. But you'll have to locate the cullpit.
  259.         
  260.         On several places in the runtime library are tests on the outcome of
  261.         systemcalls. If they fail, a message with that regard is printed on 
  262.         'stderr'.
  263.   
  264.         During execution, traps can occur. Usually this means that either 
  265.         pointers or array accesses have been outside the current allowed space.
  266.         Eg:
  267.             core dumped
  268.             SYS1808:
  269.             The process has stopped.  The software diagnostic
  270.             code (exception code) is  0005.
  271.         
  272.         These could be compiler errors, but lately I haven't found many of 
  273.         those that showed in this blunt way. Usually/un fortunately compiler 
  274.         errors show more 'secretly'.
  275.     
  276.     DEFAULTS    
  277.         
  278.         Default stack size is set to 128 Kb, which can be modified in 
  279.         passtart.asm.
  280.         Default heap size is set to 1 Mb, but can be changed by recompiling 
  281.         the 'heaplib.pas' code which is part of the runtime environment.
  282.     
  283.     ENVIRONMENT
  284.  
  285.         PASCAL for OS/2 was generated using Cocktail compiler tools, 
  286.         and compiled using the EMX/GCC. So the runtime environment for the 
  287.         compiler has to include the EMX runtime environment. In 'install.emx' 
  288.         is documentation available on how to install the EMX-run time system.
  289.         A reduced release of required tools is available in 'emxpc.zip'
  290.         
  291.         The PASCAL compiler itself only uses two environment variables:
  292.         TMP                     The location for intermediate files.
  293.                                 Note that this directory has to exist.
  294.         PAS_INC                 This path will be included in the seachpath for
  295.                                 the preprocessor.
  296.     
  297.         But the linker can use others as well:
  298.         LIB                     The path used by LINK386 for libraries.                        
  299.         PAS_LIB                 The path where additional libraries can be 
  300.                                 found for the linker. (currently ignored)
  301.         LIBRARY_PATH            GNU/GAS libraries need to go into the 
  302.                                 directory given by this env-variable.
  303.  
  304.     RUNTIME LIBRARY
  305.                             
  306.         The source for the runtime library is included in the package. It is 
  307.         the part which is least severly tested. I has several problem areas in 
  308.         it, but for most average programming it should work.
  309.         One is always free to go through the runtime library code and modify it 
  310.         to fit ones own requirements. If these changes are usefull to others as 
  311.         well I'd be more than willing to include them in a new release.
  312.     
  313.         The area with most problems in INPUT from an interactive file (eg.: 
  314.         input), since different pascal compilers have different kind of 
  315.         behaviour. TurboPascal nowhere nearly complies with the standard, and 
  316.         as such is it currently hard to mimic it's behaviour.
  317.         [ Unless ofcourse, you are of the opinion that TurboPascal is the 
  318.           standard :-( ]
  319.     
  320.     FILES
  321.         
  322.         .pas .p                  pascal source files
  323.         .inc .hp .hs             assembler or pascal include files
  324.         .i                       pascal preprocessed files
  325.         .asm .s .S               assembler sources
  326.         .obj                     MASM/ML object files
  327.         .o                       GNU/GAS object files
  328.         .lib .a                  Library files
  329.         /tmp/pc????              Temporary files
  330.         
  331.     AUTHOR
  332.         
  333.         Willem Jan Withagen.                      phone: +31-(0)40-473401
  334.         Eindhoven University of Technology        fax:   +31-(0)40-474702
  335.         Room 10.35                                Email: wjw@eb.ele.tue.nl
  336.         PO Box 513
  337.         5600 MB Eindhoven
  338.         The Netherlands
  339.  
  340.     ORIGINAL SOURCE
  341.         
  342.         The most current release of this compiler should always be available
  343.         from:
  344.                   ftp.eb.ele.tue.nl:/pub/src/pascal/pasos2?.zip    
  345.         
  346.         where '?' represents the most recent version.           
  347.     Source are not (yet) available.
  348.  
  349.     EMX
  350.         EMX is available from:
  351.                   ftp.eb.ele.tue.nl:/pub/pc/emx-0.8?
  352.  
  353.     SEE ALSO
  354.  
  355.         Kathleen Jensen and Niklaus Wirth.
  356.         Pascal User and Reference Manual
  357.         Springer Verlag, second edition, 1974.
  358.  
  359.         British Standards Institution.
  360.         Specification fo computer programming language PASCAL, 1984.
  361.         ISO 7185 / BS 6192.
  362.     
  363.         Willem Jan Withagen
  364.         A flexible frontend for a PASCAL compiler
  365.         Technical report Eindhoven University of technology
  366.         ftp: ftp.eb.ele.tue.nl:/pub/src/pascal/frontend.*
  367.     
  368.