ifl/lcc: The lcc retargetable ANSI C compiler

doc/install.html
1 004 строки42 KB
David Hanson
Fixed typo in lburg command line; changed description of bprint
02 июн 1995, 20:02
02 июн 1995, 20:0229d5aa6
<HEADER>
<TITLE>Installing lcc</tt></title></HEADER>
<BODY>

<H1>Installing lcc</H1>

<b><a href="ftp://netlib.att.com/netlib/att/cs/home/cwfraser.html">Christopher W. Fraser</a><br>
AT&amp;T Bell Laboratories Rm. 2C-300,
600 Mountain Ave.,
Murray Hill, NJ 07974-0636<p>

<a href="http://www.cs.princeton.edu/faculty/drh/">David R. Hanson</a><br>
Department of Computer Science, Princeton University,
35 Olden St.,
Princeton, NJ 08544</b><p>

<h2>Contents</h2>

<ol>
<li><a href="#intro">Introduction</a>
<li><a href="#paths">Paths</a>
<li><a href="#preprocessor">Installing the Preprocessor</a>
<li><a href="#driver">Installing the Driver</a><br>
4.1 <a href="#bprint">Installing bprint</a>
<li><a href="#rcc">Installing the Compiler Proper</a><br>
5.1 <a href="#cross-compiler">Using lcc as Cross-Compiler</a><br>
5.2 <a href="#lburg">Installing the Code-Generator Generator</a>
<li><a href="#pc">lcc on a PC</a><br>
6.1 <a href="#pc-install">Installing lcc under DOS</a><br>
6.2 <a href="#pc-using">Using lcc under DOS</a><br>
6.3 <a href="#pc-build">Building lcc under DOS</a>
<li><a href="#bugs">Reporting Bugs</a>
<li><a href="#mailinglist">Keeping in Touch</a>
</ol>

<h2><a name="intro">1. Introduction</a></h2>

<a href="http://www.cs.princeton.edu/software/lcc/"><tt>lcc</tt></a>
is the ANSI C compiler described in our book
<cite>A Retargetable C Compiler: Design and Implementation</cite>
(Benjamin/Cummings, 1995, ISBN 0-8053-1670-1).<p>

Extract the distribution into its own directory.
All paths below are relative to this directory.
The distribution holds the following subdirectories.
<dl>
<dt><tt>src</tt>		<dd>source code
<dt><tt>etc</tt>		<dd>driver, accessories
<dt><tt>cpp</tt>		<dd>preprocessor source code
<dt><tt>lburg</tt>		<dd>code-generator generator source code
<dt><tt>doc</tt>		<dd>this document, man pages
<dt><tt>include</tt>		<dd>ANSI include files
<dt><tt>tst</tt>		<dd>test suite
<dt><tt>mips/* mips/*/tst</tt>	<dd>MIPS build directories, test outputs
<dt><tt>sparc/* sparc/*/tst</tt><dd>SPARC build directories, test outputs
<dt><tt>x86/* x86/*/tst</tt>	<dd>x86 build directories, test outputs
</dl>
Distributions include code generators for the MIPS, SPARC,
and the Intel 386 and its successors.<p>

Installation on Unix systems
involves three steps performed in the following order.<p>
<ol>
<li>Decide where to install the man page, the include files,
the compiler, and <tt>lcc</tt>, the driver program;
see <a href="#paths">Sec. 2</a>.<p>

<li>Install a preprocessor;
see <a href="#preprocessor">Sec. 3</a>.<p>

<li>Install a host-specific driver;
see <a href="#driver">Sec. 4</a>.<p>

<li>Install the compiler;
see <a href="#rcc">Sec. 5</a>.<p>
</ol>

The value of the variable <tt>rcsid</tt> in <tt>src/main.c</tt>
identifies the version of the distribution.
If the file <tt>LOG</tt> appears, it
describes the changes from the previous version.<p>

If you're installing <tt>lcc</tt> on a PC, go to
<a href="#pc">Sec. 6</a> after skimming Secs. 2-5.<p>

<tt>doc/install.html</tt> is the HTML file for this document.
<tt>doc/install.ps</tt> and <tt>doc/install.txt</tt>
are PostScript and plain ASCII versions.<p>

<h2><a name="paths">2. Paths</a></h2>

Installation consists of four files and one directory;
these are summarized below along with paths used in typical installations.
<dl>
<dt><tt>/usr/local/man/man1/lcc.1</tt>	<dd>the man page
<dt><tt>/usr/local/bin/lcc</tt>		<dd>the driver
<dt><tt>/usr/local/lib/cpp</tt>		<dd>the preprocessor
<dt><tt>/usr/local/lib/rcc</tt>		<dd>the compiler
<dt><tt>/usr/local/include/ansi</tt>	<dd>include files (a directory)
</dl>
These files can be placed in other, site-specific locations,
but the compiler should be named <tt>rcc</tt>.
If the driver isn't named <tt>lcc</tt>,
edit the man page (<tt>doc/lcc.1</tt>).<p>

Include files are in directories named
<tt>include/</tt><i>target</i><tt>/</tt><i>system</i>;
the meaningful combinations are
<dl>
<dt><tt>mips/irix</tt>		<dd>IRIX Release 4.0
<dt><tt>mips/ultrix</tt>	<dd>ULTRIX 4.3
<dt><tt>sparc/sun</tt>		<dd>SunOS 4.1
<dt><tt>sparc/solaris</tt>	<dd>Solaris 2.3
<dt><tt>x86/dos</tt>		<dd>DOS 6.0, Windows 3.1
</dl>
Choose the include files that are appropriate for your system,
or make a copy of a closely related set and edit them.<p>

For example, if the paths shown above are chosen and if
<tt>include/mips/ultrix</tt> has the appropriate include files,
install the man page and include files by
<pre>% cp doc/lcc.1 /usr/local/man/man1
% cp include/mips/ultrix/*.h /usr/local/include/ansi
</pre>

<h2><a name="preprocessor">3. Installing the Preprocessor</a></h2>

<tt>lcc</tt> is intended to be used with an ANSI preprocessor,
like the GNU C preprocessor available from the Free Software Foundation.
If you have the GNU C preprocessor, you can use it and skip the reset of this section.
You'll need the preprocessor's location to configure the driver, as described
in the <a href="#driver">next</a> section.<p>

The directory <tt>cpp</tt> contains the source code for an ANSI
preprocessor written by Dennis Ritchie.
It's written in ANSI C, so you
must use an ANSI C compiler to compile it. Alternatively, you
can install <tt>lcc</tt> with an existing preprocessor,
use <tt>lcc</tt> to build and install <tt>cpp</tt>, and
then reconfigure the driver to use the new <tt>cpp</tt>.<p>

To build and install <tt>cpp</tt>,
execute the commands
<pre>% cd cpp
% make
% cp cpp /usr/local/lib
</pre>
where the destination is the location chosen for <tt>cpp</tt>
in <a href="#paths">Sec. 2</a>. Use the <tt>CC=</tt> option to specify
an ANSI C compiler, if necessary; e.g., <tt>CC=gcc</tt>.
The command ``<tt>make clean</tt>''
cleans up, but does not remove <tt>cpp</tt>, and
``<tt>make clobber</tt>''
cleans up and removes <tt>cpp</tt>.<p>

This preprocessor makes <em>no</em> assumptions about
the standard include files. You must specify the appropriate
<tt>-I</tt> options in the <tt>include</tt> array defined
in the host-specific part of the driver, as detailed in the next section.<p>

<h2><a name="driver">4. Installing the Driver</a></h2>

The preprocessor, compiler, assembler, and loader are
invoked by a driver program, <tt>lcc</tt>, which is similar
to <tt>cc</tt> on most systems. It's described in the man page
<tt>doc/lcc.1</tt>.
The driver is built by combining the host-independent
part, <tt>etc/lcc.c</tt>, with a small host-specific part.
By convention, host-specific parts are named <i>hostname</i><tt>.c</tt>,
where <i>hostname</i> is the local name for the host on which <tt>lcc</tt>
is being installed. <tt>etc</tt> holds many examples.
Comments in most give the details of the
particular host; pick one that is closely related to your host,
copy it to <tt>etc/</tt><i>yourhostname</i><tt>.c</tt>,
and edit it as described below.
You should not have to edit <tt>etc/lcc.c</tt>.<p>

Debug your version of the driver by running it
with the <tt>-v -v</tt> options, which cause it to echo the
commands it would execute, but not to execute them.<p>

Here's <tt>etc/hart.c</tt>, which we'll use as an example
in describing how to edit a host-specific part.
This example illustrates all the important features.
<pre>/* DECStations running ULTRIX at Princeton University */

#include &lt;string.h&gt;

char *cpp[] = {
        "/usr/gnu/lib/gcc-cpp", "-undef",
        "-DLANGUAGE_C", "-D_LANGUAGE_C", "-D__LANGUAGE_C",
        "-D_unix", "-D__unix", "-Dultrix", "-D_ultrix", "-D__ultrix",
        "-Dmips", "-D_mips", "-D__mips",
        "-Dhost_mips", "-D_host_mips", "-D__host_mips",
        "-DMIPSEL", "-D_MIPSEL", "-D__MIPSEL",
        "$1", "$2", "$3", 0 };
char *include[] = { "-I/usr/local/include/ansi", 0 };
char *com[] =  { "/usr/local/lib/rcc", "-target=mips-ultrix",
        "$1", "$2", "$3", 0 };
char *as[] =  { "/bin/as", "-o", "$3", "", "$1",
        "-nocpp", "-EL", "$2", 0 };
char *ld[] =  { "/usr/bin/ld", "-o", "$3", "/usr/lib/crt0.o",
        "$1", "$2", "", "", "-lm", "-lc", 0 };

int option(arg) char *arg; {
        if (strcmp(arg, "-g") == 0)
                as[3] = "-g";
        else if (strcmp(arg, "-p") == 0
        &amp;&amp; strcmp(ld[3], "/usr/lib/crt0.o") == 0) {
                ld[3] = "/usr/lib/mcrt0.o";
                ld[7] = "/usr/lib/libprof1.a";
        } else if (strcmp(arg, "-b") == 0
        &amp;&amp; access("/usr/local/lib/bbexit.o", 4) == 0)
                ld[6] = "/usr/local/lib/bbexit.o";
        else
                return 0;
        return 1;
}
</pre>

Most of the host-specific code is data that
gives prototypes for the commands that invoke
the preprocessor, compiler, assembler, and loader.
Each command prototype is an array of pointers to strings
terminated with a null pointer;
the first string is the full path name of the command and the others
are the arguments or argument placeholders, which are described below.<p>

The <tt>cpp</tt> array gives the command for running the preprocessor.
<tt>lcc</tt> is intended to be used with an ANSI preprocessor,
like the GNU C preprocessor.
If the GNU C preprocessor is used, as shown in this example,
it must be named <tt>gcc-cpp</tt> in order for <tt>lcc</tt>'s <tt>-N</tt> option
to work correctly.<p>

Literal arguments specified in prototypes, e.g., <tt>"-Dmips"</tt> in
the <tt>cpp</tt> command above, are passed to the command as given.<p>

The strings <tt>"$1"</tt>, <tt>"$2"</tt>, and <tt>"$3"</tt> in
prototypes are placeholders for <em>lists</em> of arguments that
are substituted in a copy of the prototype before the command is executed.
<tt>$1</tt> is replaced by the <em>options</em> specified by the user;
for the preprocessor, this list always contains at least
<tt>-Dunix</tt> and <tt>-D__LCC__</tt>.
<tt>$2</tt> is replaced by the <em>input</em> files,
and <tt>$3</tt> is replaced by the <em>output</em> file.<p>

Zero-length arguments after replacement are removed from
the argument list before the command is invoked. So, e.g.,
if the preprocessor is invoked without an output file,
<tt>"$3"</tt> becomes <tt>""</tt>, which is removed from the final argument list.<p>

For example, to specify a preprocessor command prototype to invoke the
preprocessor installed in <a href="#preprocessor">Sec. 3</a>
with the options <tt>-Dmips</tt> and <tt>-Dultrix</tt>,
the <tt>cpp</tt> array would be
<pre>char *cpp[] = { "/usr/local/lib/cpp", "-Dmips", "-Dultrix",
        "$1", "$2", "$3", 0 };
</pre>
where <tt>cpp[0]</tt> is the location chosen for <tt>cpp</tt>
in <a href="#paths">Sec. 2</a>.<p>

The <tt>include</tt> array is a list of <tt>-I</tt> 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 in <a href="#paths">Sec. 2</a>.
The driver adds these options to <tt>cpp</tt>'s arguments
when it invokes the preprocessor, except when <tt>-N</tt> is specified.<p>

Design this list carefully. Mixing ANSI and pre-ANSI headers (e.g., by
listing <tt>/usr/include</tt> after the directory of ANSI headers,
as shown above) may mix incompatible headers.
Unless the default list holds <em>only</em>
<tt>/usr/include</tt> or <em>only</em> the ANSI headers, many users may be
forced to use <tt>-N</tt> and <tt>-I</tt> incessantly.<p>

<tt>com</tt> gives the command for invoking the compiler.
This prototype can appear as shown above, with two important
changes. The command name should be edited to reflect the
location of the compiler chosen in <a href="#paths">Sec. 2</a>,
and the option <tt>-target=mips-ultrix</tt> should be edited
to the <i>target</i><tt>-</tt><i>system</i> for your host.
<tt>lcc</tt> can generate
code for <em>all</em> of the <i>target</i><tt>-</tt><i>system</i>
combinations listed in the file <tt>src/bind.c</tt>. The <tt>-target</tt>
option specifies the default combination. The driver's <tt>-Wf</tt> option
can be used to specify other combinations;
the <a href="lcc.1.html">man page</a> elaborates.<p>

<tt>as</tt> gives the command for invoking the assembler.<p>

<tt>ld</tt> gives the command for invoking the loader.
For the other commands, the list <tt>$2</tt> contains a single file;
for <tt>ld</tt>, <tt>$2</tt> contains all ``.o'' files and libraries, and
<tt>$3</tt> is <tt>a.out</tt>, unless the <tt>-o</tt> option is specified.
As suggested in the code above, <tt>ld</tt> must also specify
the appropriate startup code and default libraries.<p>

The <tt>option</tt> function is described below;
for now, use an existing <tt>option</tt> function or one that returns 0.<p>

After specifying the prototypes, compile the driver by
<pre>% cd etc
% make HOST=hart
cc  -c hart.c
cc  -c lcc.c
cc -s hart.o lcc.o; rm -f hart.o lcc.o
</pre>
where <tt>hart</tt> is replaced by <i>yourhostname</i>.
Run the resulting <tt>a.out</tt> with the options <tt>-v -v</tt>
to display the commands that would be executed, e.g.,
<pre>% a.out -v -v foo.c baz.c mylib.a -lX11
a.out $ Revision: 3.2 $ $ Date: 1994/09/08 17:15:13 $
foo.c:
/usr/gnu/lib/gcc-cpp -undef -DLANGUAGE_C -D_LANGUAGE_C -D__LANGUAGE_C
   -D_unix -D__unix -Dultrix -D_ultrix -D__ultrix -Dmips -D_mips -D__mips
   -Dhost_mips -D_host_mips -D__host_mips -DMIPSEL -D_MIPSEL -D__MIPSEL
   -Dunix -D__LCC__ -v -I/usr/local/include/ansi foo.c |
   /usr/local/lib/rcc -target=mips-ultrix -v - /tmp/lcc11717.s
/bin/as -o foo.o -nocpp -EL /tmp/lcc11717.s
baz.c:
/usr/gnu/lib/gcc-cpp -undef -DLANGUAGE_C -D_LANGUAGE_C -D__LANGUAGE_C
   -D_unix -D__unix -Dultrix -D_ultrix -D__ultrix -Dmips -D_mips -D__mips
   -Dhost_mips -D_host_mips -D__host_mips -DMIPSEL -D_MIPSEL -D__MIPSEL
   -Dunix -D__LCC__ -v -I/usr/local/include/ansi baz.c |
   /usr/local/lib/rcc -target=mips-ultrix -v - /tmp/lcc11717.s
/bin/as -o baz.o -nocpp -EL /tmp/lcc11717.s
/usr/bin/ld -o a.out /usr/lib/crt0.o foo.o baz.o mylib.a -lX11 -lm -lc
rm /tmp/lcc11717.s
</pre>
Leading spaces indicate lines that have been folded manually to fit this page.
Note the use of a pipeline to connect the preprocessor and compiler.
<tt>lcc</tt> arranges this pipeline itself; it does not call the shell.
If you want <tt>lcc</tt> to use temporary files instead of a pipeline,
define <tt>PIPE=0</tt> in <tt>CFLAGS</tt> when making the driver:
<pre>% make CFLAGS='-DPIPE=0' HOST=hart
</pre>
The option <tt>-pipe</tt> forces <tt>lcc</tt>
to use a pipeline between the preprocessor and the compiler
regardless of <tt>PIPE</tt>'s value.<p>
 
As the output shows, <tt>lcc</tt> places temporary files in <tt>/tmp</tt>.
Alternatives can be specified by defining <tt>TEMPDIR</tt> in <tt>CFLAGS</tt>
when making the driver, e.g.,
<pre>% make CFLAGS='-DTEMPDIR=\"/usr/tmp\"' HOST=hart
</pre>
causes <tt>lcc</tt> to place temporary files in <tt>/usr/tmp</tt>.

Once the driver is completed, install it by
<pre>% cp a.out /usr/local/bin/lcc
</pre>
where the destination is the location chosen for <tt>lcc</tt>
in <a href="#paths">Sec. 2</a>.<p>

The <tt>option</tt> function is called for the options
<tt>-g</tt>, <tt>-p</tt>, <tt>-pg</tt>, and <tt>-b</tt> because
these compiler options might also affect the loader's arguments.
For these options,
the driver calls <tt>option(arg)</tt> to give the host-specific
code an opportunity to edit the <tt>ld</tt> command, if necessary.
<tt>option</tt> can change <tt>ld</tt>, if necessary, and return 1 to
announce its acceptance of the option. If the option
is unsupported, <tt>option</tt> should return 0.<p>

For example, in response to <tt>-g</tt>, the <tt>option</tt> function shown above
changes <tt>as[3]</tt> from <tt>""</tt> to <tt>"-g"</tt>, which specifies
the debugging option to the assembler. If <tt>-g</tt> is not specified,
the <tt>""</tt> argument is omitted from the <tt>as</tt> command
because it's empty.<p>

Likewise, the <tt>-p</tt> causes <tt>option</tt> to change the name
of the startup code and add the name of the profiling library. Note that
<tt>option</tt> has been written to support simultaneous use
of <tt>-g</tt> and <tt>-p</tt>, e.g.,
<pre>% a.out -v -v -g -p foo.s baz.o -o myfoo
a.out $ Revision: 3.2 $ $ Date: 1994/09/08 17:15:13 $
/bin/as -o foo.o -g -nocpp -EL foo.s
/usr/bin/ld -o myfoo /usr/lib/mcrt0.o foo.o baz.o
   /usr/lib/libprof1.a -lm -lc
rm /tmp/lcc12270.s
</pre>
On Suns, the driver also
recognizes <tt>-Bstatic</tt> and <tt>-Bdynamic</tt> as linker options,
and recognizes but ignores Sun's ``<tt>-target</tt> <i>name</i>'' option.<p>

The option <tt>-Wo</tt><i>arg</i> causes the driver to pass <i>arg</i>
to <tt>option</tt>. Such options have no other effect; this mechanism
is provided to support system-specific options that affect the
commands executed by the driver.<p>

To complete the driver,
write an appropriate <tt>option</tt> function for your system,
and make and install the driver as described above.<p>

<h3><a name="bprint">4.1 Installing bprint</a></h3>

The <tt>-b</tt> option causes the compiler to generate
code to count the number of times each expression is executed.
The <tt>exit</tt> function in <tt>etc/bbexit.c</tt> writes these
counts to <tt>prof.out</tt> when the program terminates.
If <tt>option</tt> is called with <tt>-b</tt>,
it must edit the <tt>ld</tt> command accordingly,
as shown above. This version of <tt>option</tt> uses
the <tt>access</tt> system call to insure that <tt>bbexit.o</tt> is installed before
editing the <tt>ld</tt> command. To install <tt>bbexit.o</tt> execute
<pre>% make bbexit.o
% cp bbexit.o /usr/local/lib/bbexit.o
</pre>
If necessary, change <tt>/usr/local/lib</tt> to reflect local conventions.
The <tt>exit</tt> function in <tt>etc/bbexit.c</tt> works on the
systems listed in <a href="#paths">Sec. 2</a>,
but may need to be modified for other systems.<p>

If <tt>option</tt> supports <tt>-b</tt>, you should also
install <tt>etc/bprint.c</tt>, which reads <tt>prof.out</tt>
and generates a listing annotated with execution counts.
After <tt>lcc</tt> is installed, install <tt>bprint</tt> with the commands
<pre>% make bprint
% cp bprint /usr/local/bin/bprint
% cp ../doc/bprint.1 /usr/local/man/man1
</pre>
You must use <tt>lcc</tt> or another ANSI C compiler, e.g., <tt>gcc</tt>,
because <tt>bprint.c</tt> is written in ANSI C.<p>

<h2><a name="rcc">5. Installing the Compiler Proper</a></h2>

The compiler proper, <tt>rcc</tt>, is built by compiling it
with the host C compiler and then using the result to re-compile itself.
A test suite is used to
verify that the compiler is working correctly.
The examples below illustrate this process on a MIPS under Ultrix.
You must have the driver, <tt>lcc</tt>, installed in order
to test <tt>rcc</tt>.
If any of the steps below fail, contact us
(see <a href="#bugs">Sec. 7</a>).<p>

The object files, <tt>rcc</tt>, and the generated code for
the programs in the test suite are placed in the directory
<i>target/system</i> where <i>target</i> and <i>system</i>
are the names of your target machine and its operating system, respectively.
There are directories for the supported
<i>target/system</i> combinations, e.g., <tt>mips/ultrix</tt>.<p>

The default target in <tt>src/makefile</tt> is <tt>rcc</tt>.
<tt>lcc</tt> is built by executing <tt>make</tt> from the
apppropriate <i>target/system</i> directory
and specifying system-specific values for <tt>CFLAGS</tt> and <tt>LDFLAGS</tt>,
if necessary.
For example, to build <tt>rcc</tt> for a MIPS running Ultrix,
execute the commands
<pre>% cd mips/ultrix
% make -f ../../src/makefile 
cc -c -O ../../src/alloc.c
...
cc -c -O ../../src/x86.c
cc -o rcc  alloc.o bind.o ... mips.o sparc.o x86.o
</pre>
There may be a few warnings, but there should be no errors.
If your host is an SGI machine running IRIX 4.0 or later,
you might need <tt>CFLAGS=-cckr</tt>.
If <tt>cc</tt> doesn't automatically search the directory that holds
the source file, specify <tt>CFLAGS=-I../../src</tt>.
If you use <tt>gcc</tt>, specify <tt>CFLAGS="-ansi -fno-builtin"</tt>.<p>

Once <tt>rcc</tt> is built with the host C compiler,
run the test suite to verify that <tt>rcc</tt> is working correctly.
The commands in <tt>src/makefile</tt> run the shell script
<tt>src/run</tt> on each C program in the test suite, <tt>tst/*.c</tt>.
It uses the driver, <tt>lcc</tt>, so you must
have the driver installed before testing <tt>rcc</tt>.
The <i>target</i><tt>-</tt><i>system</i> combination is read from the
variable <tt>TARGET</tt>, which is specified when invoking <tt>make</tt>:
<pre>% make -f ../../src/makefile TARGET=mips-ultrix test
../rcc -target=mips-ultrix 8q:
../rcc -target=mips-ultrix array:
../rcc -target=mips-ultrix cf:
../rcc -target=mips-ultrix cq:
../rcc -target=mips-ultrix cvt:
../rcc -target=mips-ultrix fields:
../rcc -target=mips-ultrix front:
../rcc -target=mips-ultrix incr:
../rcc -target=mips-ultrix init:
../rcc -target=mips-ultrix limits:
../rcc -target=mips-ultrix paranoia:
../rcc -target=mips-ultrix sort:
../rcc -target=mips-ultrix spill:
../rcc -target=mips-ultrix stdarg:
../rcc -target=mips-ultrix struct:
../rcc -target=mips-ultrix switch:
../rcc -target=mips-ultrix wf1:
../rcc -target=mips-ultrix yacc:
</pre> 
For each C program in the test suite,
<tt>src/run</tt> compiles the program and uses <tt>diff</tt>
to compare the generated assembly code
with the expected code (the MIPS code expected for <tt>tst/8q.c</tt> is
in <tt>mips/ultrix/tst/8q.sbk</tt>, etc.).
If there are differences, the script
executes the generated code with the input given in <tt>tst</tt>
(the input for <tt>tst/8q.c</tt> is in <tt>tst/8q.0</tt>, etc.)
and compares the output with the expected output
(the expected output from <tt>tst/8q.c</tt> on the MIPS is
in <tt>mips/ultrix/tst/8q.1bk</tt>, etc.). The script also compares the
diagnostics from the compiler with the expected diagnostics.<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
on a MIPS and the least significant bits of some floating-point constants
differ from those bits in constants generated on your system.
There should be no differences in the output from executing the test programs.<p>

The <tt>../rcc</tt> and <tt>-target=mips-ultrix</tt> preceding the name of
each test program in the output
above indicate the compiler and the target, e.g.,
``<tt>../rcc</tt> is generating code for a <tt>mips</tt> running the
<tt>ultrix</tt> operating system.''<p>

Next, build <tt>rcc</tt> again using the just-built <tt>rcc</tt>:
<pre>%  make -f ../../src/makefile TARGET=mips-ultrix triple
rm -f *.o
make -f ../../src/makefile CC='lcc -B./ -d0.1 -A'
   CFLAGS='-Wf-target=mips-ultrix
   -I../../src/../include/`echo mips-ultrix|tr - /`
   -I../../src' LDFLAGS=''
lcc -B./ -d0.1 -A -c -Wf-target=mips-ultrix
   -I../../src/../include/`echo mips-ultrix|tr - /`
   -I../../src ../../src/alloc.c
...
lcc -B./ -d0.1 -A -c -Wf-target=mips-ultrix
   -I../../src/../include/`echo mips-ultrix|tr - /`
   -I../../src ../../src/x86.c
lcc -B./ -d0.1 -A -o rcc  alloc.o ... sparc.o x86.o
strip rcc
od rcc +8 &gt;od2
rm -f *.o
make -f ../../src/makefile CC='lcc -B./ -d0.1 -A'
   CFLAGS='-Wf-target=mips-ultrix
   -I../../src/../include/`echo mips-ultrix|tr - /`
   -I../../src' LDFLAGS=''
lcc -B./ -d0.1 -A -c -Wf-target=mips-ultrix
   -I../../src/../include/`echo mips-ultrix|tr - /`
   -I../../src ../../src/alloc.c
...
lcc -B./ -d0.1 -A -c -Wf-target=mips-ultrix
   -I../../src/../include/`echo mips-ultrix|tr - /`
   -I../../src ../../src/x86.c
lcc -B./ -d0.1 -A -o rcc  alloc.o ... sparc.o x86.o
strip rcc
od rcc +8 &gt;od3
cmp od[23] &amp;&amp; rm od[23]
</pre>
This command builds <tt>rcc</tt> twice; once using the
<tt>rcc</tt> built by <tt>cc</tt>
and again using the <tt>rcc</tt> built by <tt>lcc</tt>.
After building each version, an octal dump of the resulting binary is made,
and the two dumps are compared. They should be identical, as shown
at the end of the output above.
If they aren't, our compiler is generating bad code;
<a href="#bugs">contact</a> us.<p>

The final version of <tt>rcc</tt> should also pass the test suite;
i.e., the output from
<pre> make -f ../../src/makefile TARGET=mips-ultrix test
</pre>
should be identical to that from the previous <tt>make test</tt>.<p>

Now install the final version of <tt>rcc</tt>:
<pre>% cp rcc /usr/local/lib/rcc
</pre>
where the destination is the location chosen for <tt>rcc</tt>
in <a href="#paths">Sec. 2</a>.<p>

On some systems, you may be able
to use environment variables and <tt>make</tt>'s <tt>-e</tt>
option to avoid specifying <tt>TARGET</tt>
on each <tt>make</tt> command, and
the <tt>make</tt> commands described above can be done with a single command:
<pre>% setenv TARGET mips-ultrix
% cd mips/ultrix
% make -e -f ../../src/makefile test triple test clean
</pre>
The command
<pre>make -f ../../src/makefile clean
</pre> cleans up, but does not remove <tt>rcc</tt>, and
<pre>make -f ../../src/makefile clobber
</pre>
cleans up and removes <tt>rcc</tt>.<p>

The code generators for the other targets can be tested by running
<tt>make</tt> from the appropriate target-specific directory and setting some
environment variables to control what <tt>src/run</tt> does.
For example, if you built <tt>mips/ultrix/rcc</tt> and installed
it in <tt>/usr/local/lib/rcc</tt>, you can
test the SPARC code generator for the SunOS operating system as follows.
<pre>% setenv REMOTEHOST noexecute
% setenv BUILDDIR /usr/local/lib/
% cd sparc/sun
% make -f ../../src/makefile RCC= TARGET=sparc-sun test
/usr/local/lib/rcc -target=sparc-sun 8q:
/usr/local/lib/rcc -target=sparc-sun array:
/usr/local/lib/rcc -target=sparc-sun cf:
/usr/local/lib/rcc -target=sparc-sun cq:
/usr/local/lib/rcc -target=sparc-sun cvt:
/usr/local/lib/rcc -target=sparc-sun fields:
/usr/local/lib/rcc -target=sparc-sun front:
/usr/local/lib/rcc -target=sparc-sun incr:
/usr/local/lib/rcc -target=sparc-sun init:
/usr/local/lib/rcc -target=sparc-sun limits:
/usr/local/lib/rcc -target=sparc-sun paranoia:
/usr/local/lib/rcc -target=sparc-sun sort:
/usr/local/lib/rcc -target=sparc-sun spill:
/usr/local/lib/rcc -target=sparc-sun stdarg:
/usr/local/lib/rcc -target=sparc-sun struct:
/usr/local/lib/rcc -target=sparc-sun switch:
/usr/local/lib/rcc -target=sparc-sun wf1:
/usr/local/lib/rcc -target=sparc-sun yacc:
</pre>
As above, <tt>src/run</tt> compares the
SPARC code generated with what's expected.
There should be no differences.
Setting <tt>REMOTEHOST</tt> to <tt>noexecute</tt> suppresses
the assembly and execution of the generated code.
<tt>BUILDDIR</tt> gives the directory that holds <tt>rcc</tt>,
and specifying <tt>RCC=</tt> to <tt>make</tt> insures that
<tt>rcc</tt> is not rebuilt in the <tt>sparc/sun</tt> directory.<p>

If you set <tt>REMOTEHOST</tt>
to the name of a SPARC machine to which you can <tt>rlogin</tt>,
<tt>src/run</tt> will <tt>rcp</tt> the generated code to that machine
and execute it there, if necessary. See <tt>src/run</tt> for the details.<p>

<h3><a name="cross-compiler">5.1 Using lcc as Cross-Compiler</a></h3>

Once everything is installed, you can use <tt>lcc</tt> as a cross compiler.
The options <tt>-S</tt> and <tt>-Wf-target=</tt><i>target-system</i>
generate assembly code for the specified target, which
is any of those listed in the file <tt>src/bind.c</tt>.
For example,
<pre>% lcc -Wf-target=sparc-sun -S tst/8q.c
</pre>
generates SPARC code for <tt>tst/8q.c</tt> in <tt>8q.s</tt>.<p>
<tt>lcc</tt> 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 <tt>-Wf-target=symbolic</tt>. For example,
<pre>% lcc -Wf-target=symbolic -S tst/8q.c
</pre>
generates symbolic output for <tt>tst/8q.c</tt> in <tt>8q.s</tt>.
Finally, the option <tt>-Wf-target=null</tt> specifies the ``null''
target for which <tt>lcc</tt> emits nothing and thus only checks
the syntax and semantics of its inputs files.<p>

<h3><a name="lburg">5.2 Installing the Code-Generator Generator</a></h3>

The directory <tt>lburg</tt> holds the source
code for the code-generator generator. To build <tt>lburg</tt>,
execute the commands
<pre>% cd lburg
% make
</pre>
You must use <tt>lcc</tt> or another ANSI C compiler, e.g., <tt>gcc</tt>,
because <tt>lburg</tt> is written in ANSI C.<p>

To test <tt>lburg</tt>, use it process one of the machine
descriptions in <tt>src/*.md</tt> and compare the output with
the corresponding <tt>src/*.c</tt> file. For example,
<pre>% lburg <../src/x86.md | diff ../src/x86.c -
40c40
< generated at Mon Dec  5 17:49:52 1994
---
> generated at Tue Dec  6 13:35:42 1994
</pre>
processes <tt>src/x86.md</tt> and compares the output with
what's expected. You may get 1-2 lines of differences, because
<tt>lburg</tt>'s output includes a timestamp and a version stamp.
Move <tt>lburg</tt> to the desired
installation directory.
The command ``<tt>make clean</tt>''
cleans up, but does not remove <tt>lburg</tt>, and
``<tt>make clobber</tt>''
cleans up more and removes <tt>lburg</tt>.<p>

<tt>src/makefile</tt> includes three rules for building
<tt>src/mips.c</tt>,
<tt>src/sparc.c</tt>, and
<tt>src/x86.c</tt> from the corresponding machine descriptions in
<tt>src/mips.md</tt>,
<tt>src/sparc.md</tt>, and
<tt>src/x86.md</tt>. These rules are commented out in the distributed
<tt>src/makefile</tt>; remove the leading ``<tt>#</tt>'' to uncomment
these lines, if you want to run <tt>lburg</tt> whenever these <tt>src/*.md</tt>
files are changed. You may also want to remove the leading ``<tt>#</tt>''
on the <tt>rm</tt> command in the <tt>clobber</tt> rule, if you want
``<tt>make clobber</tt>'' to remove the <tt>src/*.c</tt> files generated
by <tt>lburg</tt>.<p>

Chapters 13-15 in
<cite>A Retargetable C Compiler: Design and Implementation</cite>
describe the overall structure of <tt>lcc</tt>'s code generator,
and the use of <tt>lburg</tt>. Chapters 16-18 describe the target-specific
parts, including the <tt>lburg</tt> rules,
for the MIPS, SPARC, and x86 architectures.
The easiest way to write a code generator for a new target
is to make a copy of the <tt>.md</tt> file for the architecture that's closest to your
intended target, and edit the copy, using the corresponding chapter
as a guide.<p>

For example, the following steps add a code generator for the PowerPC under AIX.
<ol>
<li>Copy <tt>src/mips.md</tt> to, say, <tt>src/power.md</tt>,
and edit this copy into a code generator for the PowerPC.<p>

<li>Edit <tt>src/makefile</tt>:
Add <tt>power.o</tt> to the definition of <tt>OBJS</tt>, and add
the following rules.
<pre>power.o:	$(SRC)/power.c;		$(CC) -c $(CFLAGS) $(SRC)/power.c
$(SRC)/power.c:	$(SRC)/power.md;	lburg &lt;$(SRC)/power.md &gt;$(SRC)/power.c
</pre><p>

<li>Create the directories <tt>power</tt>, <tt>power/aix</tt>, and
<tt>power/aix/tst</tt>.<p>

<li>Bind the new code generator
to the front end by including it in the initialization of
<tt>bindings</tt> in <tt>src/bind.c</tt> as described in Section 5.11
of <cite>A Retargetable C Compiler</cite>. For example, if the variable
<tt>powerIR</tt> is the interface record for the PowerPC code generator,
add the declaration
<pre>extern Interface powerIR;
</pre>
to the beginning of <tt>src/bind.c</tt>, and add the line
<pre>"power-aix",       &amp;powerIR,
</pre>
to the initialization of <tt>bindings</tt>.<p>

</ol>
Once these steps are completed, the commands
<pre>% cd power/aix
% make -f ../../src/makefile TARGET=power-aix
</pre>
build an <tt>rcc</tt> that includes
the new code generator. It's a good idea to do all these steps
changing <tt>src/power.md</tt> as little as possible to get the
machinery in place first, then finish editing <tt>src/power.md</tt>
into the new code generator.<p>

<h2><a name="pc">6. lcc on a PC</a></h2>

This section describes installing and operating <tt>lcc</tt> under MS-DOS.
Read all sections above first. The DOS distribution does not support
<tt>lcc</tt>'s <tt>-b</tt>, <tt>-g</tt>, and <tt>-p</tt> options.<p>

On the X86, <tt>lcc</tt> emits assembler code that uses a 32-bit flat address
space. It requires an external assembler, linker, library, and DOS
extender. We assemble <tt>lcc</tt>'s emitted code with Borland Turbo
Assembler 4.0 or Microsoft's MASM 6.11, and we turn the resulting
object code into a <tt>.exe</tt> file using the linker, library, and DOS
extender from Borland C++ 4.02 plus Borland PowerPack for DOS.
Warning: Borland's start-up code initializes the floating-point unit
to convert floats and doubles to integers by rounding
instead of truncating them, which the ANSI Standard specifies.<p>

Small changes to <tt>src\x86.c</tt> have allowed it to work with the linker,
library, and DOS extender from Symantec C++ 6.1.<p>

<h3><a name="pc-install">6.1 Installing lcc under DOS</a></h3>

The distribution includes the following files:
<dl>
<dt><tt>x86\dos\cpp.exe</tt>		<dd>the preprocessor
<dt><tt>x86\dos\rcc.exe</tt>		<dd>the compiler proper
<dt><tt>x86\dos\lcc.exe</tt>		<dd>the compiler's driver
<dt><tt>x86\dos\32rtm.exe</tt>		<dd>Borland PowerPack runtime manager
<dt><tt>x86\dos\dpmi32vm.ovl</tt>	<dd>Borland PowerPack DPMI server
<dt><tt>x86\dos\windpmi.386</tt>	<dd>Borland PowerPack Windows DPMI driver
</dl>
Copy the <tt>.exe</tt> and <tt>.ovl</tt> files to a directory
in your <tt>PATH</tt>. If you want to use <tt>lcc</tt>
in a full-screen DOS window under Windows 3.1, copy
<tt>windpmi.386</tt> to your <tt>\windows\system</tt> directory,
and add the lines
<pre>[386Enh]
device=windpmi.386
</pre>
to your <tt>system.ini</tt> (which is located in <tt>\windows</tt>).<p>

<tt>lcc.exe</tt> is a prebuilt driver for use with
Borland's Turbo Assembler 4.0, Borland C++ 4.02, and Borland PowerPack
for DOS.
To use some other combination of assembler, linker, library,
and DOS extender, or to change the path names compiled into the
driver, you will have to build a new driver.
You'll probably have to modify the driver
and <tt>include\x86\dos\*.h</tt> if you want to use them.
The source code for the PC version of the driver is in
<tt>etc\lcc-pc.c</tt> and <tt>etc\bc4.c</tt>.
It is unlikely that you'll need to rebuild
<tt>cpp.exe</tt> or <tt>rcc.exe</tt>.<p>

<tt>lcc</tt> comes with a preprocessor and ANSI include files
(<tt>include\x86\dos\*.h</tt>) that work with the library and DOS extender
included with Symantec C++ 6.1. Include files are generally tailored,
however, for a specific library, so use the headers that come with
your library, or adapt <tt>lcc</tt>'s headers to work with your library.<p>

If you use headers that exploit language extensions, you must also use
their companion preprocessor, or you must protect <tt>cpp.exe</tt> from the
extensions, because <tt>cpp.exe</tt> obeys the ANSI specification. For
example, when we use <tt>lcc</tt> with the library from Borland C++ 4.02, we
use Borland's headers too, and they annotate many declarations with a
non-ANSI attribute, <tt>__cdecl</tt>.
The distribution's <tt>cpp.exe</tt> won't recognize <tt>__cdecl</tt>,
so we use the <tt>cpp.exe</tt> option <tt>-D__cdecl=</tt> to
eliminate this extension, or we use Borland's preprocessor.

<h3><a name="pc-using">6.2 Using lcc under DOS</a></h3>

The default executable file is <tt>a.exe</tt>, and object files
have the extension <tt>.obj</tt>.
The other extensions are as described in <a href="#driver">Sec. 4</a>,
above, including assembler files, which
end in <tt>.s</tt>, not <tt>.asm</tt>.<p>

The Unix driver for <tt>lcc</tt> invokes the
process for each compiler subphase that's needed.
In principle, the DOS driver could do likewise, but
doing so fails under at least some DOS extenders. For maximum
portability, the distributed DOS driver thus merely emits a command
file, into <tt>dolcc.bat</tt> in the current directory,
which must be run to compile anything; for example,
<pre>C:> lcc 8q.c
C:> dolcc.bat
</pre>
compiles, assembles, and links <tt>8q.c</tt>. and leaves the
executable in <tt>a.exe</tt>.
<tt>lcc.exe</tt> writes commands to <tt>dolcc.bat</tt> that
generate and consume temporary files. These files have names
like <tt>c:\tmp\lcc</tt><i>ddddd</i><tt>.*</tt>, so
create the directory <tt>c:\tmp</tt>, if it doesn't exist.<p>

Users running programs like <tt>doskey</tt> can easily create a macro that
abbreviates this idiom, but makefiles and batch files must invoke
<tt>dolcc.bat</tt> explicitly.
If the library routines <tt>system</tt> or <tt>execv</tt> work
with your DOS extender, you might be able to modify the routine
<tt>execute</tt> in <tt>etc\lcc-pc.c</tt> to avoid this irritation.<p>

Note that the distributed <tt>lcc.exe</tt> obviates
the option <tt>-v -v</tt> decsribed in <a href="#driver">Sec. 4</a>
because it never executes commands anyway.
Also, it complicates the idiom that saves
the preprocessed source in a file. That is,
<pre>C:> lcc -E 8q.c &gt;8q.i
</pre>
fails to capture the preprocessed <tt>8q.c</tt> in <tt>8q.i</tt>
because <tt>lcc.exe</tt> creates
but does not execute a preprocessor command.<p>

<h3><a name="pc-build">6.3 Building lcc under DOS</a></h3>

It is not likely that you'll need to rebuild <tt>cpp.exe</tt>,
nor is it likely that you'll need to
rebuild <tt>rcc.exe</tt>, unless your assembler or library, say, requires the
compiler to emit different assembler code. Read the rest of this
section only if you need to modify <tt>rcc.exe</tt>.<p>

On MS-DOS systems, several batch files replace the Unix make and shell
files described in the sections above. <tt>src\triple.bat</tt> replaces the
<tt>make triple</tt> process described in <a href="#rcc">Sec. 5</a>.
It calls <tt>src\lccn.bat</tt> to
compile <tt>lcc</tt>'s modules using <tt>lcc.exe</tt>.
<tt>src\test.bat</tt> runs <tt>lcc</tt>'s test
suite. It calls <tt>src\run.bat</tt> once for each test program. The batch
files compile the test files in the directory <tt>x86\dos\tst</tt>, but they
compile the compiler itself in the <tt>src</tt> directory.
<tt>lccn.bat</tt> and <tt>run.bat</tt>
include <tt>dolcc.bat</tt> as a hard path name; edit them if you
changed the driver to deliver its commands elsewhere.<p>

<tt>src\triple.bat</tt> builds <tt>rcc.exe</tt> three times.
It builds the first with
Borland C++ 4.02, and builds the other two with the
<tt>rcc.exe</tt> built just
before. For the first of these three stages, <tt>triple.bat</tt> copies the
generated executable to directory <tt>src\rcc1</tt>. The second and third
stages do likewise with directories <tt>src\rcc2</tt> and <tt>src\rcc3</tt>,
and they move the <tt>.s</tt> files there as well,
so that they can be compared.
Clear these directories once all tests pass.<p>

Each stage runs <tt>src\test.bat</tt>.
Once all tests pass, go to the directory <tt>x86\dos\tst</tt>
and run <tt>clean.bat</tt>, which cleans up.<p>

Ideally, <tt>rcc2\rcc.exe</tt> and
<tt>rcc3\rcc.exe</tt> or <tt>rcc2\*.obj</tt>
and <tt>rcc3\*.obj</tt> would be identical,
but at least some DOS assemblers and linkers emit
slightly different object and executable files when rerun on some fixed
assembler modules, so <tt>triple.bat</tt> can confirm that <tt>lcc</tt>
consistently emits the same code for itself
only by comparing <tt>rcc2\*.s</tt> with <tt>rcc3\*.s</tt>.<p>

<h2><a name="bugs">7. Reporting Bugs</a></h2>

<tt>lcc</tt> 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>.<p>

<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.<p>

<li>Preprocess the source file and capture the preprocessor output.
Discard the original code.<p>

<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.<p>

<li>Confirm that the source file displays the error with the
<em>distributed</em> version of <tt>lcc</tt>. If you've changed <tt>lcc</tt>
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.<p>

<li>Annotate your code with comments that explain why you think that
<tt>lcc</tt> is wrong. If <tt>lcc</tt> dies with an assertion failure, please tell us
where it died. If <tt>lcc</tt> crashes, please report the last part of the
call chain if you can. If <tt>lcc</tt> 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, Appendix A in
<cite>The C Programming Language</cite>, 2nd edition
by B. W. Kernighan and D. M. Ritchie (Prentice Hall, 1988),
or the appropriate section in <cite>C: A Reference Manual</cite>, 3rd edition
by S. B. Harbison and G. L. Steele, Jr. (Prentice Hall, 1991).
If <tt>lcc</tt> silently generates incorrect code for some
construct, please include the corrupt assembly code in the comments
and flag the bad instructions if you can.<p>

<li>Confirm that your error hasn't been fixed already. The latest
version of <tt>lcc</tt> is always available for anonymous <tt>ftp</tt> from
<tt>ftp.cs.princeton.edu</tt> in
<a href="ftp://ftp.cs.princeton.edu/pub/lcc"><tt>pub/lcc</tt></a>.
A <a href="ftp://ftp.cs.princeton.edu/pub/lcc/README"><tt>README</tt></a>
file there gives acquistion details,
and a <a href="ftp://ftp.cs.princeton.edu/pub/lcc/LOG"><tt>LOG</tt></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.<p>

<li>Send your program by electronic mail to
<tt>lcc-bugs@cs.princeton.edu</tt>. Please send only valid C programs;
put all remarks in C comments so that we can process reports
semiautomatically.<p>

</ol>

<h2><a name="mailinglist">8. Keeping in Touch</a></h2>

There is an <tt>lcc</tt> mailing list for general information about <tt>lcc</tt>.
To be added to the list, send a message with the 1-line body 
<pre>subscribe lcc
</pre>
to <tt>majordomo@cs.princeton.edu</tt>.
This line must appear in the message body;
``Subject:'' lines are ignored.
To learn more about mailing lists served by <tt>majordomo</tt>,
send a message with the 1-word body ``<tt>help</tt>''
to <tt>majordomo@cs.princeton.edu</tt>.

Mail sent to <tt>lcc@cs.princeton.edu</tt>
is forwarded to everyone on the mailing list.<p>
There is also an <tt>lcc-bugs</tt> mailing list for
reporting bugs; subscribe to it by sending a message with the 1-line body
<pre>subscribe lcc-bugs
</pre>
to <tt>majordomo@cs.princeton.edu</tt>. Mail addressed to
<var>lcc-bugs@cs.princeton.edu</var> is forwarded to everyone on
this list.<p>

<hr>

<address>
<a href="ftp://netlib.att.com/netlib/att/cs/home/cwfraser.html">Chris Fraser</a>
/ cwf@research.att.com</a>
</address>
<address>
<a href="/faculty/drh">David Hanson</a> / drh@cs.princeton.edu
</address>
<address>
$Revision$ $Date$
</address>
</BODY>