4.4BSD/usr/src/usr.bin/pascal/pc/pc.1
.\" Copyright (c) 1980, 1990, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)pc.1 8.1 (Berkeley) 6/6/93
.\"
.Dd June 6, 1993
.Dt PC 1
.Os BSD 4
.Sh NAME
.Nm \&pc
.Nd Pascal compiler
.Sh SYNOPSIS
.Nm \&pc
.Op option
.Op Fl i Ar name \&...
.Ar name \&...
.Sh DESCRIPTION
.Nm \&Pc
is a Pascal compiler.
If given an argument file ending with
.Pa \&.p ,
it will compile the file
and load it
into an executable file called, by default,
.Pa a.out .
.Pp
A program may be separated into more than one
.Pa \&.p
file.
.Nm \&Pc
will compile a number of argument
.Pa \&.p
files into object files (with
the extension
.Pa \&.o
in place of
.Pa \&.p ) .
Object files may then be loaded
into an executable
.Pa a.out
file.
Exactly one object file must supply a
.Ar program
statement to successfully create an executable a.out file.
The rest of the files must consist only of
declarations which logically nest within the program.
References to objects shared between separately compiled files
are allowed if the objects are declared in
.Ic included
header files, whose names must end with
.Pa \&.h .
Header files may only be included at the outermost level,
and thus declare only globally available objects.
To allow
.Ic function Ns s
and
.Ic procedure Ns s
to be declared, an
.Ic external
directive has been added, whose use is similar to the
.Ic forward
directive but restricted to appear only in
.Pa \&.h
files.
.Ic Function
and
.Ic procedure
bodies may not appear in
.Pa \&.h
files.
A binding phase of the compiler checks that declarations
are used consistently, to enforce the type checking rules of Pascal.
.Pp
Object files
created by other language processors may be loaded together with
object files created by
.Nm \&pc .
The
.Ic function Ns s
and
.Ic procedure Ns s
they define must have been declared
in
.Pa \&.h
files included by all the
.Pa \&.p
files which call those
routines.
Calling conventions are as in C,
with
.Ic var
parameters passed by address.
.Pp
See the
.%T "Berkeley Pascal User's Manual"
for details.
.Pp
The following options have the same meaning as in
.Xr cc 1
and
.Xr f77 1 .
See
.Xr \&ld 1
for load-time options.
.Bl -tag -width indent
.It Fl c
Suppress loading and produce `.o' file(s) from source file(s).
.It Fl g
Have the compiler produce additional symbol table information for
.Xr dbx 1 .
.It Fl w
Suppress warning messages.
.It Fl p
Prepare object files for profiling, see
.Xr prof 1 .
.It Fl O
Invoke an
object-code improver.
.It Fl S
Compile the named program, and leave the
assembler-language output on the corresponding file suffixed `.s'.
(No `.o' is created.).
.It Fl o Ns Ar output
Name the final output file
.Ar output
instead of
.Pa a.out .
.El
.Pp
The following options are peculiar to
.Nm pc .
.Bl -tag -width indent
.It Fl C
Compile code to perform runtime checks,
verify
.Ic assert
calls,
and initialize all variables to zero as in
.Nm pi .
.It Fl b
Block buffer the file
.Ar output .
.It Fl i
Produce a listing for
the specified procedures, functions and
.Ar include
files.
.It Fl l
Make a program listing during translation.
.It Fl s
Accept standard Pascal only;
non-standard constructs cause warning diagnostics.
.It Fl t Ar directory
Use the given
.Ar directory
for compiler temporary files.
.It Fl z
Allow execution profiling with
.Nm pxp
by generating statement counters, and arranging for the
creation of the profile data file
.Pa pmon.out
when the resulting object is executed.
.El
.Pp
Other arguments
are taken
to be loader option arguments,
perhaps libraries of
.Nm \&pc
compatible routines.
Certain flags can also be controlled in comments within the program
as described in the
.%T "Berkeley Pascal User's Manual."
.Sh FILES
.Bl -tag -width /usr/lib.pc2.*strings -compact
.It Pa file.p
Pascal source files.
.It Pa /usr/lib/pc0
Compiler.
.It Pa /lib/f1
Code generator.
.It Pa /usr/lib/pc2
Runtime integrator (inline expander).
.It Pa /lib/c2
Peephole optimizer.
.It Pa /usr/lib/pc3
Separate compilation consistency checker.
.It Pa /usr/lib/pc2.*strings
Text of the error messages.
.It Pa /usr/lib/how_pc
Basic usage explanation.
.It Pa /usr/lib/libpc.a
Intrinsic functions and
.Tn I/O
library.
.It Pa /usr/lib/libm.a
Math library.
.It Pa /lib/libc.a
Standard library, see
.Xr intro 3 .
.El
.Sh SEE ALSO
.Xr \&pi 1 ,
.Xr pxp 1 ,
.Xr pxref 1 ,
.Rs
.%T "Berkeley Pascal User's Manual"
.Re
.Sh HISTORY
The
.Nm \&pc
appeared in
.Bx 4.0 .
.Sh DIAGNOSTICS
For a basic explanation do
.Pp
.Bd -literal -offset indent
pc
.Ed
.Pp
See
.Xr \&pi 1 .
for an explanation of the error message format.
Internal errors cause messages containing the word
.Tn SNARK .
.Sh BUGS
The keyword
.Ic packed
is recognized but has no effect.
.Pp
The binder is not as strict as described here,
with regard to the rules about external declarations only
in `.h' files and including `.h' files only at the outermost level.
It will be made to perform these checks in its next incarnation,
so users are warned not to be sloppy.
.Pp
The
.Fl z
flag doesn't work for separately compiled files.
.Pp
Because the
.Fl s
option is usurped 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
.Xr strip 1
after they are compiled.