4.1cBSD/usr/doc/pascal/pc.1.sue

.TH PC 1
.UC 4
.SH NAME
pc \- Pascal compiler
.SH SYNOPSIS
.B pc
[ option ] [
.B \-i
name ...
] name ...
.SH DESCRIPTION
.I Pc
is a Pascal compiler.
It accepts several types of files as arguments.
Files whose names have the form
.IR name .p
are taken to be Pascal source files;
they are compiled and each  
object file is left in a corresponding file
.IR name .o
Files whose names have the form
.IR name .o
are passed through to the binding phase of the compiler.
If only a single `.p' file is specified,
it is compiled and loaded,
and the `.o' file is deleted.
Files whose name  have the form
.IR name .s
are treated exactly as `.p' files,
except that they are assembled as assembler-language source
rather than being compiled as Pascal source.
.PP
Portions of a Pascal program which constitute
a sequence of \fBlabel\fR, \fBconst\fR and \fBtype\fR definitions,
\fBvar\fR, \fBprocedure\fR and \fBfunction\fR declarations
can be grouped together as a
.B segment
and separately compiled into a `.o' file.
If more than one separately segment
uses the same global definition or declaration,
then that definition or declaration must be contained
in a separate header file with the extension `.h',
rather than in one of the segments.
Each Pascal source segment using the common defintion or declaration
must \fBinclude\fR the header file containing it.
In the header files, functions and procedures to be separately compiled
are declared \fBexternal\fR in much the same way that they are
declared \fBforward\fR in a single file Pascal program.
The full procedure or function declaration is contained in a segment.
.I Pc
treats source files containing \fBinclude\fRd header files as if
the \fBlabel\fR, \fBconst\fR, \fBtype\fR, \fBvar\fR, \fBprocedure\fR and
\fBfunction\fR sections of the headers were merged with the corresponding
sections in the segment.
Reordering or multiple instances of these sections causes a
warning message but compilation continues.
.PP
Segments which are not programs, i.e., have no program body,
can be compiled using the 
.B \-c
option, which inhibits the binding/loading phase.
If that option is not used, exactly one of the files given in the
argument list must supply a \fBprogram\fR.
The other files are segments which are logically merged into the
program and which provide routine bodies for all the
\fBprocedure\fRs and \fBfunction\fRs which were declared
\fBexternal\fR.
External routines written in
.I C
may also be used;
value and var parameters are mapped to
.I C
conventions in the
obvious way.
.PP
The binding phase insures that the segments make consistent use
of definitions from header files, by checking that all segments
are compiled with the same version of each header file.
Consequently, separate compilation cannot subvert the type
consistency rules of Pascal.
The binding/loading phase produces an executable file,
which is named
.B a.out
unless renamed by the 
.B \-o
option.
.PP
Further details are contained in the
.IR "Berkeley Pascal User's Manual" .
.PP
The following options have the same meaning as in
.IR cc (1)
and
.IR f77 (1).
See
.IR ld (1)
for load-time options.
.TP 6
.B \-c
Suppress loading and produce `.o' files for the source file.
.TP 6
.B \-g
Have the compiler produce additional symbol table information for
.IR sdb (1).
.TP 6
.BR \-w
Suppress warning messages.
.TP 6
.B \-p
Prepare object files for profiling, see
.IR  prof (1).
.TP 6
.SM
.B \-O
Invoke an
object-code improver.
.TP 6
.SM
.B \-S
Compile the named program, and leave the
assembler-language output on the corresponding file suffixed `.s'.
(No `.o' is created.).
.TP 6
.BR \-o " output"
Name the final output file
.I output
instead of
.I a.out.
.PP
The following options are peculiar to
.IR pc .
.TP 6
.B \-C
Compile code to perform runtime checks,
verify
.B assert
statements,
and initialize all variables to zero as in
.IR pi .
.TP 6
.B  \-b
Block buffer the file
.I output.
.TP 6
.B  \-i
Produce a listing for
the specified procedures, functions and
.B include
files.
.TP 6
.B  \-l
Make a program listing during translation.
.TP 6
.B  \-s
Accept standard Pascal only;
non-standard constructs cause warning diagnostics.
.TP 6
.B  \-z
Allow execution profiling with
.I pxp
by generating statement counters, and arranging for the
creation of the profile data file
.I pmon.out
when the resulting object is executed.
.PP
Other arguments
are taken
to be either loader option arguments, or
.I pc
compatible object programs, typically produced by an earlier run,
or perhaps libraries of
.I pc
compatible routines.
These programs, together with the results of any
compilations specified, are loaded (in the order
given) to produce an executable program.
Certain flags can also be controlled in comments within the program
as described in the
.I "Berkeley Pascal User's Manual."
.SH FILES
.ta 2i
file.p	pascal source files
.br
file.h	\fBinclude\fR file(s)
.br
/usr/lib/pc[01]	compiler and code generator
.br
/usr/lib/pc2	procedure/function integrator (inline-expansion)
.br
/lib/c2	peephole optimizer
.br
/usr/lib/pc3	separate compilation consistency checker
.br
/usr/lib/pc2.0strings	text of the error messages
.br
/usr/lib/how_pc	basic usage explanation
.br
/usr/lib/libpc.a	intrinsic functions and I/O library
.br
/usr/lib/libm.a	math library
.br
/lib/libc.a	standard library, see intro (3)
.SH "SEE ALSO"
Berkeley Pascal User's Manual
.br
pi(1),
pxp(1),
pxref(1),
sdb(1)
.SH DIAGNOSTICS
For a basic explanation do
.IP
.B pc
.PP
See 
.IR pi (1).
for an explanation of the error message format.
Internal errors cause messages containing the word SNARK.
.SH AUTHORS
Charles B. Haley, William N. Joy, and Ken Thompson
.br
Retargetted to the second pass of the portable
.I C
compiler by Peter Kessler
.br
Runtime library and inline optimizer by M. Kirk McKusick
.br
Separate compilation consistency checking by Louise Madrid
.SH BUGS
The keyword
.B packed
is recognized but has no effect.
.PP
Because the -s option is used by the compiler,
it is not possible to pass the strip option to the loader.
Thus programs which are to be stripped, must be run through 
.IR strip (1)
after they are compiled.