* Moved lcc and q3asm into code/tools
This commit is contained in:
Tim Angus
parent
b1cef6352e
commit
ad118b9baf
452 changed files with 0 additions and 0 deletions
605
code/tools/lcc/doc/lcc.1
Normal file
605
code/tools/lcc/doc/lcc.1
Normal file
|
|
@ -0,0 +1,605 @@
|
|||
.\" $Id: lcc.1 145 2001-10-17 21:53:10Z timo $
|
||||
.TH LCC 1 "local \- $Date: 2001-10-17 16:53:10 -0500 (Wed, 17 Oct 2001) $"
|
||||
.SH NAME
|
||||
lcc \- ANSI C compiler
|
||||
.SH SYNOPSIS
|
||||
.B lcc
|
||||
[
|
||||
.I option
|
||||
|
|
||||
.I file
|
||||
]...
|
||||
.br
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
.I lcc
|
||||
is an ANSI C compiler for a variety of platforms.
|
||||
.PP
|
||||
Arguments whose names end with `.c' (plus `.C' under Windows) are taken to be
|
||||
C source programs; they are preprocessed, compiled, and
|
||||
each object program is left on the file
|
||||
whose name is that of the source with `.o' (UNIX) or `.obj' (Windows)
|
||||
substituted for the extension.
|
||||
Arguments whose names end with `.i' are treated similarly,
|
||||
except they are not preprocessed.
|
||||
In the same way,
|
||||
arguments ending with `.s' (plus `.S', `.asm', and `.ASM', under Windows)
|
||||
are taken to be assembly source programs
|
||||
and are assembled, producing an object file.
|
||||
If there are no arguments,
|
||||
.I lcc
|
||||
summarizes its options on the standard error.
|
||||
.PP
|
||||
.I lcc
|
||||
deletes an object file if and only if exactly one
|
||||
source file is mentioned and no other file
|
||||
(source, object, library) or
|
||||
.B \-l
|
||||
option is mentioned.
|
||||
.PP
|
||||
If the environment variable
|
||||
.B LCCINPUTS
|
||||
is set,
|
||||
.I lcc
|
||||
assumes it gives a semicolon- or colon-separated list of directories in which to
|
||||
look for source and object files whose names do not begin with `/'.
|
||||
These directories are also added to the list of directories
|
||||
searched for libraries.
|
||||
If
|
||||
.B LCCINPUTS
|
||||
is defined, it must contain `.' in order for the current directory
|
||||
to be searched for input files.
|
||||
.PP
|
||||
.I lcc
|
||||
uses ANSI standard header files (see `FILES' below).
|
||||
Include files not found in the ANSI header files
|
||||
are taken from the normal default include areas,
|
||||
which usually includes
|
||||
.BR /usr/include .
|
||||
Under Windows, if the environment variable
|
||||
.B include
|
||||
is defined, it gives a semicolon-separated list of directories in which to search for
|
||||
header files.
|
||||
.PP
|
||||
.I lcc
|
||||
interprets the following options; unrecognized options are
|
||||
taken as loader options (see
|
||||
.IR ld (1))
|
||||
unless
|
||||
.BR \-c ,
|
||||
.BR \-S ,
|
||||
or
|
||||
.B \-E
|
||||
precedes them.
|
||||
Except for
|
||||
.BR \-l ,
|
||||
all options are processed before any of the files
|
||||
and apply to all of the files.
|
||||
Applicable options are passed to each compilation phase in the order given.
|
||||
.TP
|
||||
.B \-c
|
||||
Suppress the loading phase of the compilation, and force
|
||||
an object file to be produced even if only one program is compiled.
|
||||
.TP
|
||||
.B \-g
|
||||
Produce additional symbol table information for the local debuggers.
|
||||
.I lcc
|
||||
warns when
|
||||
.B \-g
|
||||
is unsupported.
|
||||
.TP
|
||||
.BI \-Wf\-g n , x
|
||||
Set the debugging level to
|
||||
.I n
|
||||
and emit source code as comments into the generated assembly code;
|
||||
.I x
|
||||
must be the assembly language comment character.
|
||||
If
|
||||
.I n
|
||||
is omitted, it defaults to 1, which is similar to
|
||||
.BR \-g .
|
||||
Omitting
|
||||
.BI , x
|
||||
just sets the debugging level to
|
||||
.IR n .
|
||||
.TP
|
||||
.B \-w
|
||||
Suppress warning diagnostics, such as those
|
||||
announcing unreferenced statics, locals, and parameters.
|
||||
The line
|
||||
.I
|
||||
#pragma ref id
|
||||
simulates a reference to the variable
|
||||
.IR id .
|
||||
.TP
|
||||
.BI \-d n
|
||||
Generate jump tables for switches whose density is at least
|
||||
.IR n ,
|
||||
a floating point constant between zero and one.
|
||||
The default is 0.5.
|
||||
.TP
|
||||
.B \-A
|
||||
Warns about
|
||||
declarations and casts of function types without prototypes,
|
||||
assignments between pointers to ints and pointers to enums, and
|
||||
conversions from pointers to smaller integral types.
|
||||
A second
|
||||
.B \-A
|
||||
warns about
|
||||
unrecognized control lines,
|
||||
nonANSI language extensions and source characters in literals,
|
||||
unreferenced variables and static functions,
|
||||
declaring arrays of incomplete types,
|
||||
and exceeding
|
||||
.I some
|
||||
ANSI environmental limits, like more than 257 cases in switches.
|
||||
It also arranges for duplicate global definitions in separately compiled
|
||||
files to cause loader errors.
|
||||
.TP
|
||||
.B \-P
|
||||
Writes declarations for all defined globals on standard error.
|
||||
Function declarations include prototypes;
|
||||
editing this output can simplify conversion to ANSI C.
|
||||
This output may not correspond to the input when
|
||||
there are several typedefs for the same type.
|
||||
.TP
|
||||
.B \-n
|
||||
Arrange for the compiler to produce code
|
||||
that tests for dereferencing zero pointers.
|
||||
The code reports the offending file and line number and calls
|
||||
.IR abort (3).
|
||||
.TP
|
||||
.B \-O
|
||||
is ignored.
|
||||
.TP
|
||||
.B \-S
|
||||
Compile the named C programs, and leave the
|
||||
assembler-language output on corresponding files suffixed `.s' or `.asm'.
|
||||
.TP
|
||||
.B \-E
|
||||
Run only the preprocessor on the named C programs
|
||||
and unsuffixed file arguments,
|
||||
and send the result to the standard output.
|
||||
.TP
|
||||
.BI \-o " output"
|
||||
Name the output file
|
||||
.IR output .
|
||||
If
|
||||
.B \-c
|
||||
or
|
||||
.B \-S
|
||||
is specified and there is exactly one source file,
|
||||
this option names the object or assembly file, respectively.
|
||||
Otherwise, this option names the final executable
|
||||
file generated by the loader, and `a.out' (UNIX) or `a.exe' (Windows) is left undisturbed.
|
||||
.I lcc
|
||||
warns if
|
||||
.B \-o
|
||||
and
|
||||
.B \-c
|
||||
or
|
||||
.B \-S
|
||||
are given with more than one source file and ignores the
|
||||
.B \-o
|
||||
option.
|
||||
.TP
|
||||
.BI \-D name=def
|
||||
Define the
|
||||
.I name
|
||||
to the preprocessor, as if by `#define'.
|
||||
If
|
||||
.I =def
|
||||
is omitted, the name is defined as "1".
|
||||
.TP
|
||||
.BI \-U name
|
||||
Remove any initial definition of
|
||||
.IR name .
|
||||
.TP
|
||||
.BI \-I dir
|
||||
`#include' files
|
||||
whose names do not begin with `/' are always
|
||||
sought first in the directory of the
|
||||
.I file
|
||||
arguments, then in directories named in
|
||||
.B \-I
|
||||
options, then in directories on a standard list.
|
||||
.TP
|
||||
.B \-N
|
||||
Do not search
|
||||
.I any
|
||||
of the standard directories for `#include' files.
|
||||
Only those directories specified by subsequent explicit
|
||||
.B \-I
|
||||
options will be searched, in the order given.
|
||||
.TP
|
||||
.BI \-B str
|
||||
Use the compiler
|
||||
.BI "" str rcc
|
||||
instead of the default version.
|
||||
Note that
|
||||
.I str
|
||||
often requires a trailing slash.
|
||||
On Sparcs only,
|
||||
.B \-Bstatic
|
||||
and
|
||||
.BI \-Bdynamic
|
||||
are passed to the loader; see
|
||||
.IR ld (1).
|
||||
.TP
|
||||
.BI \-Wo\-lccdir= dir
|
||||
Find the preprocessor, compiler proper, and include directory
|
||||
in the directory
|
||||
.I dir/
|
||||
or
|
||||
.I
|
||||
dir\\.
|
||||
If the environment variable
|
||||
.B LCCDIR
|
||||
is defined, it gives this directory.
|
||||
.I lcc
|
||||
warns when this option is unsupported.
|
||||
.TP
|
||||
.B \-Wf-unsigned_char=1
|
||||
.br
|
||||
.ns
|
||||
.TP
|
||||
.B \-Wf-unsigned_char=0
|
||||
makes plain
|
||||
.B char
|
||||
an unsigned (1) or signed (0) type; by default,
|
||||
.B char
|
||||
is signed.
|
||||
.TP
|
||||
.B \-Wf\-wchar_t=unsigned_char
|
||||
.br
|
||||
.ns
|
||||
.TP
|
||||
.B \-Wf\-wchar_t=unsigned_short
|
||||
.br
|
||||
.ns
|
||||
.TP
|
||||
.B \-Wf\-wchar_t=unsigned_int
|
||||
Makes wide characters the type indicated; by default,
|
||||
wide characters are unsigned short ints, and
|
||||
.B wchar_t
|
||||
is a typedef for unsigned short defined in stddef.h.
|
||||
The definition for
|
||||
.B wchar_t
|
||||
in stddef.h must correspond to the type specified.
|
||||
.TP
|
||||
.B \-v
|
||||
Print commands as they are executed; some of the executed
|
||||
programs are directed to print their version numbers.
|
||||
More than one occurrence of
|
||||
.B \-v
|
||||
causes the commands to be printed, but
|
||||
.I not
|
||||
executed.
|
||||
.TP
|
||||
.BR \-help " or " \-?
|
||||
Print a message on the standard error summarizing
|
||||
.IR lcc 's
|
||||
options and giving the values of the environment variables
|
||||
.B LCCINPUTS
|
||||
and
|
||||
.BR LCCDIR ,
|
||||
if they are defined.
|
||||
Under Windows, the values of
|
||||
.B include
|
||||
and
|
||||
.B lib
|
||||
are also given, if they are defined.
|
||||
.TP
|
||||
.B \-b
|
||||
Produce code that counts the number of times each expression is executed.
|
||||
If loading takes place, arrange for a
|
||||
.B prof.out
|
||||
file to be written when the object program terminates.
|
||||
A listing annotated with execution counts can then be generated with
|
||||
.IR bprint (1).
|
||||
.I lcc
|
||||
warns when
|
||||
.B \-b
|
||||
is unsupported.
|
||||
.B \-Wf\-C
|
||||
is similar, but counts only the number of function calls.
|
||||
.TP
|
||||
.B \-p
|
||||
Produce code that counts the number of times each function is called.
|
||||
If loading takes place, replace the standard startup
|
||||
function by one that automatically calls
|
||||
.IR monitor (3)
|
||||
at the start and arranges to write a
|
||||
.B mon.out
|
||||
file when the object program terminates normally.
|
||||
An execution profile can then be generated with
|
||||
.IR prof (1).
|
||||
.I lcc
|
||||
warns when
|
||||
.B \-p
|
||||
is unsupported.
|
||||
.TP
|
||||
.B \-pg
|
||||
Causes the compiler to produce counting code like
|
||||
.BR \-p ,
|
||||
but invokes a run-time recording mechanism that keeps more
|
||||
extensive statistics and produces a
|
||||
.B gmon.out
|
||||
file at normal termination.
|
||||
Also, a profiling library is searched, in lieu of the standard C library.
|
||||
An execution profile can then be generated with
|
||||
.IR gprof (1).
|
||||
.I lcc
|
||||
warns when
|
||||
.B \-pg
|
||||
is unsupported.
|
||||
.TP
|
||||
.BI \-t name
|
||||
.br
|
||||
.ns
|
||||
.TP
|
||||
.BI \-t
|
||||
Produce code to print the name of the function, an activation number,
|
||||
and the name and value of each argument at function entry.
|
||||
At function exit, produce code to print
|
||||
the name of the function, the activation number, and the return value.
|
||||
By default,
|
||||
.I printf
|
||||
does the printing; if
|
||||
.I name
|
||||
appears, it does.
|
||||
For null
|
||||
.I char*
|
||||
values, "(null)" is printed.
|
||||
.BI \-target
|
||||
.I name
|
||||
is accepted, but ignored.
|
||||
.TP
|
||||
.BI \-tempdir= dir
|
||||
Store temporary files in the directory
|
||||
.I dir/
|
||||
or
|
||||
.I
|
||||
dir\\.
|
||||
The default is usually
|
||||
.BR /tmp .
|
||||
.TP
|
||||
.BI \-W xarg
|
||||
pass argument
|
||||
.I arg
|
||||
to the program indicated by
|
||||
.IR x ;
|
||||
.I x
|
||||
can be one of
|
||||
.BR p ,
|
||||
.BR f ,
|
||||
.BR a ,
|
||||
or
|
||||
.BR l ,
|
||||
which refer, respectively, to the preprocessor, the compiler proper,
|
||||
the assembler, and the loader.
|
||||
.I arg
|
||||
is passed as given; if a
|
||||
.B \-
|
||||
is expected, it must be given explicitly.
|
||||
.BI \-Wo arg
|
||||
specifies a system-specific option,
|
||||
.IR arg .
|
||||
.PP
|
||||
Other arguments
|
||||
are taken to be either loader option arguments, or C-compatible
|
||||
object programs, typically produced by an earlier
|
||||
.I lcc
|
||||
run, or perhaps libraries of C-compatible routines.
|
||||
Duplicate object files are ignored.
|
||||
These programs, together with the results of any
|
||||
compilations specified, are loaded (in the order
|
||||
given) to produce an executable program with name
|
||||
.BR a.out
|
||||
(UNIX) or
|
||||
.BR a.exe
|
||||
(Windows).
|
||||
.PP
|
||||
.I lcc
|
||||
assigns the most frequently referenced scalar parameters and
|
||||
locals to registers whenever possible.
|
||||
For each block,
|
||||
explicit register declarations are obeyed first;
|
||||
remaining registers are assigned to automatic locals if they
|
||||
are `referenced' at least 3 times.
|
||||
Each top-level occurrence of an identifier
|
||||
counts as 1 reference. Occurrences in a loop,
|
||||
either of the then/else arms of an if statement, or a case
|
||||
in a switch statement each count, respectively, as 10, 1/2, or 1/10 references.
|
||||
These values are adjusted accordingly for nested control structures.
|
||||
.B \-Wf\-a
|
||||
causes
|
||||
.I lcc
|
||||
to read a
|
||||
.B prof.out
|
||||
file from a previous execution and to use the data therein
|
||||
to compute reference counts (see
|
||||
.BR \-b ).
|
||||
.PP
|
||||
.I lcc
|
||||
is a cross compiler;
|
||||
.BI \-Wf\-target= target/os
|
||||
causes
|
||||
.I lcc
|
||||
to generate code for
|
||||
.I target
|
||||
running the operating system denoted by
|
||||
.IR os .
|
||||
The supported
|
||||
.I target/os
|
||||
combinations may include
|
||||
.PP
|
||||
.RS
|
||||
.ta \w'sparc/solarisxx'u
|
||||
.nf
|
||||
alpha/osf ALPHA, OSF 3.2
|
||||
mips/irix big-endian MIPS, IRIX 5.2
|
||||
mips/ultrix little-endian MIPS, ULTRIX 4.3
|
||||
sparc/solaris SPARC, Solaris 2.3
|
||||
x86/win32 x86, Windows NT 4.0/Windows 95/98
|
||||
x86/linux x86, Linux
|
||||
symbolic text rendition of the generated code
|
||||
null no output
|
||||
.fi
|
||||
.RE
|
||||
.PP
|
||||
For
|
||||
.BR \-Wf\-target=symbolic ,
|
||||
the option
|
||||
.B \-Wf-html
|
||||
causes the text rendition to be emitted as HTML.
|
||||
.B
|
||||
.SH LIMITATIONS
|
||||
.PP
|
||||
.I lcc
|
||||
accepts the C programming language
|
||||
as described in the ANSI standard.
|
||||
If
|
||||
.I lcc
|
||||
is used with the GNU C preprocessor, the
|
||||
.B \-Wp\-trigraphs
|
||||
option is required to enable trigraph sequences.
|
||||
.PP
|
||||
Plain int bit fields are signed.
|
||||
Bit fields are aligned like unsigned integers but are otherwise laid out
|
||||
as by most standard C compilers.
|
||||
Some compilers, such as the GNU C compiler,
|
||||
may choose other, incompatible layouts.
|
||||
.PP
|
||||
Likewise, calling conventions are intended to be compatible with
|
||||
the host C compiler,
|
||||
except possibly for passing and returning structures.
|
||||
Specifically,
|
||||
.I lcc
|
||||
passes and returns structures like host ANSI C compilers
|
||||
on most targets, but some older host C compilers use different conventions.
|
||||
Consequently, calls to/from such functions compiled with
|
||||
older C compilers may not work.
|
||||
Calling a function that returns
|
||||
a structure without declaring it as such violates
|
||||
the ANSI standard and may cause a fault.
|
||||
.SH FILES
|
||||
.PP
|
||||
The file names listed below are
|
||||
.IR typical ,
|
||||
but vary among installations; installation-dependent variants
|
||||
can be displayed by running
|
||||
.I lcc
|
||||
with the
|
||||
.B \-v
|
||||
option.
|
||||
.PP
|
||||
.RS
|
||||
.ta \w'$LCCDIR/liblcc.{a,lib}XX'u
|
||||
.nf
|
||||
file.{c,C} input file
|
||||
file.{s,asm} assembly-language file
|
||||
file.{o,obj} object file
|
||||
a.{out,exe} loaded output
|
||||
/tmp/lcc* temporary files
|
||||
$LCCDIR/cpp preprocessor
|
||||
$LCCDIR/rcc compiler
|
||||
$LCCDIR/liblcc.{a,lib} \fIlcc\fP-specific library
|
||||
/lib/crt0.o runtime startup (UNIX)
|
||||
/lib/[gm]crt0.o startups for profiling (UNIX)
|
||||
/lib/libc.a standard library (UNIX)
|
||||
$LCCDIR/include ANSI standard headers
|
||||
/usr/local/include local headers
|
||||
/usr/include traditional headers
|
||||
prof.out file produced for \fIbprint\fR(1)
|
||||
mon.out file produced for \fIprof\fR(1)
|
||||
gmon.out file produced for \fIgprof\fR(1)
|
||||
.fi
|
||||
.RE
|
||||
.PP
|
||||
.I lcc
|
||||
predefines the macro
|
||||
.B __LCC__
|
||||
on all systems.
|
||||
It may also predefine some installation-dependent symbols; option
|
||||
.B \-v
|
||||
exposes them.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
C. W. Fraser and D. R. Hanson,
|
||||
.I A Retargetable C Compiler: Design and Implementation,
|
||||
Addison-Wesley, 1995. ISBN 0-8053-1670-1.
|
||||
.PP
|
||||
The World-Wide Web page at http://www.cs.princeton.edu/software/lcc/.
|
||||
.PP
|
||||
S. P. Harbison and G. L. Steele, Jr.,
|
||||
.I C: A Reference Manual,
|
||||
4th ed., Prentice-Hall, 1995.
|
||||
.PP
|
||||
B. W. Kernighan and D. M. Ritchie,
|
||||
.I The C Programming Language,
|
||||
2nd ed., Prentice-Hall, 1988.
|
||||
.PP
|
||||
American National Standards Inst.,
|
||||
.I American National Standard for Information Systems\(emProgramming
|
||||
.IR Language\(emC ,
|
||||
ANSI X3.159-1989, New York, 1990.
|
||||
.br
|
||||
.SH BUGS
|
||||
Mail bug reports along with the shortest preprocessed program
|
||||
that exposes them and the details reported by
|
||||
.IR lcc 's
|
||||
.B \-v
|
||||
option to lcc-bugs@princeton.edu. The WWW page at
|
||||
URL http://www.cs.princeton.edu/software/lcc/
|
||||
includes detailed instructions for reporting bugs.
|
||||
.PP
|
||||
The ANSI standard headers conform to the specifications in
|
||||
the Standard, which may be too restrictive for some applications,
|
||||
but necessary for portability.
|
||||
Functions given in the ANSI headers may be missing from
|
||||
some local C libraries (e.g., wide-character functions)
|
||||
or may not correspond exactly to the local versions;
|
||||
for example, the ANSI standard
|
||||
stdio.h
|
||||
specifies that
|
||||
.IR printf ,
|
||||
.IR fprintf ,
|
||||
and
|
||||
.I sprintf
|
||||
return the number of characters written to the file or array,
|
||||
but some existing libraries don't implement this convention.
|
||||
.PP
|
||||
On the MIPS and SPARC, old-style variadic functions must use
|
||||
varargs.h
|
||||
from MIPS or Sun. New-style is recommended.
|
||||
.PP
|
||||
With
|
||||
.BR \-b ,
|
||||
files compiled
|
||||
.I without
|
||||
.B \-b
|
||||
may cause
|
||||
.I bprint
|
||||
to print erroneous call graphs.
|
||||
For example, if
|
||||
.B f
|
||||
calls
|
||||
.B g
|
||||
calls
|
||||
.B h
|
||||
and
|
||||
.B f
|
||||
and
|
||||
.B h
|
||||
are compiled with
|
||||
.BR \-b ,
|
||||
but
|
||||
.B g
|
||||
is not,
|
||||
.B bprint
|
||||
will report that
|
||||
.B f
|
||||
called
|
||||
.BR h .
|
||||
The total number of calls is correct, however.
|
||||
Loading…
Add table
Add a link
Reference in a new issue