1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
5
<link HREF="mailto:drh@cs.princeton.edu" REV="made" TITLE="David R. Hanson">
6
<title>Installing lcc</title>
11
<h1>Installing lcc</h1>
13
<p ALIGN="LEFT"><strong><a HREF="http://www.research.microsoft.com/~cwfraser/">Christopher
14
W. Fraser</a> and <a HREF="http://www.research.microsoft.com/~drh/">David R. Hanson</a>, <a
15
HREF="http://www.research.microsoft.com/">Microsoft Research</a></strong></p>
20
<li><a HREF="#intro">Introduction</a></li>
21
<li><a HREF="#unix">Installation on UNIX</a></li>
22
<li><a HREF="#driver">Building the Driver</a></li>
23
<li><a HREF="#rcc">Building the Compiler and Accessories</a></li>
24
<li><a HREF="#win32">Installation on Windows NT 4.0 and Windows 95/98</a></li>
25
<li><a HREF="#bugs">Reporting Bugs</a></li>
26
<li><a HREF="#mailinglist">Keeping in Touch</a></li>
29
<h2><a NAME="intro">Introduction</a></h2>
31
<p><a HREF="http://www.cs.princeton.edu/software/lcc/">lcc</a> is the ANSI C compiler
32
described in our book <cite>A Retargetable C Compiler: Design and Implementation</cite>
33
(Addison-Wesley, 1995, ISBN 0-8053-1670-1).</p>
35
<p>If you're installing lcc on a UNIX system, read the remainder of this section and
36
continue with the next section. If you're installing lcc on a Windows NT 4.0 or Windows
37
95/98 system, and you intend only to <u>use</u> lcc, you can run the <a
38
href="ftp://ftp.cs.princeton.edu/pub/packages/lcc/lcc41.exe">InstallShield executable</a>,
39
which installs the binaries and the documentation. If you want to <u>modify</u> lcc or <u>rebuild</u>
40
it from the source files, you need the <a
41
href="ftp://ftp.cs.princeton.edu/packages/lcc/lcc41.zip">complete distribution</a>, and
42
you should read the rest of the section, the following three sections, and the <a
43
HREF="#win32">Windows NT/95/98</a> section.</p>
45
<p>Extract the distribution into its own directory. All non-absolute paths below are
46
relative to this directory. The distribution holds the following subdirectories.</p>
49
<table BORDER="0" CELLPADDING="1" CELLSPACING="1" WIDTH="80%">
51
<td><a HREF="../src"><code>src</code></a></td>
56
<td><a HREF="../etc"><code>etc</code></a></td>
58
<td>driver, accessories</td>
61
<td><a HREF="../lib"><code>lib</code></a></td>
63
<td>runtime library source code</td>
66
<td><a HREF="../cpp"><code>cpp</code></a></td>
68
<td>preprocessor source code</td>
71
<td><a HREF="../lburg"><code>lburg</code></a></td>
73
<td>code-generator generator source code</td>
76
<td><a HREF="../doc"><code>doc</code></a></td>
78
<td>this document, man pages</td>
81
<td><code><a HREF="../include">include</a>/*/*</code></td>
83
<td>include files</td>
86
<td><a HREF="../tst"><code>tst</code></a></td>
91
<td><code><a HREF="../alpha">alpha</a>/*/tst</code></td>
93
<td>ALPHA test outputs</td>
96
<td><code><a HREF="../mips">mips</a>/*/tst</code></td>
98
<td>MIPS test outputs</td>
101
<td><code><a HREF="../sparc">sparc</a>/*/tst</code></td>
103
<td>SPARC test outputs</td>
106
<td><code><a HREF="../x86">x86</a>/*/tst</code></td>
108
<td>X86 test outputs</td>
113
<p><code>doc/install.html</code> is the HTML file for this document. <a HREF="4.html"><code>doc/4.html</code></a>
114
describes the internal differences between lcc 3.x and 4.1.</p>
116
<p>The installation makefile is designed so that lcc can be installed from a read-only
117
file system or directory, which is common in networked environments, so the distribution
118
can be unloaded on a central file server. <strong>You will need an existing ANSI/ISO C
119
compiler to build and install lcc.</strong></p>
121
<h2><a NAME="unix">Installation on UNIX</a></h2>
123
<p>The compilation components (the preprocessor, include files, and compiler proper, etc.)
124
are installed in a single <em>build directory</em>. On multi-platform systems supported by
125
a central file server, it's common to store the build directory in a location specific to
126
the platform and to the version of lcc, and to point a symbolic link to this location. For
130
<pre>% ln -s /usr/local/lib/lcc-4.1/sparc-solaris /usr/local/lib/lcc</pre>
133
<p>points <code>/usr/local/lib/lcc</code> to a build directory for lcc version 4.1 on the
134
SPARC under Solaris. Links into <code>/usr/local/lib</code> are created for the programs <code>lcc</code>
135
and <code>bprint</code>. Thus, a new distribution can be installed by building it in its
136
own build directory and changing one symbolic link to point to that directory. If these
137
conventions or their equivalents are followed, the host-specific parts of the driver
138
program, <code>lcc</code>, can be used unmodified.</p>
140
<p>Installation on a UNIX system involves the following steps. Below, the build directory
141
is referred to as <code>BUILDDIR</code>.
144
<li>Create the build directory, using a version- and platform-specific naming convention as
145
suggested above, and record the name of this directory in the <code>BUILDDIR</code>
146
environment variable:<blockquote>
147
<pre>% setenv BUILDDIR /usr/local/lib/lcc-4.1/sparc-solaris
148
% mkdir -p $BUILDDIR</pre>
150
<p>Here and below, commands assume the C shell. Also, you'll need a version of <code>mkdir</code>
151
that supports the <code>-p</code> option, which creates intermediate directories as
154
<li>Copy the man pages to the repository for local man pages, e.g.,<blockquote>
155
<pre>% cp doc/*.1 /usr/local/man/man1</pre>
157
<p>Some users copy the man pages to the build directory and create the appropriate
158
symbolic links, e.g., </p>
160
<pre>% cp doc/*.1 $BUILDDIR
161
% ln -s $BUILDDIR/*.1 /usr/local/man/man1</pre>
164
<li>Platform-specific include files are in directories named <code>include/</code><em>target</em><code>/</code><em>os</em>.
165
Create the include directory in the build directory, and copy the include hierarchy for
166
your platform to this directory, e.g.,<blockquote>
167
<pre>% mkdir $BUILDDIR/include
168
% cp -p -R include/sparc/solaris/* $BUILDDIR/include</pre>
170
<p>Again, some users create a symbolic link to the appropriate directory in the
171
distribution instead of copying the include files. For example, at Princeton, the
172
distributions are stored under <code>/proj/pkg/lcc</code>, so the included files are
173
"installed" by creating one symbolic link: </p>
175
<pre>% ln -s /proj/pkg/lcc/4.1/include/sparc/solaris $BUILDDIR/include</pre>
177
<p>If you're installing lcc on Linux, you <em>must</em> also plant a symbolic link named <code>gcc</code>
178
to gcc's library directory, because lcc uses gcc's C preprocessor and most of gcc's header
181
<pre>% ln -s /usr/lib/gcc-lib/i486-linux/2.7.2.2 $BUILDDIR/gcc</pre>
183
<p>The library directory shown above may be different on your Linux machine; to determine
184
the correct directory, browse <code>/usr/lib/gcc-lib</code>, or execute</p>
186
<pre>% cc -v tst/8q.c</pre>
188
<p>and examine the diagnostic output. Make sure that <code>$BUILDDIR/gcc/cpp</code> and <code>$BUILDDIR/gcc/include</code>
189
point to, respectively, gcc's C preprocessor and header files. On Linux, lcc looks for
190
include files in <code>$BUILDDIR/include</code>, <code>$BUILDDIR/gcc/include</code>, and <code>/usr/include</code>,
191
in that order; see <a HREF="#driver"><em>Building the Driver</em></a> and <a
192
href="../etc/linux.c"><code>etc/linux.c</code></a> for details.</p>
194
<li>The <a HREF="../makefile"><code>makefile</code></a> includes the file named by the <code>CUSTOM</code>
195
macro; the default is <code>custom.mk</code>, and an empty <code>custom.mk</code> is
196
included in the distribution. If desired, prepare a site-specification customization file
197
and define <code>CUSTOM</code> to the path of that file when invoking make in steps 5 and
199
<pre>make CUSTOM=/users/drh/solaris.mk</pre>
201
<p>You can, for example, use customization files to record site-specific values for macros
202
instead of using environment variables, and to record targets for the steps in this list.</p>
204
<li>Build the host-specific driver, creating a custom host-specific part, if necessary. See <a
205
HREF="#driver"><em>Building the Driver</em></a>.</li>
206
<li>Build the preprocessor, compiler proper, library, and other accessories. See <a
207
HREF="#rcc"><em>Building the Compiler</em></a>.</li>
208
<li>Plant symbolic links to the build directory and to the installed programs, e.g.,<blockquote>
209
<pre>% ln -s $BUILDDIR /usr/local/lib/lcc
210
% ln -s /usr/local/lib/{lcc,bprint} /usr/local/bin</pre>
212
<p>Some users copy <code>bprint</code> and <code>lcc</code> into <code>/usr/local/bin</code>
213
instead of creating symbolic links. The advantange of creating the links for <code>lcc</code>
214
and <code>bprint</code> as shown is that, once established, they point indirectly to
215
whatever <code>/usr/local/lib/lcc</code> points to; installing a new version of lcc, say,
216
4.2, can be done by changing <code>/usr/local/lib/lcc</code> to point to the 4.2 build
221
<h2><a NAME="driver">Building the Driver</a></h2>
223
<p>The preprocessor, compiler, assembler, and loader are invoked by a driver program, <code>lcc</code>,
224
which is similar to <code>cc</code> on most systems. It's described in the man page <code>doc/lcc.1</code>.
225
The driver is built by combining the host-independent part, <a href="../etc/lcc.c"><code>etc/lcc.c</code></a>,
226
with a small host-specific part. Distributed host-specific parts are named <code>etc/</code><em>os</em><code>.c</code>,
227
where <em>os</em> is the name of the operating system for the host on which <code>lcc</code>
228
is being installed. If you're following the installations conventions described above, you
229
can probably use one of the host-specific parts unmodified; otherwise, pick one that is
230
closely related to your platform, copy it to <em>whatever</em><code>.c</code>, and edit it
231
as described below. You should not have to edit <code>etc/lcc.c</code>.</p>
233
<p>We'll use <a HREF="../etc/solaris.c"><code>etc/solaris.c</code></a> as an example in
234
describing how the host-specific part works. This example illustrates all the important
235
features. Make sure you have the environment variable <code>BUILDDIR</code> set correctly,
236
and build the driver with a <code>make</code> command, e.g.,</p>
239
<pre>% make HOSTFILE=etc/solaris.c lcc
240
cc -g -c -DTEMPDIR=\"/tmp\" -o /usr/local/lib/lcc-4.1/sparc-solaris/lcc.o etc/lcc.c
241
cc -g -c -o /usr/local/lib/lcc-4.1/sparc-solaris/host.o etc/solaris.c
242
cc -g -o /usr/local/lib/lcc-4.1/sparc-solaris/lcc /usr/local/lib/lcc-4.1/sparc-solaris/lcc.o /usr/local/lib/lcc-4.1/sparc-solaris/host.o</pre>
245
<p>The symbolic name <code>HOSTFILE</code> specifies the path to the host-specific part,
246
either one in the distribution or <em>whatever</em><code>.c</code>. Some versions of make
247
may require the <code>-e</code> option in order to read the environment.</p>
249
<p>Here's <code>etc/solaris.c</code>:</p>
252
<pre>/* Sparcs running Solaris 2.5.1 at CS Dept., Princeton University */
254
#include <string.h>
256
static char rcsid[] = "$ Id: solaris.c,v 1.10 1998/09/14 20:36:33 drh Exp $";
259
#define LCCDIR "/usr/local/lib/lcc/"
262
#define SUNDIR "/opt/SUNWspro/SC4.2/lib/"
265
char *suffixes[] = { ".c", ".i", ".s", ".o", ".out", 0 };
266
char inputs[256] = "";
267
char *cpp[] = { LCCDIR "cpp",
268
"-D__STDC__=1", "-Dsparc", "-D__sparc__", "-Dsun", "-D__sun__", "-Dunix",
269
"$1", "$2", "$3", 0 };
270
char *include[] = { "-I" LCCDIR "include", "-I/usr/local/include",
271
"-I/usr/include", 0 };
272
char *com[] = { LCCDIR "rcc", "-target=sparc/solaris",
273
"$1", "$2", "$3", 0 };
274
char *as[] = { "/usr/ccs/bin/as", "-Qy", "-s", "-o", "$3", "$1", "$2", 0 };
275
char *ld[] = { "/usr/ccs/bin/ld", "-o", "$3", "$1",
276
SUNDIR "crti.o", SUNDIR "crt1.o",
277
SUNDIR "values-xa.o", "$2", "",
278
"-Y", "P," SUNDIR ":/usr/ccs/lib:/usr/lib", "-Qy",
279
"-L" LCCDIR, "-llcc", "-lm", "-lc", SUNDIR "crtn.o", 0 };
281
extern char *concat(char *, char *);
283
int option(char *arg) {
284
if (strncmp(arg, "-lccdir=", 8) == 0) {
285
cpp[0] = concat(&arg[8], "/cpp");
286
include[0] = concat("-I", concat(&arg[8], "/include"));
287
ld[12] = concat("-L", &arg[8]);
288
com[0] = concat(&arg[8], "/rcc");
289
} else if (strcmp(arg, "-p") == 0) {
290
ld[5] = SUNDIR "mcrt1.o";
291
ld[10] = "P," SUNDIR "libp:/usr/ccs/lib/libp:/usr/lib/libp:"
292
SUNDIR ":/usr/ccs/lib:/usr/lib";
293
} else if (strcmp(arg, "-b") == 0)
295
else if (strncmp(arg, "-ld=", 4) == 0)
303
<p><code>LCCDIR</code> defaults to <code>"/usr/local/lib/lcc/"</code> unless
304
it's defined by a <code>-D</code> option as part of <code>CFLAGS</code> in the make
308
<pre>% make HOSTFILE=etc/solaris.c CFLAGS='-DLCCDIR=\"/v/lib/lcc/\"' lcc</pre>
311
<p>Note the trailing slash; <code>SUNDIR</code> is provided so you can use <code>etc/solaris.c</code>
312
even if you have a different version of the Sun Pro compiler suite. If you're using the
313
gcc compiler tools instead of the Sun Pro tools, see <a HREF="../etc/gcc-solaris.c"><code>etc/gcc-solaris.c</code></a>.</p>
315
<p>Most of the host-specific code is platform-specific data and templates for the commands
316
that invoke the preprocessor, compiler, assembler, and loader. The <code>suffixes</code>
317
array lists the file name suffixes for C source files, preprocessed source files, assembly
318
language source files, object files, and executable files. <code>suffixes</code> must be
319
terminated with a null pointer, as shown above. The initialization of <code>suffixes</code>
320
in <code><a HREF="../etc/solaris.c">etc/solaris.c</a></code> are the typical ones for UNIX
321
systems. Each element of <code>suffixes</code> is actually a list of suffixes, separated
322
by semicolons; <code><a HREF="../etc/win32.c">etc/win32.c</a></code> holds an example:</p>
325
<pre>char *suffixes[] = { ".c;.C", ".i;.I", ".asm;.ASM;.s;.S", ".obj;.OBJ", ".exe", 0 };</pre>
328
<p>When a list is given, the first suffix is used whenever lcc needs to generate a file
329
name. For example, with <code><a HREF="../etc/win32.c">etc/win32.c</a></code>, lcc emits
330
the generated assembly code into <code>.asm</code> files.</p>
332
<p>The <code>inputs</code> array holds a null-terminated string of directories separated
333
by colons or semicolons. These are used as the default value of <code>LCCINPUTS</code>, if
334
the environment variable <code>LCCINPUTS</code> is not set; see the <a HREF="lcc.pdf">man
337
<p>Each command template is an array of pointers to strings terminated with a null
338
pointer; the strings are full path names of commands, arguments, or argument placeholders,
339
which are described below. Commands are executed in a child process, and templates can
340
contain multiple commands by separating commands with newlines. The driver runs each
341
command in a new process.</p>
343
<p>The <code>cpp</code> array gives the command for running lcc's preprocessor, <code>cpp</code>.
344
Literal arguments specified in templates, e.g., <code>"-Dsparc"</code> in the <code>cpp</code>
345
command above, are passed to the command as given.</p>
347
<p>The strings <code>"$1"</code>, <code>"$2"</code>, and <code>"$3"</code>
348
in templates are placeholders for <em>lists</em> of arguments that are substituted in a
349
copy of the template before the command is executed. <code>$1</code> is replaced by the <em>options</em>
350
specified by the user; for the preprocessor, this list always contains at least <code>-D__LCC__</code>.
351
<code>$2</code> is replaced by the <em>input</em> files, and <code>$3</code> is replaced
352
by the <em>output</em> file.</p>
354
<p>Zero-length arguments after replacement are removed from the argument list before the
355
command is invoked. So, for example, if the preprocessor is invoked without an output
356
file, <code>"$3"</code> becomes <code>""</code>, which is removed from
357
the final argument list.</p>
359
<p>The <code>include</code> array is a list of <code>-I</code> options that specify which
360
directives should be searched to satisfy include directives. These directories are
361
searched in the order given. The first directory should be the one to which the ANSI
362
header files were copied as described in <a HREF="#unix">UNIX</a> or <a HREF="#win32">Windows</a>
363
installation instructions. The driver adds these options to <code>cpp</code>'s arguments
364
when it invokes the preprocessor, except when <code>-N</code> is specified.</p>
366
<p><code>com</code> gives the command for invoking the compiler. This template can appear
367
as shown above in a custom host-specific part, but the option <code>-target=sparc/solaris</code>
368
should be edited to the <em>target</em><code>/</code><em>os</em> for your platform. If <code>com[1]</code>
369
includes the string "<code>win32</code>", the driver assumes it's running on
370
Windows. lcc can generate code for <em>all</em> of the <em>target</em><code>/</code><em>os</em>
371
combinations listed in the file <code>src/bind.c</code>. The <code>-target</code> option
372
specifies the default combination. The driver's <code>-Wf</code> option can be used to
373
specify other combinations; the <a HREF="lcc.pdf">man page</a> elaborates.</p>
375
<p><code>as</code> gives the command for invoking the assembler. On Linux, you must be
376
running at least version 2.8.1 of the GNU assembler; earlier versions mis-assemble some
377
instructions emitted by lcc.</p>
379
<p><code>ld</code> gives the command for invoking the loader. For the other commands, the
380
list <code>$2</code> contains a single file; for <code>ld</code>, <code>$2</code> contains
381
all ".o" files and libraries, and <code>$3</code> is <code>a.out</code>, unless
382
the <code>-o</code> option is specified. As suggested in the code above, <code>ld</code>
383
must also specify the appropriate startup code and default libraries, including the lcc
384
library, <code>liblcc.a</code>.</p>
386
<p>The <code>option</code> function is described below; the minimal <code>option</code>
387
function just returns 0.</p>
389
<p>You can test <code>lcc</code> with the options <code>-v -v</code> to display the
390
commands that would be executed, e.g.,</p>
393
<pre>% $BUILDDIR/lcc -v -v foo.c baz.c mylib.a -lX11
394
/usr/local/lib/lcc-4.1/lcc $ Id: solaris.c,v 1.10 1998/09/14 20:36:33 drh Exp $
396
/usr/local/lib/lcc/cpp -D__STDC__=1 -Dsparc -D__sparc__ -Dsun -D__sun__ -Dunix -D__LCC__ -I/usr/local/lib/lcc/include -I/usr/local/include -I/usr/include foo.c /tmp/lcc266290.i
397
/usr/local/lib/lcc/rcc -target=sparc/solaris -v /tmp/lcc266290.i /tmp/lcc266291.
399
/usr/ccs/bin/as -Qy -s -o /tmp/lcc266292.o /tmp/lcc266291.s
401
/usr/local/lib/lcc/cpp -D__STDC__=1 -Dsparc -D__sparc__ -Dsun -D__sun__ -Dunix -D__LCC__ -I/usr/local/lib/lcc/include -I/usr/local/include -I/usr/include baz.c /tmp/lcc266290.i
402
/usr/local/lib/lcc/rcc -target=sparc/solaris -v /tmp/lcc266290.i /tmp/lcc266291.s
403
/usr/ccs/bin/as -Qy -s -o /tmp/lcc266293.o /tmp/lcc266291.s
404
/usr/ccs/bin/ld -o a.out /opt/SUNWspro/SC4.2/lib/crti.o /opt/SUNWspro/SC4.2/lib/crt1.o /opt/SUNWspro/SC4.2/lib/values-xa.o /tmp/lcc266292.o /tmp/lcc266293.o mylib.a -lX11 -Y P,/opt/SUNWspro/SC4.2/lib/:/usr/ccs/lib:/usr/lib -Qy -L/usr/local/lib/lcc/ -llcc -lm -lc /opt/SUNWspro/SC4.2/lib/crtn.o
405
rm /tmp/lcc266293.o /tmp/lcc266290.i /tmp/lcc266291.s /tmp/lcc266292.o</pre>
408
<p>As the output shows, <code>lcc</code> places temporary files in <code>/tmp</code>; if
409
any of the environment variables <code>TMP</code>, <code>TEMP</code>, and <code>TMPDIR</code>
410
are set, they override this default (in the order shown) as does the <code>-tempdir=</code><em>dir</em>
411
option. The default can be changed by defining <code>TEMPDIR</code> in <code>CFLAGS</code>
412
when building the driver.</p>
414
<p>The <code>option</code> function is called for the options <code>-Wo</code>, <code>-g</code>,
415
<code>-p</code>, <code>-pg</code>, and <code>-b</code> because these compiler options
416
might also affect the loader's arguments. For these options, the driver calls <code>option(arg)</code>
417
to give the host-specific code an opportunity to edit the <code>ld</code> command, if
418
necessary. <code>option</code> can change <code>ld</code>, if necessary, and return 1 to
419
announce its acceptance of the option. If the option is unsupported, <code>option</code>
422
<p>For example, in response to <code>-g</code>, the <code>option</code> function shown
423
above accepts the option but does nothing else, because the <code>ld</code> and <code>as</code>
424
commands don't need to be modified on the SPARC. <code>-g</code> will also be added to the
425
compiler's options by the host-independent part of the driver. The <code>-p</code> causes <code>option</code>
426
to change the name of the startup code and changed the list of libraries. The <code>-b</code>
427
option turns on <code>lcc</code>'s per-expression profiling, the code for which is in <code>liblcc.a</code>,
428
so <code>option</code> need no nothing.</p>
430
<p>On SPARCs, the driver also recognizes <code>-Bstatic</code> and <code>-Bdynamic</code>
431
as linker options. The driver recognizes but ignores "<code>-target</code> <em>name</em>"
434
<p>The option <code>-Wo</code><em>arg</em> causes the driver to pass <em>arg</em> to <code>option</code>.
435
Such options have no other effect; this mechanism is provided to support system-specific
436
options that affect the commands executed by the driver. As illustrated above,
437
host-specific parts should support the <code>-Wo-lccdir=</code><em>dir</em> option, which
438
causes lcc's compilation components to be found in <em>dir</em>, because this option is
439
used by the test scripts, and because the driver simulates a <code>-Wo-lccdir</code>
440
option with the value of the environment variable <code>LCCDIR</code>, if it's defined.
441
The code above rebuilds the paths to the include files, preprocessor, compiler, and
442
library by calling <code>concat</code>, which is defined in <code>etc/lcc.c</code>.</p>
444
<h2><a NAME="rcc">Building the Compiler and Accessories</a></h2>
446
<p>To build the rest of compilation components make sure <code>BUILDDIR</code> is set
447
appropriately and type "<code>make all</code>". This command builds <code>librcc.a</code>
448
(the compiler's private library), <code>rcc</code> (the compiler proper), <code>lburg</code>
449
(the code-generator generator), <code>cpp</code> (the preprocessor), <code>liblcc.a</code>
450
(the runtime library), and <code>bprint</code> (the profile printer), all in <code>BUILDDIR</code>.
451
There may be warnings, but there should be no errors. If you're using an ANSI/ISO compiler
452
other than <code>cc</code>, specify its name with the <code>CC=</code> option, e.g.,
453
"<code>make CC=gcc all</code>". If you're running on a DEC ALPHA, use "<code>make
454
CC='cc -std1' all</code>"; the <code>-std1</code> option is essential on the ALPHA.
455
If you're on a DEC 5000 running Ultrix 4.3, use "<code>make CC=c89 all</code>".</p>
457
<p>Once <code>rcc</code> is built with the host C compiler, run the test suite to verify
458
that <code>rcc</code> is working correctly. If any of the steps below fail, contact us
459
(see <a HREF="#bugs"><em>Reporting Bugs</em></a>). The commands in the makefile run the
460
shell script <code>src/run.sh</code> on each C program in the test suite, <code>tst/*.c</code>.
461
It uses the driver, <code>$BUILDDIR/lcc</code>, so you must have the driver in the build
462
directory before testing <code>rcc</code>. The <em>target</em><code>/</code><em>os</em>
463
combination is read from the variable <code>TARGET</code>, which must be specified when
464
invoking <code>make</code>:</p>
467
<pre>% make TARGET=sparc/solaris test
468
mkdir -p /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst
469
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/8q.s:
470
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/array.s:
471
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/cf.s:
472
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/cq.s:
473
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/cvt.s:
474
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/fields.s:
475
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/front.s:
476
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/incr.s:
477
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/init.s:
478
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/limits.s:
479
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/paranoia.s:
480
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/sort.s:
481
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/spill.s:
482
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/stdarg.s:
483
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/struct.s:
484
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/switch.s:
485
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/wf1.s:
486
/usr/local/lib/lcc-4.1/sparc-solaris/rcc -target=sparc/solaris /usr/local/lib/lcc-4.1/sparc-solaris/sparc/solaris/tst/yacc.s:</pre>
489
<p>Each line in the output above is of the form</p>
492
<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>
495
<p>where <em>X</em> is the base name of the C program <em>X</em><code>.c</code> in the
496
test suite. This output identifies the compiler and the target, e.g., "<code>$BUILDDIR/rcc</code>
497
is generating code for a <code>sparc</code> running the <code>solaris</code> operating
500
<p>For each program in the test suite, <code>src/run.sh</code> compiles the program, drops
501
the generated assembly language code in <code>BUILDDIR</code>/<em>target</em><code>/</code><em>os</em>,
502
and uses <code>diff</code> to compare the generated assembly code with the expected code
503
(the code expected for <code>tst/8q.c</code> on the SPARC under Solaris is in <code>sparc/solaris/tst/8q.sbk</code>,
504
etc.). If there are differences, the script executes the generated code with the input
505
given in <code>tst</code> (the input for <code>tst/8q.c</code> is in <code>tst/8q.0</code>,
506
etc.) and compares the output with the expected output (the expected output from <code>tst/8q.c</code>
507
on the SPARC under Solaris is in <code>sparc/solaris/tst/8q.1bk</code>, etc.). The script
508
also compares the diagnostics from the compiler with the expected diagnostics.</p>
510
<p>On some systems, there may be a few differences between the generated code and the
511
expected code. These differences occur because the expected code is generated by cross
512
compilation and the least significant bits of some floating-point constants differ from
513
those bits in constants generated on your system. On Linux, there may be differences
514
because of differences in the header files between our system and yours. There should be
515
no differences in the output from executing the test programs.</p>
517
<p>Next, run the "triple test", which builds <code>rcc</code> using itself:</p>
521
/usr/local/lib/lcc-4.1/sparc-solaris/lcc -o /usr/local/lib/lcc-4.1/sparc-solaris/1rcc -d0.6 -Wo-lccdir=/usr/local/lib/lcc-4.1/sparc-solaris -B/usr/local/lib/lcc-4.1/sparc-solaris/ -Isrc src/*.c
525
/usr/local/lib/lcc-4.1/sparc-solaris/lcc -o /usr/local/lib/lcc-4.1/sparc-solaris/1rcc -d0.6 -Wo-lccdir=/usr/local/lib/lcc-4.1/sparc-solaris -B/usr/local/lib/lcc-4.1/sparc-solaris/ -Isrc src/*.c
529
strip /usr/local/lib/lcc-4.1/sparc-solaris/[12]rcc
530
dd if=/usr/local/lib/lcc-4.1/sparc-solaris/1rcc of=/usr/local/lib/lcc-4.1/sparc-solaris/rcc1 bs=512 skip=1
533
dd if=/usr/local/lib/lcc-4.1/sparc-solaris/2rcc of=/usr/local/lib/lcc-4.1/sparc-solaris/rcc2 bs=512 skip=1
536
if cmp /usr/local/lib/lcc-4.1/sparc-solaris/rcc[12]; then \
537
mv /usr/local/lib/lcc-4.1/sparc-solaris/2rcc /usr/local/lib/lcc-4.1/sparc-solaris/rcc; \
538
rm -f /usr/local/lib/lcc-4.1/sparc-solaris/1rcc /usr/local/lib/lcc-4.1/sparc-solaris/rcc[12]; fi</pre>
541
<p>This command builds <code>rcc</code> twice; once using the <code>rcc</code> built by <code>cc</code>
542
and again using the <code>rcc</code> built by <code>lcc</code>. The resulting binaries are
543
compared. They should be identical, as shown at the end of the output above. If they
544
aren't, our compiler is generating incorrect code; <a HREF="#bugs">contact</a> us.</p>
546
<p>The final version of <code>rcc</code> should also pass the test suite; that is, the
550
<pre>% make TARGET=sparc/solaris test</pre>
553
<p>should be identical to that from the previous <code>make test</code>.</p>
555
<p>The command "<code>make clean</code>" cleans up, but does not remove <code>rcc</code>,
556
etc., and "<code>make clobber</code>" cleans up and removes <code>lcc</code>, <code>rcc</code>,
557
and the other accessories. Test directories under <code>BUILDDIR</code> are <em>not</em>
558
removed; you'll need to remove these by hand, e.g.,</p>
561
<pre>% rm -fr $BUILDDIR/sparc</pre>
564
<p>The code generators for the other targets can be tested by specifying the desired <em>target</em><code>/</code><em>os</em>
565
and setting an environment variable that controls what <code>src/run.sh</code> does. For
566
example, to test the MIPS code generator, type</p>
569
<pre>% setenv REMOTEHOST noexecute
570
% make TARGET=mips/irix test</pre>
573
<p>As above, <code>src/run.sh</code> compares the MIPS code generated with what's
574
expected. There should be no differences. Setting <code>REMOTEHOST</code> to <code>noexecute</code>
575
suppresses the assembly and execution of the generated code. If you set <code>REMOTEHOST</code>
576
to the name of a MIPS machine to which you can <code>rlogin</code>, <code>src/run.sh</code>
577
will <code>rcp</code> the generated code to that machine and execute it there, if
578
necessary. See <code>src/run.sh</code> for the details.</p>
580
<p>You can use lcc as a cross compiler. The options <code>-S</code> and <code>-Wf-target=</code><em>target/os</em>
581
generate assembly code for the specified target, which is any of those listed in the file <code>src/bind.c</code>.
585
<pre>% lcc -Wf-target=mips/irix -S tst/8q.c</pre>
588
<p>generates MIPS code for <code>tst/8q.c</code> in <code>8q.s</code>.</p>
590
<p>lcc can also generate code for a "symbolic" target. This target is used
591
routinely in front-end development, and its output is a printable representation of the
592
input program, e.g., the dags constructed by the front end are printed, and other
593
interface functions print their arguments. You can specify this target with the option <code>-Wf-target=symbolic</code>.
597
<pre>% lcc -Wf-target=symbolic -S tst/8q.c</pre>
600
<p>generates symbolic output for <code>tst/8q.c</code> in <code>8q.s</code>. Adding <code>-Wf-html</code>
601
causes the symbolic target to emit HTML instead of plain text. Finally, the option <code>-Wf-target=null</code>
602
specifies the "null" target for which lcc emits nothing and thus only checks the
603
syntax and semantics of its input files.</p>
605
<h2><a NAME="win32">Installation on Windows NT 4.0 or Windows 95/98</a></h2>
607
<p>On Windows NT 4.0 and Windows 95/98, lcc is designed to work with Microsoft's Visual
608
C++ 5.0 (VC) and Microsoft's Assembler, MASM 6.11d. It uses the VC header files,
609
libraries, and command-line tools, and it uses MASM to assemble the code it generates. If
610
you have MASM 6.11, make sure you <a
611
HREF="http://support.microsoft.com/support/kb/articles/Q138/9/83.asp">upgrade to 6.11d</a>,
612
because earlier 6.11 releases do not generate correct COFF object files.</p>
614
<p>Building the distribution components from the ground up requires Microsoft's Visual
615
C/C++ 5.0 compiler, Microsoft's make, <code>nmake</code>, and the standard Windows command
616
interpreter. <a HREF="../makefile.nt"><code>makefile.nt</code></a> is written to use only <code>nmake</code>.
617
As on UNIX systems, the compilation components are installed in a single <em>build
618
directory</em>, and the top-level programs, <code>lcc.exe</code> and <code>bprint.exe</code>,
619
are installed in a directory on the PATH. If the conventions used below are followed, the
620
Windows-specific parts of the driver program, <code>lcc.exe</code>, can be used
623
<p>Building from the source distribution on a Windows system involves the following steps.
624
Below, the build directory is referred to as <code>BUILDDIR</code>, and the distribution
625
is in <code>\dist\lcc\4.1</code>.
628
<li>Create the build directory, perhaps using a version- and platform-specific naming
629
convention as suggested in <a HREF="#unix"><em>Installation on UNIX</em></a>, and record
630
the name of this directory in the <code>BUILDDIR</code> environment variable:<blockquote>
631
<pre>C:\dist\lcc\4.1>set BUILDDIR=\progra~1\lcc\4.1\bin
632
C:\dist\lcc\4.1>mkdir %BUILDDIR%</pre>
634
<p>The default build, or installation, directory is <code>\Program Files\lcc\4.1\bin</code>,
635
but the <code>nmake</code> commands require that you use the corresponding 8.3 file name, <code>progra~1</code>,
636
instead of <code>Program Files</code>.</p>
638
<li><a HREF="../etc/win32.c"><code>etc\win32.c</code></a> is the Windows-specific part of
639
the driver. It assumes that environment variable <code>include</code> gives the locations
640
of the VC header files and that the linker (<code>link.exe</code>) and the assembler (<code>ml.exe</code>)
641
are on the PATH. It also assumes that the macro <code>LCCDIR</code> gives the build
642
directory. If necessary, revise a copy of <a HREF="../etc/win32.c"><code>etc\win32.c</code></a>
643
to reflect the conventions on your computer (see <a HREF="#driver"><em>Building the Driver</em></a>),
644
then build the driver, specifying the default temporary directory, if necessary:<blockquote>
645
<pre>C:\dist\lcc\4.1>nmake -f makefile.nt TEMPDIR=\\temp HOSTFILE=etc/win32.c lcc
647
cl -nologo -Zi -MLd -Fd\progra~1\lcc\4.1\bin\ -c -DTEMPDIR=\"\\temp\" -Fo\progra~1\lcc\4.1\bin\lcc.obj etc/lcc.c
649
cl -nologo -Zi -MLd -Fd\progra~1\lcc\4.1\bin\ -c -Fo\progra~1\lcc\4.1\bin\host.obj etc/win32.c
651
cl -nologo -Zi -MLd -Fd\progra~1\lcc\4.1\bin\ -Fe\progra~1\lcc\4.1\bin\lcc.exe \progra~1\lcc\4.1\bin\lcc.obj \progra~1\lcc\4.1\bin\host.obj</pre>
653
<p>If you make a copy of <code>etc\win32.c</code>, specify the path of the copy as the
654
value of <code>HOSTFILE</code>. For example, if you copy <code>etc\win32.c</code> to <code>BUILDDIR</code>
655
and edit it, use the command</p>
657
<pre>C:\dist\lcc\4.1>nmake -f makefile.nt TEMPDIR=\\temp HOSTFILE=%BUILDDIR%\win32.c lcc</pre>
660
<li>Build the preprocessor, compiler proper, library, and other accessories (see <a
661
HREF="#rcc"><em>Building the Compiler</em></a>):<blockquote>
662
<pre>C:\dist\lcc\4.1>nmake -f makefile.nt all</pre>
664
<p>This command uses the VC command-line tools <code>cl</code> and <code>lib</code> to
665
build <code>bprint.exe</code>, <code>cpp.exe</code>, <code>lburg.exe</code>, <code>liblcc.lib</code>,
666
<code>librcc.lib</code>, and <code>rcc.exe</code>, all in <code>BUILDDIR</code>. There may
667
be some warnings, but there should be no warnings.</p>
669
<li>Create a test directory and run the test suite:<blockquote>
670
<pre>C:\dist\lcc\4.1>mkdir %BUILDDIR%\x86\win32\tst
671
C:\dist\lcc\4.1>nmake -f makefile.nt test</pre>
673
<p>This command compiles each program in <a HREF="../tst">tst</a>, compares the generated
674
assembly code and diagnostics with the expected assembly code and diagnostics, executes
675
the program, and compares the output with the expected output (using <code>fc</code>). For
676
example, when the nmake command compiles <a HREF="../tst/8q.c"><code>tst\8q.c</code></a>,
677
it leaves the generated assembly code and diagnostic output in <code>%BUILDDIR%\x86\win32\tst\8q.s</code>
678
and <code>%BUILDDIR%\x86\win32\tst\8q.2</code>, and it compares them with the expected
679
results in <code>x86\win32\tst\8q.sbk</code>. It builds the executable program in <code>%BUILDDIR%\x86\win32\tst\8q.exe</code>,
680
runs it, and redirects the output to <code>%BUILDDIR%\x86\win32\tst\8q.1</code>, which it
681
compares with <code>x86\win32\tst\8q.1bk</code>. The output from this step is voluminous,
682
but there should be no differences and no errors.</p>
684
<li>Run the "triple" test, which compiles <code>rcc</code> with itself and
685
verifies the results:<blockquote>
686
<pre>C:\dist\lcc\4.1>nmake -f makefile.nt triple
688
\progra~1\lcc\4.1\bin\x86.c:
689
Assembling: C:/TEMP/lcc2001.asm
690
fc /b \progra~1\lcc\4.1\bin\1rcc.exe \progra~1\lcc\4.1\bin\2rcc.exe
691
Comparing files \progra~1\lcc\4.1\bin\1rcc.exe and \progra~1\lcc\4.1\bin\2RCC.EXE
692
00000088: B4 D5</pre>
694
<p>This command builds <code>rcc</code> twice; once using the <code>rcc</code> built by VC
695
and again using the <code>rcc</code> built by <code>lcc</code>. The resulting binaries are
696
compared using <code>fc</code>. They should be identical, except for one or two bytes of
697
timestamp data, as shown at the end of the output above. If they aren't, our compiler is
698
generating incorrect code; <a HREF="#bugs">contact</a> us.</p>
700
<li>Copy <code>lcc.exe</code> and <code>bprint.exe</code> to a directory on your PATH, e.g.,<blockquote>
701
<pre>C:\dist\lcc\4.1>copy %BUILDDIR%\lcc.exe \bin
704
C:\dist\lcc\4.1>copy %BUILDDIR%\bprint.exe \bin
705
1 file(s) copied.</pre>
708
<li>Finally, clean up:<blockquote>
709
<pre>C:\dist\lcc\4.1>nmake -f makefile.nt clean</pre>
711
<p>This command removes the derived files in <code>BUILDDIR</code>, but does not remove <code>rcc.exe</code>,
712
etc.; "<code>nmake -f makefile.nt clobber</code>" cleans up and removes all
713
executables and libraries. Test directories under <code>BUILDDIR</code> are <em>not</em>
714
removed; you'll need to remove these by hand, e.g.,</p>
716
<pre>C:\dist\lcc\4.1>rmdir %BUILDDIR%\x86 /s
717
\progra~1\lcc\4.1\bin\x86, Are you sure (Y/N)? y</pre>
722
<h2><a NAME="bugs">Reporting Bugs</a></h2>
724
<p>lcc is a large, complex program. We find and repair errors routinely. If you think that
725
you've found a error, follow the steps below, which are adapted from the instructions in
726
Chapter 1 of <cite>A Retargetable C Compiler: Design and Implementation</cite>.
729
<li>If you don't have a source file that displays the error, create one. Most errors are
730
exposed when programmers try to compile a program they think is valid, so you probably
731
have a demonstration program already.</li>
732
<li>Preprocess the source file and capture the preprocessor output. Discard the original
734
<li>Prune your source code until it can be pruned no more without sending the error into
735
hiding. We prune most error demonstrations to fewer than five lines.</li>
736
<li>Confirm that the source file displays the error with the <em>distributed</em> version of
737
lcc. If you've changed lcc and the error appears only in your version, then you'll have to
738
chase the error yourself, even if it turns out to be our fault, because we can't work on
740
<li>Annotate your code with comments that explain why you think that lcc is wrong. If lcc
741
dies with an assertion failure, please tell us where it died. If lcc crashes, please
742
report the last part of the call chain if you can. If lcc is rejecting a program you think
743
is valid, please tell us why you think it's valid, and include supporting page numbers in
744
the ANSI Standard, Appendix A in <cite>The C Programming Language</cite>, or the
745
appropriate section in <cite>C: A Reference Manual</cite>, 4th edition by S. B. Harbison
746
and G. L. Steele, Jr. (Prentice Hall, 1995). If lcc silently generates incorrect code for
747
some construct, please include the corrupt assembly code in the comments and flag the
748
incorrect instructions if you can.</li>
749
<li>Confirm that your error hasn't been fixed already. The latest version of lcc is always
750
available for anonymous <code>ftp</code> from <code>ftp.cs.princeton.edu</code> in <a
751
HREF="ftp://ftp.cs.princeton.edu/pub/lcc"><code>pub/lcc</code></a>. A <a
752
HREF="ftp://ftp.cs.princeton.edu/pub/lcc/README"><code>README</code></a> file there gives
753
acquistion details, and the <a HREF="../LOG"><code>LOG</code></a> file reports what errors
754
were fixed and when they were fixed. If you report a error that's been fixed, you might
755
get a canned reply.</li>
756
<li>Send your program by electronic mail to <code>lcc-bugs@cs.princeton.edu</code>. Please
757
send only valid C programs; put all remarks in C comments so that we can process reports
758
semiautomatically.</li>
761
<h2><a NAME="mailinglist">Keeping in Touch</a></h2>
763
<p>There is an lcc mailing list for general information about lcc. To be added to the
764
list, send a message with the 1-line body</p>
767
<pre>subscribe lcc</pre>
770
<p>to <code>majordomo@cs.princeton.edu</code>. This line must appear in the message body;
771
"Subject:" lines are ignored. To learn more about mailing lists served by <code>majordomo</code>,
772
send a message with the 1-word body "<code>help</code>" to <code>majordomo@cs.princeton.edu</code>.
773
Mail sent to <code>lcc@cs.princeton.edu</code> is forwarded to everyone on the mailing
776
<p>There is also an <code>lcc-bugs</code> mailing list for reporting bugs; subscribe to it
777
by sending a message with the 1-line body </p>
780
<pre>subscribe lcc-bugs</pre>
783
<p>to <code>majordomo@cs.princeton.edu</code>. Mail addressed to <var>lcc-bugs@cs.princeton.edu</var>
784
is forwarded to everyone on this list.</p>
789
<a HREF="http://www.research.microsoft.com/~cwfraser/">Chris Fraser</a> / <a
790
HREF="mailto:cwfraser@microsoft.com">cwfraser@microsoft.com</a><br>
791
<a HREF="http://www.research.microsoft.com/~drh/">David Hanson</a> / <a
792
HREF="mailto:drh@microsoft.com">drh@microsoft.com</a><br>
793
$Revision: 145 $ $Date: 2001-10-17 16:53:10 -0500 (Wed, 17 Oct 2001) $
added
removed
code/tools/lcc/doc/install.html
