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