Return to pc68.1 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ucs / sumacc

Annotation of 43BSDReno/share/doc/ucs/sumacc/pc68.1, revision 1.1

1.1     ! root        1: .TH PC68 1 MC68000
        !             2: .SU
        !             3: .SH NAME
        !             4: pc68 \- Pascal compiler for the MC68000
        !             5: .SH SYNOPSIS
        !             6: .B pc68
        !             7: [ option ] name ...
        !             8: .SH DESCRIPTION
        !             9: .I Pc68
        !            10: is the version of the portable Pascal* compiler that generates code for 
        !            11: the MC68000.
        !            12: .I Pc68
        !            13: is a flexible program for translating between various types of files.  The
        !            14: types catered for in order of appearance during translation are `.p' 
        !            15: (Pascal source files), `.a68' or '.s' (assembly language files), 
        !            16: `.b' (relocatable binary files),
        !            17: `b.out' (absolute binary files), `.r' (byte-reversed files, cf.
        !            18: .I rev68(1)
        !            19: ).
        !            20: and `.dl' (Macsbug download format, cf.
        !            21: .I dl68(1)
        !            22: ).
        !            23: .PP
        !            24: Arguments to pc68 are either flags or input files.
        !            25: The type of an input file is normally determined by its suffix.  When an
        !            26: argument to pc68 is not a flag and has none of the above suffixes, it is
        !            27: assumed to be of one of the types `.p', `.b', or `b.out', namely the latest of
        !            28: these three consistent with the type of the output (e.g. if the output type
        !            29: were `.s' or `.b' then the input would have to be `.p').
        !            30: .PP
        !            31: Translation proceeds as follows.  
        !            32: Each `.p' and `.s' program is translated to a `.b' relocatable using upas68, 
        !            33: ugen68, and as68 as necessary.  Then all .b files including those produced by
        !            34: translation are link edited into the one file, called `b.out'.  If the only
        !            35: input file was a single `.p' program then the `.b' file is deleted, otherwise
        !            36: all `.b' files are preserved.
        !            37: .PP
        !            38: The amount of processing performed by cc68 may be decreased or increased with
        !            39: some of the options.  The -S option takes translation no further than `.s'
        !            40: files, i.e. only upas68 and ugen68 are applied.  
        !            41: The -c option takes translation up to `.b' files, omitting the link-editing 
        !            42: and not deleting any `.b' files.
        !            43: The -d option goes beyond `b.out' to produce a `.dl' file (using dl68) that
        !            44: may be downloaded by the Motorola MACSBUG monitor and the Sun1 monitor.  The
        !            45: -r option similarly goes beyond `b.out' to produce a `.r' file (using rev68)
        !            46: that may be loaded directly by 68000 code based on ld68.  Both -d and -r may
        !            47: be used together.
        !            48: .PP
        !            49: The output may be named explicitly with the -o option; the output file's name
        !            50: should follow -o.  Otherwise the name is `b.out' in the normal case, or
        !            51: `filename.dl' for the -d option, or `filename.r' for the -r option, where
        !            52: `filename' is the first `.p', `.a68', `.s', or `.b' file named as an input.  
        !            53: If the input is not in any of those three categories, the names `d.out' 
        !            54: and `r.out' are used respectively for -d and -r.
        !            55: .PP
        !            56: The version of the target machine may be given as the flag
        !            57: .BI \-v n
        !            58: where 
        !            59: .I n
        !            60: is the version.
        !            61: -vm is "Version Macsbug."
        !            62: -vV means to run under the Vkernal. This is pretty much a hack:
        !            63: File I/O is not supported and you can't refer to C routines
        !            64: containing upper-case letters in their names.
        !            65: It's also rather minimally tested.
        !            66: .PP
        !            67: A complete list of options interpreted by pc68 follows:
        !            68: .TP 6
        !            69: \#flag
        !            70: Pass
        !            71: .I flag
        !            72: to the compiler. See the SOURCE FLAGS section below.
        !            73: .TP 6
        !            74: .B \-c
        !            75: Suppress loading and produce `.b' file(s) from source file(s).
        !            76: .TP 6
        !            77: .B \-g
        !            78: Have the compiler produce additional symbol table information for
        !            79: .IR pcdb68
        !            80: (not implemented).
        !            81: .TP 6
        !            82: .B \-e " entrypoint"
        !            83: Entrypoint specifies where to begin execution.
        !            84: .TP 6
        !            85: .BR \-o " output"
        !            86: Name the final output file
        !            87: .I output
        !            88: instead of
        !            89: .I b.out.
        !            90: .TP 6
        !            91: .B  \-s
        !            92: Accept standard Pascal only;
        !            93: non-standard constructs cause warning diagnostics (not implemented \- see 
        !            94: internally controlled options).
        !            95: .TP 6
        !            96: .B  \-v n
        !            97: Use the 'n' version of the runtime support.
        !            98: .TP 6
        !            99: .BR \-w
        !           100: Suppress warning messages (not implemented).
        !           101: .TP 6
        !           102: .B \-\-x
        !           103: Suppress passing the '\-x' flag to the loader, retaining local symbols.
        !           104: .TP 6
        !           105: .B \-E
        !           106: Run only the preprocessor (not implemented).
        !           107: .TP 6
        !           108: .B  \-L
        !           109: Make an assembly listing in filename.ls for each file assembled.
        !           110: .TP 6
        !           111: .SM
        !           112: .B \-O
        !           113: Invoke an
        !           114: object-code improver (not implemented).
        !           115: .TP 6
        !           116: .B  \-R
        !           117: Preserve relocation information in b.out.
        !           118: .TP 6
        !           119: .SM
        !           120: .B \-S
        !           121: Compile the named program, and leave the
        !           122: assembler-language output on the corresponding file suffixed `.s'.
        !           123: (No `.b' is created.).
        !           124: .TP 6
        !           125: .B \-T " org"
        !           126: Org specifies in hexadecimal where to begin loading the program.
        !           127: .TP 6
        !           128: .B \-V
        !           129: Show the various stages of the compilation by printing images of the processes
        !           130: forked off to perform the actual work of the compilation.
        !           131: .TP 6
        !           132: .B \-U
        !           133: Save the ucode associated with filname.p in filename.u (and filename.z,
        !           134: depending on the -W option).
        !           135: .TP 6
        !           136: .B \-W
        !           137: Invoke the global ucode-to-ucode optimizer.  If -U option active, generates
        !           138: filename.z.
        !           139: .TP 6
        !           140: .B \-P
        !           141: Save all intermediate files.  Most useful in conjuntion with \-V (so that it
        !           142: is possible to find the intermediates).
        !           143: .PP
        !           144: Other arguments
        !           145: are taken
        !           146: to be loader option arguments,
        !           147: perhaps libraries of
        !           148: .IR pc68
        !           149: compatible routines.
        !           150: .SH SEPARATE COMPILATION
        !           151: Object files 
        !           152: created by other language processors may be loaded together with
        !           153: object files created by 
        !           154: .IR pc68 .
        !           155: Calling conventions are as in C,
        !           156: with
        !           157: .B var
        !           158: parameters and arrays passed by address.
        !           159: Don't pass structures except by VAR (pointer) if you call C, since here
        !           160: pc68 and cc68 differ.
        !           161: As a convenience, string constants are followed by a zero byte, so that you
        !           162: can use them as C strings when calling C routines.
        !           163: .PP
        !           164: To refer to a subroutine defined in a separate module, it must be declared.
        !           165: This follows the same syntax as
        !           166: .B forward
        !           167: declarations, except that the keyword
        !           168: .B FORWARD
        !           169: is replaced by
        !           170: .B EXTERN .
        !           171: .PP
        !           172: A file of subroutines is similar to a program except that there
        !           173: is no main program, and the
        !           174: .B program
        !           175: statement at the beginning of the file is replaced by a
        !           176: .b module
        !           177: statement:
        !           178: .br
        !           179:    MODULE modulename;
        !           180: .br
        !           181: The 'end;' of the last function in the file is followed by a period -
        !           182: there is no main program block.
        !           183: .br
        !           184: The modulename will become significant in Pascal*.
        !           185: .pp
        !           186: Note that in identifiers (such as subprogram names) upper case is
        !           187: changed to lower case, and the linker is asked to ignore case.
        !           188: 
        !           189: .SH OPENING FILES
        !           190: 
        !           191: To open a file for both input and output, use the standard
        !           192: procedure REVISE, which is analogous with RESET and REWRITE.
        !           193: NOT TESTED.
        !           194: .sp
        !           195: You can read and write files on machines which run a Leaf server.
        !           196: To open  a file for reading do:
        !           197: .sp
        !           198:    reset(file,'[hostname:username:password]filename');
        !           199: .sp
        !           200: The same syntax applies to rewrite.
        !           201: You can of course also use a Pascal string variable.
        !           202: Terminating spaces in hostname, username and password are ignored.
        !           203: (This should make it easier for a program to construct the appropriate
        !           204: filename string.)
        !           205: .sp
        !           206: You can leave out fields (or the entire second parameter), and the
        !           207: program will assume you want the same as before.
        !           208: If there is no "before", it will ask you.
        !           209: .sp
        !           210: Reset, Rewrite and Revise may have an optional third parameter,
        !           211: which is a string of switches. E.g.:
        !           212: .br
        !           213:     Reset(Input,'data1.txt','Nofilter;Prompt:"Try again!"');
        !           214: .sp
        !           215: Standard switches are:
        !           216: .br
        !           217:  - Prompt:  The string  is used as  a prompt  (interactive
        !           218: systems only).   If  a file  name  is NOT  given,  this
        !           219: prompt is used to get the file name from the user.   If
        !           220: one IS given (like in the example above), the prompt is
        !           221: used to get another file name from the user if the file
        !           222: can't be opened.
        !           223: .br
        !           224:  - Default:  The string is used are used as a default file
        !           225: name, which is used if the user types a carriage return
        !           226: in response to the prompt.
        !           227: .br
        !           228:  - Standard:  If Reset, the standard input file  is  used.
        !           229: If Rewrite, the standard output is used.
        !           230: .br
        !           231:  - Nofilter:    (Reset, Revise only.) Normally a text file
        !           232: is 'filtered' by the runtimes so that  it  conforms  to
        !           233: the  standard  Pascal  definition of a text file.  Most
        !           234: notably, any end-of-line characters  are  changed  into
        !           235: one  space.    The  inclusion  of  Nofilter  causes all
        !           236: characters to be passed through exactly as they  appear
        !           237: in  the  text file.  Eoln, Eopage and Readln still work
        !           238: as for standard files.
        !           239: 
        !           240: .SH EXTENSIONS TO READ AND WRITE
        !           241: 
        !           242: For all field widths (if there are two field-width-type
        !           243: parameters,  the first one only), a negative value will
        !           244: mean  that  the  value  written  will  be  left-aligned
        !           245: instead  of  right-aligned.    For string variables, if
        !           246: Abs(Fieldwidth)  <  Length,  then   the   last   Length
        !           247: - Abs(Fieldwidth) characters  of  the  string  will  be 
        !           248: written.
        !           249: .sp
        !           250: Variables  of enumerated types may be read and written.
        !           251: The field width is interpreted the same as for strings.
        !           252: Enumerated constant names are uppercased when they  are
        !           253: read in.
        !           254: .sp
        !           255: Sets  of  readable and writeable types may also be read
        !           256: and written.  They  appear  exactly  as  set  constants
        !           257: appear   in  Pascal  programs.    The  field  width  is
        !           258: interpreted for each element the same as  it  would  be
        !           259: for    the   set   element   type.
        !           260: .sp
        !           261: Integers may be written in other bases beside  base  10
        !           262: by  including  an  optional field-width-type parameter,
        !           263: which may be anywhere from 1..16.  The field  width  is
        !           264: the  same  as  for  base 10.  Integers may also be read
        !           265: from a file in other  than  base  10,  by  including  a
        !           266: field-width-type  parameter  in  the  call  to  Read or
        !           267: Readln.
        !           268: .sp
        !           269: Real numbers may have a capital  "E"  as  well  as  the
        !           270: standard small "e" in the exponent part.
        !           271: 
        !           272: .SH MORE ABOUT INPUT-OUTPUT
        !           273: Lazy lokahead is used for text files, so that terminal input
        !           274: works reasonably.
        !           275: .sp
        !           276: The procedure Eopage is true iff a page marker has just been read, and
        !           277: the corresponding space in now in the file buffer.
        !           278: .sp
        !           279: Random-access in files is done with the standard procedure
        !           280: .br
        !           281:     seek (File, N);
        !           282: .br
        !           283: This positions the file so that the next read/write will apply
        !           284: to component no. N of the file.
        !           285: .sp
        !           286: To close a file immediately do: close(file);
        !           287: .sp
        !           288: Function Filesize (var Filevar: Anyfile): 0..Maxint  
        !           289: returns the current number of components in a file.
        !           290: .sp
        !           291: Function Curpos (var Filevar: Anyfile): 0..Maxint:  Returns the
        !           292: current file position.
        !           293: .sp
        !           294: Procedure Filepos (var Filevar:  Text; var Pagenum, Linenum, Charnum: 0..Maxint):
        !           295: Returns page, line number, and column number of the next
        !           296: character that will be read from the file (must be open for input).
        !           297: Does not work for random access.
        !           298: 
        !           299: .SH TIME AND DATE ROUTINES
        !           300: .nf
        !           301:     Clock -returns milli-seconds since the monitor was booted.
        !           302: .fi
        !           303: .sp
        !           304: The following routines routines don't work if you want to run stand-alone,
        !           305: but need an operating system (V or Unix).
        !           306: .nf
        !           307: 
        !           308:     Ptime -returns (in theory) milli-seconds since midnight.
        !           309:     (under V, actually returns seconds*1000)
        !           310: 
        !           311:     Pdate(day, month, year) -set day, month & year (say 1982).
        !           312: 
        !           313:     Time(string) -sets string to 'HH:MM:SS'
        !           314: 
        !           315:     Date(string) -sets string to 'MM/DD/YY'.
        !           316: .fi
        !           317: For both time and date, the string is a packed array [1..n] of char,
        !           318: where n>=8. (Any overflow is set to spaces.)
        !           319: 
        !           320: .SH OTHER EXTENSIONS AND FEATURES
        !           321: An "others" label in as CASE statement, indicates a default case.
        !           322: .sp
        !           323: To include a file as part of the program source do:
        !           324: .br
        !           325:     INCLUDE 'filename';
        !           326: .br
        !           327: This is especially useful for declarations for
        !           328: seperately compiled modules.
        !           329: .sp
        !           330: Records declared as "packed" will be packed down to individual bits;
        !           331: however elements of packed arrays are at least a byte.
        !           332: .sp
        !           333: Function Min (X,Y:  T):  T -- returns the minimum of two arguments,
        !           334: which may be of any ordinal or real type.
        !           335: .sp
        !           336: Function Max (X,Y:  T):  T -- returns the maximum of two arguments.
        !           337: .sp
        !           338: Procedure Halt (Exitcode:  Integer):  Causes abnormal termaination of
        !           339: a program.  Passes a system-dependent exit code to the operating system.
        !           340: .sp
        !           341: The comment pairs '{ }' and '(* *) match independently, allowing
        !           342: limited nesting of comments.
        !           343: 
        !           344: .SH "SOURCE FLAGS"
        !           345: .PP
        !           346: These flags can be passed to the compiler either at the command
        !           347: level when invoking pc68, or as comments within the program.
        !           348: A sample option line is a comment with # as its first character:
        !           349: .ta 1.5i 3.0i
        !           350: .nf
        !           351: .na
        !           352: Sample option line: (*#g+,tdpy 1,tchk 1,U-8 *)
        !           353: WARNING: Only (* *)-style comments will work; {#...} is ignored!
        !           354: Sample command line: pc68 file.p #g:+ #tdpy:1 #tchk:1 #U:-8
        !           355: .sp
        !           356: .b
        !           357: Switch Meaning (Note that the default value is shown)
        !           358: 
        !           359: B+     Bounds and nil pointer checking
        !           360: C+     Print ucode
        !           361: D-     Load with debugger
        !           362: E+     Emit source code (for system debugging)
        !           363: G-     Write error messages only to listing file
        !           364: L-     Write full listing
        !           365: I16    Number of characters of identifiers that
        !           366:          are considered significant
        !           367: O-     Emit optimizer-compatible code
        !           368: P-     Keep execution profile
        !           369: R0     Put up to N local variables in (data) registers
        !           370:        (Register allocation should be done by the optimizer.)
        !           371: S-     Accept standard Pascal only
        !           372: T---   Code generator options 
        !           373: U+     Leave procedure names exactly as is
        !           374: V32    Number of bits (16 or 32) to allocate for 'Integer'.
        !           375: Wn     PRINT WARNINGS FOR:
        !           376: W1       unused variables, types, procs, etc.
        !           377: W10      nested comments
        !           378: Z---   Optimizer switches
        !           379: .fi
        !           380: .ad
        !           381: .SH FILES
        !           382: file.p pascal source files
        !           383: .br
        !           384: file.b binary files
        !           385: .br
        !           386: file.a68       assembler files
        !           387: .br
        !           388: file.s assembler files  
        !           389: .br
        !           390: file.ls        assembler listing
        !           391: .br
        !           392: file.err       pascal listing
        !           393: .SH BUGS
        !           394: Displacements off a frame pointer is limited to 16 bits signed,
        !           395: so very large locally-defined arrays will crash.
        !           396: .sp 2
        !           397: Some attempted bogus conversions (e.g. structure to real) aren't detected
        !           398: by the front end, and result in messages about 'Illegal CVT datatypes'
        !           399: from the code generator.
        !           400: .sp 2
        !           401: Sometimes formfeeds in the source get passed to the assembler, causing it to crash.
        !           402: .sp 2
        !           403: There is no macro processor.
        !           404: .SH GRIPES
        !           405: Complaints should be sent to:
        !           406: .br
        !           407:     Per Bothner (mail to bothner@score)
        !           408: .sp
        !           409: There is also a pc68 mailing list. To add yourself to it, send a
        !           410: message to mailer@su-whitney. The first line of the message body
        !           411: should say:
        !           412: .br
        !           413:    add me to pc68
        !           414: .sp
        !           415: To say messages to to list, mail to pc68 at shasta, diablo,
        !           416: navajo or whitney.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.