URL
https://opencores.org/ocsvn/eco32/eco32/trunk
Subversion Repositories eco32
Compare Revisions
- This comparison shows the changes necessary to convert path
/eco32/tags/eco32-0.25/lcc/doc
- from Rev 4 to Rev 248
- ↔ Reverse comparison
Rev 4 → Rev 248
/lcc.1
0,0 → 1,605
.\" $Id: lcc.1,v 1.15 1998/08/24 21:14:33 drh Exp $ |
.TH LCC 1 "local \- $Date: 1998/08/24 21:14:33 $" |
.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. |
/install.html
0,0 → 1,774
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
<html> |
|
<head> |
<link HREF="mailto:drh@cs.princeton.edu" REV="made" TITLE="David R. Hanson"> |
<title>Installing lcc</title> |
</head> |
|
<body> |
|
<h1>Installing lcc</h1> |
|
<p ALIGN="LEFT"><strong><a HREF="http://www.research.microsoft.com/~cwfraser/">Christopher |
W. Fraser</a> and <a HREF="http://www.research.microsoft.com/~drh/">David R. Hanson</a>, <a |
HREF="http://www.research.microsoft.com/">Microsoft Research</a></strong><br> |
September 2002</p> |
|
<h2>Contents</h2> |
|
<dir> |
<li><a HREF="#intro">Introduction</a></li> |
<li><a HREF="#unix">Installation on UNIX</a></li> |
<li><a HREF="#driver">Building the Driver</a></li> |
<li><a HREF="#rcc">Building the Compiler and Accessories</a></li> |
<li><a HREF="#win32">Installation on Windows</a></li> |
<li><a HREF="#bugs">Reporting Bugs</a></li> |
<li><a HREF="#mailinglist">Keeping in Touch</a></li> |
</dir> |
|
<h2><a NAME="intro">Introduction</a></h2> |
|
<p><a HREF="http://www.cs.princeton.edu/software/lcc/">lcc</a> is the ANSI C compiler |
described in our book <cite>A Retargetable C Compiler: Design and Implementation</cite> |
(Addison-Wesley, 1995, ISBN 0-8053-1670-1).</p> |
|
<p>If you're installing lcc on a UNIX system, read the remainder of this section and |
continue with the next section. If you're installing lcc on a Windows system, you should read the rest of this section, the following three sections, and the <a |
HREF="#win32">Windows</a> section.</p> |
|
<p>Extract the distribution into its own directory. All non-absolute paths below are |
relative to this directory. The distribution holds the following subdirectories.</p> |
|
<blockquote> |
<table BORDER="0" CELLPADDING="1" CELLSPACING="1" WIDTH="80%"> |
<tr> |
<td><a HREF="../src"><code>src</code></a></td> |
<td></td> |
<td>source code</td> |
</tr> |
<tr> |
<td><a HREF="../etc"><code>etc</code></a></td> |
<td></td> |
<td>driver, accessories</td> |
</tr> |
<tr> |
<td><a HREF="../lib"><code>lib</code></a></td> |
<td></td> |
<td>runtime library source code</td> |
</tr> |
<tr> |
<td><a HREF="../cpp"><code>cpp</code></a></td> |
<td></td> |
<td>preprocessor source code</td> |
</tr> |
<tr> |
<td><a HREF="../lburg"><code>lburg</code></a></td> |
<td></td> |
<td>code-generator generator source code</td> |
</tr> |
<tr> |
<td><a HREF="../doc"><code>doc</code></a></td> |
<td></td> |
<td>this document, man pages</td> |
</tr> |
<tr> |
<td><code><a HREF="../include">include</a>/*/*</code></td> |
<td></td> |
<td>include files</td> |
</tr> |
<tr> |
<td><a HREF="../tst"><code>tst</code></a></td> |
<td></td> |
<td>test suite</td> |
</tr> |
<tr> |
<td><code><a HREF="../alpha">alpha</a>/*/tst</code></td> |
<td></td> |
<td>ALPHA test outputs</td> |
</tr> |
<tr> |
<td><code><a HREF="../mips">mips</a>/*/tst</code></td> |
<td></td> |
<td>MIPS test outputs</td> |
</tr> |
<tr> |
<td><code><a HREF="../sparc">sparc</a>/*/tst</code></td> |
<td></td> |
<td>SPARC test outputs</td> |
</tr> |
<tr> |
<td><code><a HREF="../x86">x86</a>/*/tst</code></td> |
<td></td> |
<td>X86 test outputs</td> |
</tr> |
</table> |
</blockquote> |
|
<p><code>doc/install.html</code> is the HTML file for this document.</p> |
|
<p>The installation makefile is designed so that lcc can be installed from a read-only |
file system or directory, which is common in networked environments, so the distribution |
can be unloaded on a central file server. <strong>You will need an existing ANSI/ISO C |
compiler to build and install lcc.</strong></p> |
|
<h2><a NAME="unix">Installation on UNIX</a></h2> |
|
<p>The compilation components (the preprocessor, include files, and compiler proper, etc.) |
are installed in a single <em>build directory</em>. On multi-platform systems supported by |
a central file server, it's common to store the build directory in a location specific to |
the platform and to the version of lcc, and to point a symbolic link to this location. For |
example,</p> |
|
<blockquote> |
<pre>% ln -s $BUILDDIR/sparc-solaris /usr/local/lib/lcc</pre> |
</blockquote> |
|
<p>points <code>/usr/local/lib/lcc</code> to a build directory for lcc on the SPARC under Solaris. Links into <code>/usr/local/lib/lcc</code> are created for the programs <code>lcc</code> |
and <code>bprint</code>. Thus, a new distribution can be installed by building it in its |
own build directory and changing one symbolic link to point to that directory. If these |
conventions or their equivalents are followed, the host-specific parts of the driver |
program, <code>lcc</code>, can be used unmodified.</p> |
|
<p>Installation on a UNIX system involves the following steps. Below, the build directory |
is referred to as <code>BUILDDIR</code>, and the commands below are executed |
from the distribution directory.<ol> |
<li>Create the build directory, using a version- and platform-specific naming convention as |
suggested above, and record the name of this directory in the <code>BUILDDIR</code> |
environment variable:<blockquote> |
<pre>% setenv BUILDDIR $BUILDDIR/sparc-solaris |
% mkdir -p $BUILDDIR</pre> |
</blockquote> |
<p>Here and below, commands assume the C shell. Also, you'll need a version of <code>mkdir</code> |
that supports the <code>-p</code> option, which creates intermediate directories as |
necessary.</p> |
</li> |
<li>Copy the man pages to the repository for local man pages, e.g.,<blockquote> |
<pre>% cp doc/*.1 /usr/local/man/man1</pre> |
</blockquote> |
<p>Some users copy the man pages to the build directory and create the appropriate |
symbolic links, e.g., </p> |
<blockquote> |
<pre>% cp doc/*.1 $BUILDDIR |
% ln -s $BUILDDIR/*.1 /usr/local/man/man1</pre> |
</blockquote> |
</li> |
<li>Platform-specific include files are in directories named <code>include/</code><em>target</em><code>/</code><em>os</em>. |
Create the include directory in the build directory, and copy the include hierarchy for |
your platform to this directory, e.g.,<blockquote> |
<pre>% mkdir $BUILDDIR/include |
% cp -p -R include/sparc/solaris/* $BUILDDIR/include</pre> |
</blockquote> |
<p>Again, some users create a symbolic link to the appropriate directory in the |
distribution instead of copying the include files. For example, at Princeton, the |
distributions are stored under <code>/proj/pkg/lcc</code>, so the included files are |
"installed" by creating one symbolic link: </p> |
<blockquote> |
<pre>% ln -s $BUILDDIR/include/sparc/solaris $BUILDDIR/include</pre> |
</blockquote> |
<p>If you're installing lcc on Linux, you <em>must</em> also plant a symbolic link named <code>gcc</code> |
to gcc's library directory, because lcc uses gcc's C preprocessor and most of gcc's header |
files:</p> |
<blockquote> |
<pre>% ln -s /usr/lib/gcc-lib/i386-redhat-linux/2.96 $BUILDDIR/gcc</pre> |
</blockquote> |
<p>The library directory shown above may be different on your Linux machine; to determine |
the correct directory, browse <code>/usr/lib/gcc-lib</code>, or execute</p> |
<blockquote> |
<pre>% cc -v tst/8q.c</pre> |
</blockquote> |
<p>and examine the diagnostic output. Make sure that <code>$BUILDDIR/gcc/cpp0</code> and <code>$BUILDDIR/gcc/include</code> |
are, respectively, gcc's C preprocessor and header files. On Linux, lcc looks for |
include files in <code>$BUILDDIR/include</code>, <code>$BUILDDIR/gcc/include</code>, and <code>/usr/include</code>, |
in that order; see <a HREF="#driver"><em>Building the Driver</em></a> and <a |
href="../etc/linux.c"><code>etc/linux.c</code></a> for details.</p> |
</li> |
<li>The <a HREF="../makefile"><code>makefile</code></a> includes the file named by the <code>CUSTOM</code> |
macro; the default is <code>custom.mk</code>, and an empty <code>custom.mk</code> is |
included in the distribution. If desired, prepare a site-specification customization file |
and define <code>CUSTOM</code> to the path of that file when invoking make in steps 5 and |
6, e.g.,<blockquote> |
<pre>make CUSTOM=<a href="http://www.cs.princeton.edu/software/lcc/pkg/solaris.mk">solaris.mk</a></pre> |
</blockquote> |
<p>You can, for example, use customization files to record site-specific values for macros |
instead of using environment variables, and to record targets for the steps in this list.</p> |
</li> |
<li>Build the host-specific driver, creating a custom host-specific part, if necessary. See <a |
HREF="#driver"><em>Building the Driver</em></a>.</li> |
<li>Build the preprocessor, compiler proper, library, and other accessories. See <a |
HREF="#rcc"><em>Building the Compiler</em></a>.</li> |
<li>Plant symbolic links to the build directory and to the installed programs, e.g.,<blockquote> |
<pre>% ln -s $BUILDDIR /usr/local/lib/lcc |
% ln -s /usr/local/lib/{lcc,bprint} /usr/local/bin</pre> |
</blockquote> |
<p>Some users copy <code>bprint</code> and <code>lcc</code> into <code>/usr/local/bin</code> |
instead of creating symbolic links. The advantage of creating the links for <code>lcc</code> |
and <code>bprint</code> as shown is that, once established, they point indirectly to |
whatever <code>/usr/local/lib/lcc</code> points to; installing a new version of lcc can be done by changing <code>/usr/local/lib/lcc</code> to point to the build |
directory for the new version.</p> |
</li> |
</ol> |
|
<h2><a NAME="driver">Building the Driver</a></h2> |
|
<p>The preprocessor, compiler, assembler, and loader are invoked by a driver program, <code>lcc</code>, |
which is similar to <code>cc</code> on most systems. It's described in the man page <code>doc/lcc.1</code>. |
The driver is built by combining the host-independent part, <a href="../etc/lcc.c"><code>etc/lcc.c</code></a>, |
with a small host-specific part. Distributed host-specific parts are named <code>etc/</code><em>os</em><code>.c</code>, |
where <em>os</em> is the name of the operating system for the host on which <code>lcc</code> |
is being installed. If you're following the installations conventions described above, you |
can probably use one of the host-specific parts unmodified; otherwise, pick one that is |
closely related to your platform, copy it to <em>whatever</em><code>.c</code>, and edit it |
as described below. You should not have to edit <code>etc/lcc.c</code>.</p> |
|
<p>We'll use <a HREF="../etc/solaris.c"><code>etc/solaris.c</code></a> as an example in |
describing how the host-specific part works. This example illustrates all the important |
features. Make sure you have the environment variable <code>BUILDDIR</code> set correctly, |
and build the driver with a <code>make</code> command, e.g.,</p> |
|
<blockquote> |
<pre>% make HOSTFILE=etc/solaris.c lcc |
cc -g -c -o $BUILDDIR/sparc-solaris/lcc.o etc/lcc.c |
cc -g -c -o $BUILDDIR/sparc-solaris/host.o etc/solaris.c |
cc -g -o $BUILDDIR/lcc $BUILDDIR/sparc-solaris/lcc.o $BUILDDIR/sparc-solaris/host.o</pre> |
</blockquote> |
|
<p>Of course, the actual value of <code>BUILDDIR</code> will appear in place of |
<code>$BUILDDIR</code>. The symbolic name <code>HOSTFILE</code> specifies the path to the host-specific part, |
either one in the distribution or <em>whatever</em><code>.c</code>. Some versions of make |
may require the <code>-e</code> option in order to read the environment.</p> |
|
<p>Here's <code>etc/solaris.c</code>:</p> |
|
<blockquote> |
<pre>/* Sparcs running Solaris 2.5.1 at CS Dept., Princeton University */ |
|
#include <string.h> |
|
static char rcsid[] = "$ Id: solaris.c,v 1.10 1998/09/14 20:36:33 drh Exp $"; |
|
#ifndef LCCDIR |
#define LCCDIR "/usr/local/lib/lcc/" |
#endif |
#ifndef SUNDIR |
#define SUNDIR "/opt/SUNWspro/SC4.2/lib/" |
#endif |
|
char *suffixes[] = { ".c", ".i", ".s", ".o", ".out", 0 }; |
char inputs[256] = ""; |
char *cpp[] = { LCCDIR "cpp", |
"-D__STDC__=1", "-Dsparc", "-D__sparc__", "-Dsun", "-D__sun__", "-Dunix", |
"$1", "$2", "$3", 0 }; |
char *include[] = { "-I" LCCDIR "include", "-I/usr/local/include", |
"-I/usr/include", 0 }; |
char *com[] = { LCCDIR "rcc", "-target=sparc/solaris", |
"$1", "$2", "$3", 0 }; |
char *as[] = { "/usr/ccs/bin/as", "-Qy", "-s", "-o", "$3", "$1", "$2", 0 }; |
char *ld[] = { "/usr/ccs/bin/ld", "-o", "$3", "$1", |
SUNDIR "crti.o", SUNDIR "crt1.o", |
SUNDIR "values-xa.o", "$2", "", |
"-Y", "P," SUNDIR ":/usr/ccs/lib:/usr/lib", "-Qy", |
"-L" LCCDIR, "-llcc", "-lm", "-lc", SUNDIR "crtn.o", 0 }; |
|
extern char *concat(char *, char *); |
|
int option(char *arg) { |
if (strncmp(arg, "-lccdir=", 8) == 0) { |
cpp[0] = concat(&arg[8], "/cpp"); |
include[0] = concat("-I", concat(&arg[8], "/include")); |
ld[12] = concat("-L", &arg[8]); |
com[0] = concat(&arg[8], "/rcc"); |
} else if (strcmp(arg, "-p") == 0) { |
ld[5] = SUNDIR "mcrt1.o"; |
ld[10] = "P," SUNDIR "libp:/usr/ccs/lib/libp:/usr/lib/libp:" |
SUNDIR ":/usr/ccs/lib:/usr/lib"; |
} else if (strcmp(arg, "-b") == 0) |
; |
else if (strncmp(arg, "-ld=", 4) == 0) |
ld[0] = &arg[4]; |
else |
return 0; |
return 1; |
}</pre> |
</blockquote> |
|
<p><code>LCCDIR</code> defaults to <code>"/usr/local/lib/lcc/"</code> unless |
it's defined by a <code>-D</code> option as part of <code>CFLAGS</code> in the make |
command, e.g.,</p> |
|
<blockquote> |
<pre>% make HOSTFILE=etc/solaris.c CFLAGS='-DLCCDIR=\"/v/lib/lcc/\"' lcc</pre> |
</blockquote> |
|
<p>Note the trailing slash; <code>SUNDIR</code> is provided so you can use <code>etc/solaris.c</code> |
even if you have a different version of the Sun Pro compiler suite. If you're using the |
gcc compiler tools instead of the Sun Pro tools, see <a HREF="../etc/gcc-solaris.c"><code>etc/gcc-solaris.c</code></a>.</p> |
|
<p>Most of the host-specific code is platform-specific data and templates for the commands |
that invoke the preprocessor, compiler, assembler, and loader. The <code>suffixes</code> |
array lists the file name suffixes for C source files, preprocessed source files, assembly |
language source files, object files, and executable files. <code>suffixes</code> must be |
terminated with a null pointer, as shown above. The initialization of <code>suffixes</code> |
in <code><a HREF="../etc/solaris.c">etc/solaris.c</a></code> are the typical ones for UNIX |
systems. Each element of <code>suffixes</code> is actually a list of suffixes, separated |
by semicolons; <code><a HREF="../etc/win32.c">etc/win32.c</a></code> holds an example:</p> |
|
<blockquote> |
<pre>char *suffixes[] = { ".c;.C", ".i;.I", ".asm;.ASM;.s;.S", ".obj;.OBJ", ".exe", 0 };</pre> |
</blockquote> |
|
<p>When a list is given, the first suffix is used whenever lcc needs to generate a file |
name. For example, with <code><a HREF="../etc/win32.c">etc/win32.c</a></code>, lcc emits |
the generated assembly code into <code>.asm</code> files.</p> |
|
<p>The <code>inputs</code> array holds a null-terminated string of directories separated |
by colons or semicolons. These are used as the default value of <code>LCCINPUTS</code>, if |
the environment variable <code>LCCINPUTS</code> is not set; see the <a HREF="lcc.pdf">man |
page</a>.</p> |
|
<p>Each command template is an array of pointers to strings terminated with a null |
pointer; the strings are full path names of commands, arguments, or argument placeholders, |
which are described below. Commands are executed in a child process, and templates can |
contain multiple commands by separating commands with newlines. The driver runs each |
command in a new process.</p> |
|
<p>The <code>cpp</code> array gives the command for running lcc's preprocessor, <code>cpp</code>. |
Literal arguments specified in templates, e.g., <code>"-Dsparc"</code> in the <code>cpp</code> |
command above, are passed to the command as given.</p> |
|
<p>The strings <code>"$1"</code>, <code>"$2"</code>, and <code>"$3"</code> |
in templates are placeholders for <em>lists</em> of arguments that are substituted in a |
copy of the template before the command is executed. <code>$1</code> is replaced by the <em>options</em> |
specified by the user; for the preprocessor, this list always contains at least <code>-D__LCC__</code>. |
<code>$2</code> is replaced by the <em>input</em> files, and <code>$3</code> is replaced |
by the <em>output</em> file.</p> |
|
<p>Zero-length arguments after replacement are removed from the argument list before the |
command is invoked. So, for example, if the preprocessor is invoked without an output |
file, <code>"$3"</code> becomes <code>""</code>, which is removed from |
the final argument list.</p> |
|
<p>The <code>include</code> array is a list of <code>-I</code> options that specify which |
directives should be searched to satisfy include directives. These directories are |
searched in the order given. The first directory should be the one to which the ANSI |
header files were copied as described in <a HREF="#unix">UNIX</a> or <a HREF="#win32">Windows</a> |
installation instructions. The driver adds these options to <code>cpp</code>'s arguments |
when it invokes the preprocessor, except when <code>-N</code> is specified.</p> |
|
<p><code>com</code> gives the command for invoking the compiler. This template can appear |
as shown above in a custom host-specific part, but the option <code>-target=sparc/solaris</code> |
should be edited to the <em>target</em><code>/</code><em>os</em> for your platform. If <code>com[1]</code> |
includes the string "<code>win32</code>", the driver assumes it's running on |
Windows. lcc can generate code for <em>all</em> of the <em>target</em><code>/</code><em>os</em> |
combinations listed in the file <code>src/bind.c</code>. The <code>-target</code> option |
specifies the default combination. The driver's <code>-Wf</code> option can be used to |
specify other combinations; the <a HREF="lcc.pdf">man page</a> elaborates.</p> |
|
<p><code>as</code> gives the command for invoking the assembler. On Linux, you must be |
running at least version 2.8.1 of the GNU assembler; earlier versions mis-assemble some |
instructions emitted by lcc.</p> |
|
<p><code>ld</code> gives the command for invoking the loader. For the other commands, the |
list <code>$2</code> contains a single file; for <code>ld</code>, <code>$2</code> contains |
all ".o" files and libraries, and <code>$3</code> is <code>a.out</code>, unless |
the <code>-o</code> option is specified. As suggested in the code above, <code>ld</code> |
must also specify the appropriate startup code and default libraries, including the lcc |
library, <code>liblcc.a</code>.</p> |
|
<p>The <code>option</code> function is described below; the minimal <code>option</code> |
function just returns 0.</p> |
|
<p>You can test <code>lcc</code> with the options <code>-v -v</code> to display the |
commands that would be executed, e.g.,</p> |
|
<blockquote> |
<pre>% $BUILDDIR/lcc -v -v foo.c baz.c mylib.a -lX11 |
$BUILDDIR/sparc-solaris/lcc $ Id: lcc.c,v 4.33 2001/06/28 22:19:58 drh $ |
foo.c: |
/usr/local/lib/lcc/cpp -D__STDC__=1 -Dsparc -D__sparc__ -Dsun -D__sun__ -Dunix -D__LCC__i |
/usr/local/lib/lcc/rcc -target=sparc/solaris -v /tmp/lcc4060.i /tmp/lcc4061.s |
/usr/ccs/bin/as -Qy -s -o /tmp/lcc4062.o /tmp/lcc4061.s |
baz.c: |
/usr/local/lib/lcc/cpp -D__STDC__=1 -Dsparc -D__sparc__ -Dsun -D__sun__ -Dunix -D__LCC__i |
/usr/local/lib/lcc/rcc -target=sparc/solaris -v /tmp/lcc4060.i /tmp/lcc4061.s |
/usr/ccs/bin/as -Qy -s -o /tmp/lcc4063.o /tmp/lcc4061.s |
/usr/ccs/bin/ld -o a.out /opt/SUNWspro/SC4.2/lib/crti.o /opt/SUNWspro/SC4.2/lib/crt1.o /o |
rm /tmp/lcc4063.o /tmp/lcc4060.i /tmp/lcc4061.s /tmp/lcc4062.o</pre> |
</blockquote> |
|
<p>As the output shows, <code>lcc</code> places temporary files in <code>/tmp</code>; if |
any of the environment variables <code>TMP</code>, <code>TEMP</code>, and <code>TMPDIR</code> |
are set, they override this default (in the order shown) as does the <code>-tempdir=</code><em>dir</em> |
option. The default can be changed by defining <code>TEMPDIR</code> in <code>CFLAGS</code> |
when building the driver.</p> |
|
<p>The <code>option</code> function is called for the options <code>-Wo</code>, <code>-g</code>, |
<code>-p</code>, <code>-pg</code>, and <code>-b</code> because these compiler options |
might also affect the loader's arguments. For these options, the driver calls <code>option(arg)</code> |
to give the host-specific code an opportunity to edit the <code>ld</code> command, if |
necessary. <code>option</code> can change <code>ld</code>, if necessary, and return 1 to |
announce its acceptance of the option. If the option is unsupported, <code>option</code> |
should return 0.</p> |
|
<p>For example, in response to <code>-g</code>, the <code>option</code> function shown |
above accepts the option but does nothing else, because the <code>ld</code> and <code>as</code> |
commands don't need to be modified on the SPARC. <code>-g</code> will also be added to the |
compiler's options by the host-independent part of the driver. The <code>-p</code> causes <code>option</code> |
to change the name of the startup code and changed the list of libraries. The <code>-b</code> |
option turns on <code>lcc</code>'s per-expression profiling, the code for which is in <code>liblcc.a</code>, |
so <code>option</code> need no nothing.</p> |
|
<p>On SPARCs, the driver also recognizes <code>-Bstatic</code> and <code>-Bdynamic</code> |
as linker options. The driver recognizes but ignores "<code>-target</code> <em>name</em>" |
option.</p> |
|
<p>The option <code>-Wo</code><em>arg</em> causes the driver to pass <em>arg</em> to <code>option</code>. |
Such options have no other effect; this mechanism is provided to support system-specific |
options that affect the commands executed by the driver. As illustrated above, |
host-specific parts should support the <code>-Wo-lccdir=</code><em>dir</em> option, which |
causes lcc's compilation components to be found in <em>dir</em>, because this option is |
used by the test scripts, and because the driver simulates a <code>-Wo-lccdir</code> |
option with the value of the environment variable <code>LCCDIR</code>, if it's defined. |
The code above rebuilds the paths to the include files, preprocessor, compiler, and |
library by calling <code>concat</code>, which is defined in <code>etc/lcc.c</code>.</p> |
|
<h2><a NAME="rcc">Building the Compiler and Accessories</a></h2> |
|
<p>To build the rest of compilation components make sure <code>BUILDDIR</code> is set |
appropriately and type "<code>make all</code>". This command builds <code>librcc.a</code> |
(the compiler's private library), <code>rcc</code> (the compiler proper), <code>lburg</code> |
(the code-generator generator), <code>cpp</code> (the preprocessor), <code>liblcc.a</code> |
(the runtime library), and <code>bprint</code> (the profile printer), all in <code>BUILDDIR</code>. |
There may be warnings, but there should be no errors. If you're using an ANSI/ISO compiler |
other than <code>cc</code>, specify its name with the <code>CC=</code> option, e.g., |
"<code>make CC=gcc all</code>". If you're running on a DEC ALPHA, use "<code>make |
CC='cc -std1' all</code>"; the <code>-std1</code> option is essential on |
the ALPHA.</p> |
|
<p>Once <code>rcc</code> is built with the host C compiler, run the test suite to verify |
that <code>rcc</code> is working correctly. If any of the steps below fail, contact us |
(see <a HREF="#bugs"><em>Reporting Bugs</em></a>). The commands in the makefile run the |
shell script <code>src/run.sh</code> on each C program in the test suite, <code>tst/*.c</code>. |
It uses the driver, <code>$BUILDDIR/lcc</code>, so you must have the driver in the build |
directory before testing <code>rcc</code>. The <em>target</em><code>/</code><em>os</em> |
combination is read from the variable <code>TARGET</code>, which must be specified when |
invoking <code>make</code>:</p> |
|
<blockquote> |
<pre>% make TARGET=sparc/solaris test |
mkdir -p $BUILDDIR/sparc-solaris/sparc/solaris/tst |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/8q.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/array.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/cf.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/cq.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/cvt.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/fields.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/front.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/incr.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/init.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/limits.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/paranoia.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/sort.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/spill.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/stdarg.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/struct.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/switch.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/wf1.s: |
$BUILDDIR/sparc-solaris/rcc -target=sparc/solaris $BUILDDIR/sparc-solaris/sparc/solaris/tst/yacc.s:</pre> |
</blockquote> |
|
<p>Each line in the output above is of the form</p> |
|
<blockquote> |
<p><code>$BUILDDIR/rcc -target=</code><em>target</em><code>/</code><em>os</em><code> $BUILDDIR/</code><em>target</em><code>/</code><em>os</em><code>/</code><em>X</em><code>.s:</code></p> |
</blockquote> |
|
<p>where <em>X</em> is the base name of the C program <em>X</em><code>.c</code> in the |
test suite. The actual value of <code>BUILDDIR</code> will, of course, appear in |
place of <code>$BUILDDIR</code>. This output identifies the compiler and the target, e.g., "<code>$BUILDDIR/rcc</code> |
is generating code for a <code>sparc</code> running the <code>solaris</code> operating |
system."</p> |
|
<p>For each program in the test suite, <code>src/run.sh</code> compiles the program, drops |
the generated assembly language code in <code>BUILDDIR</code>/<em>target</em><code>/</code><em>os</em>, |
and uses <code>diff</code> to compare the generated assembly code with the expected code |
(the code expected for <code>tst/8q.c</code> on the SPARC under Solaris is in <code>sparc/solaris/tst/8q.sbk</code>, |
etc.). If there are differences, the script executes the generated code with the input |
given in <code>tst</code> (the input for <code>tst/8q.c</code> is in <code>tst/8q.0</code>, |
etc.) and compares the output with the expected output (the expected output from <code>tst/8q.c</code> |
on the SPARC under Solaris is in <code>sparc/solaris/tst/8q.1bk</code>, etc.). The script |
also compares the diagnostics from the compiler with the expected diagnostics.</p> |
|
<p>On some systems, there may be a few differences between the generated code and the |
expected code. These differences occur because the expected code is generated by cross |
compilation and the least significant bits of some floating-point constants differ from |
those bits in constants generated on your system. On Linux, there may be differences |
because of differences in the header files between our system and yours. There should be |
no differences in the output from executing the test programs.</p> |
|
<p>Next, run the "triple test", which builds <code>rcc</code> using itself:</p> |
|
<blockquote> |
<pre>% make triple |
$BUILDDIR/sparc-solaris/lcc -A -d0.6 -Wo-lccdir=$(BUILDDIR) -Isrc -I$(BUILDDIR) -o $BUILDDIR/sparc-solaris/1rcc -B$BUILDDIR/sparc-solaris/ src/alloc.c ... |
src/alloc.c: |
... |
$BUILDDIR/sparc-solaris/lcc -A -d0.6 -Wo-lccdir=$(BUILDDIR) -Isrc -I$(BUILDDIR) -o $BUILDDIR/sparc-solaris/2rcc -B$BUILDDIR/sparc-solaris/1 src/alloc.c ... |
src/alloc.c: |
... |
strip $BUILDDIR/sparc-solaris/[12]rcc |
dd if=$BUILDDIR/sparc-solaris/1rcc of=$BUILDDIR/sparc-solaris/rcc1 bs=512 skip=1 |
1270+1 records in |
1270+1 records out |
dd if=$BUILDDIR/sparc-solaris/2rcc of=$BUILDDIR/sparc-solaris/rcc2 bs=512 skip=1 |
1270+1 records in |
1270+1 records out |
if cmp $BUILDDIR/sparc-solaris/rcc[12]; then \ |
mv $BUILDDIR/sparc-solaris/2rcc $BUILDDIR/sparc-solaris/rcc; \ |
rm -f $BUILDDIR/sparc-solaris/1rcc $BUILDDIR/sparc-solaris/rcc[12]; fi</pre> |
</blockquote> |
|
<p>This command builds <code>rcc</code> twice; once using the <code>rcc</code> built by <code>cc</code> |
and again using the <code>rcc</code> built by <code>lcc</code>. The resulting binaries are |
compared. They should be identical, as shown at the end of the output above. If they |
aren't, our compiler is generating incorrect code; <a HREF="#bugs">contact</a> us.</p> |
|
<p>The final version of <code>rcc</code> should also pass the test suite; that is, the |
output from</p> |
|
<blockquote> |
<pre>% make TARGET=sparc/solaris test</pre> |
</blockquote> |
|
<p>should be identical to that from the previous <code>make test</code>.</p> |
|
<p>The command "<code>make clean</code>" cleans up, but does not remove <code>rcc</code>, |
etc., and "<code>make clobber</code>" cleans up and removes <code>lcc</code>, <code>rcc</code>, |
and the other accessories. Test directories under <code>BUILDDIR</code> are <em>not</em> |
removed; you'll need to remove these by hand, e.g.,</p> |
|
<blockquote> |
<pre>% rm -fr $BUILDDIR/sparc</pre> |
</blockquote> |
|
<p>The code generators for the other targets can be tested by specifying the desired <em>target</em><code>/</code><em>os</em> |
and setting an environment variable that controls what <code>src/run.sh</code> does. For |
example, to test the MIPS code generator, type</p> |
|
<blockquote> |
<pre>% setenv REMOTEHOST noexecute |
% make TARGET=mips/irix test</pre> |
</blockquote> |
|
<p>As above, <code>src/run.sh</code> compares the MIPS code generated with what's |
expected. There should be no differences. Setting <code>REMOTEHOST</code> to <code>noexecute</code> |
suppresses the assembly and execution of the generated code. If you set <code>REMOTEHOST</code> |
to the name of a MIPS machine to which you can <code>rlogin</code>, <code>src/run.sh</code> |
will <code>rcp</code> the generated code to that machine and execute it there, if |
necessary. See <code>src/run.sh</code> for the details.</p> |
|
<p>You can use lcc as a cross compiler. The options <code>-S</code> and <code>-Wf-target=</code><em>target/os</em> |
generate assembly code for the specified target, which is any of those listed in the file <code>src/bind.c</code>. |
For example, </p> |
|
<blockquote> |
<pre>% lcc -Wf-target=mips/irix -S tst/8q.c</pre> |
</blockquote> |
|
<p>generates MIPS code for <code>tst/8q.c</code> in <code>8q.s</code>.</p> |
|
<p>lcc can also generate code for a "symbolic" target. This target is used |
routinely in front-end development, and its output is a printable representation of the |
input program, e.g., the dags constructed by the front end are printed, and other |
interface functions print their arguments. You can specify this target with the option <code>-Wf-target=symbolic</code>. |
For example,</p> |
|
<blockquote> |
<pre>% lcc -Wf-target=symbolic -S tst/8q.c</pre> |
</blockquote> |
|
<p>generates symbolic output for <code>tst/8q.c</code> in <code>8q.s</code>. Adding <code>-Wf-html</code> |
causes the symbolic target to emit HTML instead of plain text. Finally, the option <code>-Wf-target=null</code> |
specifies the "null" target for which lcc emits nothing and thus only checks the |
syntax and semantics of its input files.</p> |
|
<h2><a NAME="win32">Installation on Windows</a></h2> |
|
<p>On Windows, lcc is designed to work with Microsoft's Visual |
C++ (VC), version 5.0 and above, and Microsoft's Assembler, MASM. It uses the VC header files, |
libraries, and command-line tools, and it uses MASM to assemble the code it generates. |
You must use MASM 6.11d or later, |
because earlier releases generate incorrect COFF object files. MASM |
6.15 is available as part of the free |
<a href="http://msdn.microsoft.com/vstudio/downloads/ppack/default.asp">Visual |
C++ 6.0 Processor Pack</a>.</p> |
|
<p>Building the distribution components from the ground up requires Microsoft's Visual |
C/C++ compiler, Microsoft's make, <code>nmake</code>, and the standard Windows command |
interpreter. <a HREF="../makefile.nt"><code>makefile.nt</code></a> is written to use only <code>nmake</code>. |
As on UNIX systems, the compilation components are installed in a single <em>build |
directory</em>, and the top-level programs, <code>lcc.exe</code> and <code>bprint.exe</code>, |
are installed in a directory on the PATH. If the conventions used below are followed, the |
Windows-specific parts of the driver program, <code>lcc.exe</code>, can be used |
unmodified.</p> |
|
<p>Building from the source distribution on a Windows system involves the following steps. |
Below, the build directory is referred to as <code>BUILDDIR</code>, and the distribution |
is in <code>\dist\lcc</code>. |
|
<ol> |
<li>Create the build directory, perhaps using a version- and platform-specific naming |
convention as suggested in <a HREF="#unix"><em>Installation on UNIX</em></a>, and record |
the name of this directory in the <code>BUILDDIR</code> environment variable:<blockquote> |
<pre>C:\dist\lcc>set BUILDDIR=\progra~1\lcc\<i>version</i>\bin |
C:\dist\lcc>mkdir %BUILDDIR%</pre> |
</blockquote> |
<p>The default build, or installation, directory is <code>\Program Files\lcc\</code><i>version</i><code>\bin</code>, |
where <i>version</i> is the version number, e.g., 4.2, but the <code>nmake</code> commands require that you use the corresponding 8.3 file name, <code>progra~1</code>, |
instead of <code>Program Files</code>.</p> |
</li> |
<li><a HREF="../etc/win32.c"><code>etc\win32.c</code></a> is the Windows-specific part of |
the driver. It assumes that environment variable <code>include</code> gives the locations |
of the VC header files and that the linker (<code>link.exe</code>) and the assembler (<code>ml.exe</code>) |
are on the PATH. It also assumes that the macro <code>LCCDIR</code> gives the build |
directory. If necessary, revise a copy of <a HREF="../etc/win32.c"><code>etc\win32.c</code></a> |
to reflect the conventions on your computer (see <a HREF="#driver"><em>Building the Driver</em></a>), |
then build the driver, specifying the default temporary directory, if necessary:<blockquote> |
<pre>C:\dist\lcc>nmake -f makefile.nt HOSTFILE=etc/win32.c lcc |
... |
cl -nologo -Zi -MLd -Fd%BUILDDIR%\ -c -Fo%BUILDDIR%\lcc.obj etc/lcc.c |
lcc.c |
cl -nologo -Zi -MLd -Fd%BUILDDIR%\ -c -Fo%BUILDDIR%\host.obj etc/win32.c |
win32.c |
cl -nologo -Zi -MLd -Fd%BUILDDIR%\ -Fe%BUILDDIR%\lcc.exe %BUILDDIR%\lcc.obj %BUILDDIR%\host.obj</pre> |
</blockquote> |
<p>If you make a copy of <code>etc\win32.c</code>, specify the path of the copy as the |
value of <code>HOSTFILE</code>. For example, if you copy <code>etc\win32.c</code> to <code>BUILDDIR</code> |
and edit it, use the command</p> |
<blockquote> |
<pre>C:\dist\lcc>nmake -f makefile.nt HOSTFILE=%BUILDDIR%\win32.c lcc</pre> |
</blockquote> |
</li> |
<li>Build the preprocessor, compiler proper, library, and other accessories (see <a |
HREF="#rcc"><em>Building the Compiler</em></a>):<blockquote> |
<pre>C:\dist\lcc>nmake -f makefile.nt all</pre> |
</blockquote> |
<p>This command uses the VC command-line tools <code>cl</code> and <code>lib</code> to |
build <code>bprint.exe</code>, <code>cpp.exe</code>, <code>lburg.exe</code>, <code>liblcc.lib</code>, |
<code>librcc.lib</code>, and <code>rcc.exe</code>, all in <code>BUILDDIR</code>. There may |
be some warnings, but there should be no warnings.</p> |
</li> |
<li>Create a test directory and run the test suite:<blockquote> |
<pre>C:\dist\lcc>mkdir %BUILDDIR%\x86\win32\tst |
C:\dist\lcc>nmake -f makefile.nt test</pre> |
</blockquote> |
<p>This command compiles each program in <a HREF="../tst">tst</a>, compares the generated |
assembly code and diagnostics with the expected assembly code and diagnostics, executes |
the program, and compares the output with the expected output (using <code>fc</code>). For |
example, when the nmake command compiles <a HREF="../tst/8q.c"><code>tst\8q.c</code></a>, |
it leaves the generated assembly code and diagnostic output in <code>%BUILDDIR%\x86\win32\tst\8q.s</code> |
and <code>%BUILDDIR%\x86\win32\tst\8q.2</code>, and it compares them with the expected |
results in <code>x86\win32\tst\8q.sbk</code>. It builds the executable program in <code>%BUILDDIR%\x86\win32\tst\8q.exe</code>, |
runs it, and redirects the output to <code>%BUILDDIR%\x86\win32\tst\8q.1</code>, which it |
compares with <code>x86\win32\tst\8q.1bk</code>. The output from this step is voluminous, |
but there should be no differences and no errors.</p> |
</li> |
<li>Run the "triple" test, which compiles <code>rcc</code> with itself and |
verifies the results:<blockquote> |
<pre>C:\dist\lcc>nmake -f makefile.nt triple |
... |
Assembling: C:/TEMP/lcc2001.asm |
fc /b %BUILDDIR%\1rcc.exe %BUILDDIR%\2rcc.exe |
Comparing files %BUILDDIR%\1rcc.exe and %BUILDDIR%\2RCC.EXE |
00000088: B4 D5</pre> |
</blockquote> |
<p>This command builds <code>rcc</code> twice; once using the <code>rcc</code> built by VC |
and again using the <code>rcc</code> built by <code>lcc</code>. The resulting binaries are |
compared using <code>fc</code>. They should be identical, except for one or two bytes of |
timestamp data, as shown at the end of the output above (which will be |
different on your system). If <code>1rcc.exe</code> and <code>2rcc.exe</code> aren't |
identical, our compiler is |
generating incorrect code; <a HREF="#bugs">contact</a> us.</p> |
</li> |
<li>Copy <code>lcc.exe</code> and <code>bprint.exe</code> to a directory on your PATH, e.g.,<blockquote> |
<pre>C:\dist\lcc>copy %BUILDDIR%\lcc.exe \bin |
1 file(s) copied. |
|
C:\dist\lcc>copy %BUILDDIR%\bprint.exe \bin |
1 file(s) copied.</pre> |
</blockquote> |
</li> |
<li>Finally, clean up:<blockquote> |
<pre>C:\dist\lcc>nmake -f makefile.nt clean</pre> |
</blockquote> |
<p>This command removes the derived files in <code>BUILDDIR</code>, but does not remove <code>rcc.exe</code>, |
etc.; "<code>nmake -f makefile.nt clobber</code>" cleans up and removes all |
executables and libraries. Test directories under <code>BUILDDIR</code> are <em>not</em> |
removed; you'll need to remove these by hand, e.g.,</p> |
<blockquote> |
<pre>C:\dist\lcc>rmdir %BUILDDIR%\x86 /s |
%BUILDDIR%\x86, Are you sure (Y/N)? y</pre> |
</blockquote> |
</li> |
</ol> |
|
<h2><a NAME="bugs">Reporting Bugs</a></h2> |
|
<p>lcc is a large, complex program. We find and repair errors routinely. If you think that |
you've found a error, follow the steps below, which are adapted from the instructions in |
Chapter 1 of <cite>A Retargetable C Compiler: Design and Implementation</cite>. |
|
<ol> |
<li>If you don't have a source file that displays the error, create one. Most errors are |
exposed when programmers try to compile a program they think is valid, so you probably |
have a demonstration program already.</li> |
<li>Preprocess the source file and capture the preprocessor output. Discard the original |
code.</li> |
<li>Prune your source code until it can be pruned no more without sending the error into |
hiding. We prune most error demonstrations to fewer than five lines.</li> |
<li>Confirm that the source file displays the error with the <em>distributed</em> version of |
lcc. If you've changed lcc and the error appears only in your version, then you'll have to |
chase the error yourself, even if it turns out to be our fault, because we can't work on |
your code.</li> |
<li>Annotate your code with comments that explain why you think that lcc is |
wrong. If lcc dies with an assertion failure, please tell us where it died. If |
lcc crashes, please report the last part of the call chain if you can. If lcc |
is rejecting a program you think is valid, please tell us why you think it's |
valid, and include supporting page numbers in the ANSI Standard or the |
appropriate section in <cite>C: A Reference Manual</cite>, 4th edition by S. B. Harbison |
and G. L. Steele, Jr. (Prentice Hall, 1995). If lcc silently generates incorrect code for |
some construct, please include the corrupt assembly code in the comments and flag the |
incorrect instructions if you can.</li> |
<li>Confirm that your error hasn't been fixed already. The latest version of lcc is always |
available for anonymous <code>ftp</code> from <code>ftp.cs.princeton.edu</code> in <a |
HREF="ftp://ftp.cs.princeton.edu/pub/lcc"><code>pub/lcc</code></a>. A <a |
HREF="ftp://ftp.cs.princeton.edu/pub/lcc/README"><code>README</code></a> file there gives |
acquisition details, and the <a HREF="../LOG"><code>LOG</code></a> file reports what errors |
were fixed and when they were fixed. If you report a error that's been fixed, you might |
get a canned reply.</li> |
<li>Post your program to the newsgroup <a href="news:comp.compilers.lcc"><code>comp.compilers.lcc</code></a> |
using a USENET newsreader like those at <a href="http://www.dejanews.com/">http://www.dejanews.com/</a> |
and <a href="http://groups.google.com/">http://groups.google.com/</a>. |
Please post only valid C programs; put all remarks in C comments so that we can process |
reports semi automatically.</li> |
</ol> |
|
<h2><a NAME="mailinglist">Keeping in Touch</a></h2> |
|
<p>The USENET newsgroup <a href="news:comp.compilers.lcc">comp.compilers.lcc</a> is an |
unmoderated newsgroup that serves as a forum for all topics related to the installation, |
use, and development of lcc. You can post messages to comp.compilers.lcc using any USENET |
newsreader or by visiting <a href="http://www.dejanews.com/">http://www.dejanews.com/</a>, |
which also includes an archive of recent postings.</p> |
|
<hr> |
|
<address> |
<a HREF="http://www.research.microsoft.com/~cwfraser/">Chris Fraser</a> / <a |
HREF="mailto:cwfraser@microsoft.com">cwfraser@microsoft.com</a><br> |
<a HREF="http://www.research.microsoft.com/~drh/">David Hanson</a> / <a |
HREF="mailto:drh@microsoft.com">drh@microsoft.com</a><br> |
$Revision: 1.45 $ $Date: 2002/09/04 18:33:24 $ |
</address> |
</body> |
</html> |
/bprint.1
0,0 → 1,83
.\" $Id: bprint.1,v 1.4 1998/08/24 21:18:18 drh Exp $ |
.TH BPRINT 1 "local \- $Date: 1998/08/24 21:18:18 $" |
.SH NAME |
bprint \- expression profiler |
.SH SYNOPSIS |
.B bprint |
[ |
.I option ... |
] |
[ |
.I file ... |
] |
.SH DESCRIPTION |
.I bprint |
produces on the standard output a listing of the programs compiled by |
.I lcc |
with the |
.B \-b |
option. |
Executing an |
.B a.out |
so compiled appends profiling data to |
.BR prof.out . |
The first token of each expression in the listing is preceded |
by the number of times it was executed |
enclosed in angle brackets as determined from the data in |
.BR prof.out . |
.I bprint |
interprets the following options. |
.TP |
.B \-c |
Compress the |
.B prof.out |
file, which otherwise grows with every execution of |
.BR a.out . |
.TP |
.B \-b |
Print an annotated listing as described above. |
.TP |
.B \-n |
Include line numbers in the listing. |
.TP |
.B \-f |
Print only the number of invocations of each function. |
A second |
.B \-f |
summarizes call sites instead of callers. |
.TP |
.BI \-I \*Sdir |
specifies additional directories in which to seek |
files given in |
.B prof.out |
that do not begin with `/'. |
.PP |
If any file names are given, only the requested data for those files are printed |
in the order presented. |
If no options are given, |
.B \-b |
is assumed. |
.SH FILES |
.PP |
.ta \w'$LCCDIR/liblcc.{a,lib}XX'u |
.nf |
prof.out profiling data |
$LCCDIR/liblcc.{a,lib} \fIlcc\fP-specific library |
.SH "SEE ALSO" |
.IR lcc (1), |
.IR prof (1) |
.SH BUGS |
Macros and comments can confuse |
.I bprint |
because it uses post-expansion source coordinates |
to annotate pre-expansion source files. |
If |
.I bprint |
sees that it's about to print a statement count |
.I inside |
a number or identifier, it moves the count to just |
.I before |
the token. |
.PP |
Can't cope with an ill-formed |
.BR prof.out . |