![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to install.tex CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10no / cmd / lcc / doc|
Return to install.tex CVS log | Up to [Research Unix] / researchv10no / cmd / lcc / doc |
1.1 root 1: \documentstyle{article}
2:
3: \title{Installing lcc}
4:
5: \author{Christopher W. Fraser\\
6: AT\&T Bell Laboratories, 600 Mountain Avenue,\\
7: Murray Hill, NJ 07974
8: \and
9: David R. Hanson\\
10: Department of Computer Science, Princeton University,\\
11: Princeton, NJ 08544}
12:
13: \date{May 21, 1991\\ Last Revised September 15, 1992}
14:
15: \begin{document}
16: %\bibliographystyle{abbrv}
17:
18: \maketitle
19:
20: \section{Introduction}
21:
22: \verb|lcc| is a retargetable compiler for ANSI C~\cite{ansi:Cstandard}.
23: \verb|lcc| is in production use
24: at Princeton University and AT\&T Bell Laboratories.
25: When used with a conforming preprocessor and library,
26: \verb|lcc| passes the conformance section of Version 2.00 of the Plum-Hall
27: Validation Suite for ANSI~C.
28:
29: Extract the distribution into its own directory.
30: All paths below are relative to this directory.
31:
32: All distributions include the following top-level directories;
33: ``front-end'' distributions include {\em only\/} these directories.
34:
35: \begin{center}
36: \begin{tabular}{ll}
37: \tt c & front end \\
38: \tt etc & driver, man page \\
39: \tt doc & this document, other documentation \\
40: \tt include & ANSI include files \\
41: \tt tst & test suite \\
42: \tt gen0 & ``symbolic'' code generator \\
43: \tt gen3 & demonstration VAX code generator \\
44: \end{tabular}
45: \end{center}
46: ``Front-end'' distributions include no production code generators
47: and Sec.~\ref{gen2} of this document does not apply.
48: Secs.~\ref{gen3} and \ref{gen0} describe how to build compilers
49: with the demonstation VAX code generator and
50: the symbolic code generator, respectively.
51:
52: ``Full'' distributions include code generators for the VAX, MIPS,
53: and Motorola 68020 with the 68881 floating-point co-processor.
54: These distributions add the top-level directory
55: \verb|gen2|, which holds the production code generators.
56:
57: Installation of a production compiler
58: involves three steps performed in the following order.
59: \begin{enumerate}
60: \item Decide where to install the man page, the include files,
61: the compiler, and \verb|lcc|, the driver program; see Sec.~\ref{paths}.
62:
63: \item Install a host-specific driver; see Sec.~\ref{driver}.
64:
65: \item Install a host- and target-specific compiler; see Sec.~\ref{gen2}.
66: \end{enumerate}
67:
68: \verb|c/version.h| identifies the version of the distribution
69: as {\tt (($x$<<8)|$y$)} for version {\tt $x$.$y$},
70: and \verb|LOG| describes the changes from the previous version.
71:
72: \verb|doc/*.tex| are \LaTeX\ input files for several reports that
73: describe \verb|lcc|, including this one.
74: To format these reports, run \verb|latex| twice, e.g.,
75: \begin{verbatim}
76: $ latex overview; latex overview
77: \end{verbatim}
78: Ignore warnings about overfull boxes.
79:
80: \section{Paths}\label{paths}
81:
82: Installation consists of three files and one directory;
83: these are summarized below along with paths used in typical installations.
84:
85: \begin{center}
86: \begin{tabular}{ll}
87: \tt /usr/local/man/man1/lcc.1 & the man page \\
88: \tt /usr/local/lib/rcc & the compiler \\
89: \tt /usr/local/bin/lcc & the driver \\
90: \tt /usr/local/include/ansi & include files (a directory) \\
91: \end{tabular}
92: \end{center}
93:
94: These files can be placed in other, site-specific locations,
95: but the compiler should be named \verb|rcc|.
96: If the driver isn't named \verb|lcc|, edit the man page (\verb|etc/lcc.1|).
97:
98: Include files are in directories named \verb|include/|{\it target}\verb|_|{\it system};
99: the following table lists the available combinations.
100: \begin{center}
101: \begin{tabular}{lll}
102: \em target & \em system & operating system \\[0.5ex]
103: \tt vax & \tt bsd & 4.3BSD UNIX \\
104: & \tt ultrix & ULTRIX 3.0 \\
105: & \tt v9 & 9th Edition UNIX \\
106: \tt mips & \tt iris & IRIX System V Release 3.2 \\
107: & \tt mips & RISC/OS 4.0 \\
108: & \tt ultrix & ULTRIX 4.0 \\
109: \tt mc & \tt sun & SunOS 4.0 \\
110: & \tt next & Mach \\
111: % \tt sparc & \tt sun & SunOS 4.0 \\
112: \end{tabular}
113: \end{center}
114: Not all combinations of {\it target}, {\it system\/} are provided
115: and many don't make sense.
116: Choose the include files that are appropriate for your system,
117: or make a copy of a closely related set and edit them.
118:
119: For example, if the paths shown above are chosen and if
120: \verb|include/mips_ultrix| has the appropriate include files,
121: install the man page and include files by
122: \begin{verbatim}
123: $ cp etc/lcc.1 /usr/local/man/man1
124: $ cp include/mips_ultrix/*.h /usr/local/include/ansi
125: \end{verbatim}
126:
127: \section{Installing the Driver}\label{driver}
128:
129: The preprocessor, compiler, assembler, and loader are
130: invoked by a driver program, \verb|lcc|, which is similar
131: to \verb|cc| on most systems. It's described in the man page
132: \verb|etc/lcc.1|.
133: The driver is built by combining the host-independent
134: part, \verb|etc/lcc.c|, with a small host-specific part.
135: By convention, host-specific parts are named {\it hostname}\verb|.c|,
136: where {\it hostname\/} is the local name for the host on which \verb|lcc|
137: is being installed. \verb|etc| holds many examples.
138: Comments in most give the details of the
139: particular host; pick one that is closely related to your host,
140: copy it to \verb|etc/|{\it yourhostname}\verb|.c|,
141: and edit it as described below.
142: You should not have to edit \verb|etc/lcc.c|.
143:
144: Debug your version of the driver by running it
145: with the \verb|-v -v| options, which cause it to echo the
146: commands it would execute, but not to execute them.
147:
148: Here's \verb|etc/hart.c|, which we'll use as an example
149: in describing how to edit a host-specific part.
150: This example illustrates all of the important features.
151: \begin{verbatim}
152: /* DECStations running ULTRIX at Princeton University */
153:
154: #include <string.h>
155:
156: char *cpp[] = {
157: "/usr/gnu/lib/gcc-cpp", "-undef",
158: "-DLANGUAGE_C", "-D_LANGUAGE_C", "-D__LANGUAGE_C",
159: "-D_unix", "-D__unix",
160: "-Dultrix", "-D_ultrix", "-D__ultrix",
161: "-Dmips", "-D_mips", "-D__mips",
162: "-Dhost_mips", "-D_host_mips", "-D__host_mips",
163: "-DMIPSEL", "-D_MIPSEL", "-D__MIPSEL",
164: "$1", "$2", "$3", 0 };
165: char *include[] = { "-I/usr/local/include/ansi", 0 };
166: char *com[] = { "/usr/local/lib/rcc", "$1", "$2", "$3", 0 };
167: char *as[] = { "/bin/as", "-o", "$3", "", "$1",
168: "-nocpp", "-EL", "$2", 0 };
169: char *ld[] = { "/usr/bin/ld", "-o", "$3", "/usr/lib/crt0.o",
170: "$1", "$2", "", "", "-lm", "-lc", 0 };
171:
172: int option(arg) char *arg; {
173: if (strcmp(arg, "-g") == 0)
174: as[3] = "-g";
175: else if (strcmp(arg, "-p") == 0
176: && strcmp(ld[3], "/usr/lib/crt0.o") == 0) {
177: ld[3] = "/usr/lib/mcrt0.o";
178: ld[7] = "/usr/lib/libprof1.a";
179: } else if (strcmp(arg, "-b") == 0
180: && access("/usr/local/lib/bbexit.o", 4) == 0)
181: ld[6] = "/usr/local/lib/bbexit.o";
182: else
183: return 0;
184: return 1;
185: }
186: \end{verbatim}
187:
188: Most of the host-specific code is data that
189: gives prototypes for the commands that invoke
190: the preprocessor, compiler, assembler, and loader.
191: Each command prototype is an array of pointers to strings
192: terminated with a null pointer;
193: the first string is the full path name of the command and the others
194: are the arguments or argument placeholders, which are described below.
195:
196: The \verb|cpp| array gives the command for running the preprocessor.
197: \verb|lcc| is intended to be used with an ANSI preprocessor,
198: such as the GNU C preprocessor available from the Free Software Foundation.
199: If the GNU preprocessor is used,
200: it must be named \verb|gcc-cpp| in order for \verb|lcc|'s \verb|-N| option
201: to work correctly.
202:
203: Literal arguments specified in prototypes, e.g., \verb|"-Dmips"| in
204: the \verb|cpp| command above, are passed to the command as given.
205:
206: The strings \verb|"$1"|, \verb|"$2"|, and \verb|"$3"| in
207: prototypes are placeholders for {\em lists} of arguments that
208: are substituted in a copy of the prototype before the command is executed.
209: \verb|$1| is replaced by the {\em options} specified by the user;
210: for the preprocessor, this list always contains at least
211: \verb|-Dunix| and \verb|-D__LCC__|.
212: \verb|$2| is replaced by the {\em input} files,
213: and \verb|$3| is replaced by the {\em output} file.
214:
215: Zero-length arguments after replacement are removed from
216: the argument list before the command is invoked. So, e.g.,
217: if the preprocessor is invoked without an output file,
218: \verb|"$3"| becomes \verb|""|, which is removed from the final argument list.
219:
220: For example, to specify a preprocessor command prototype to invoke
221: \verb|/bin/cpp| with the options \verb|-Dmips| and \verb|-Dultrix|,
222: the \verb|cpp| array would be
223: \begin{verbatim}
224: char *cpp[] = { "/bin/cpp", "-Dvax", "-Dultrix",
225: "$1", "$2", "$3", 0 };
226: \end{verbatim}
227:
228: The \verb|include| array is a list of \verb|-I| options that
229: specify which directives should be searched to satisfy include directives.
230: These directories are searched in the order given.
231: The first directory should be the one to which the ANSI
232: header files were copied in Sec.~\ref{paths}.
233: The driver adds these options to \verb|cpp|'s arguments
234: when it invokes the preprocessor, except when \verb|-N| is specified.
235:
236: Design this list carefully. Mixing ANSI and pre-ANSI headers (e.g., by
237: listing \verb|/usr/include| after the directory of ANSI headers as
238: shown above) may mix incompatible headers. Unless the default list holds {\em only}
239: \verb|/usr/include| or {\em only\/} the ANSI headers, many users may be
240: forced to use \verb|-N| and \verb|-I| incessantly.
241:
242: \verb|com| gives the command for invoking the compiler.
243: This prototype can appear exactly as shown above, except
244: that the command name should be edited to reflect the
245: location of the compiler chosen in Sec.~\ref{paths}.
246:
247: \verb|as| gives the command for invoking the assembler.
248:
249: \verb|ld| gives the command for invoking the loader.
250: For the other commands, the list \verb|$2| contains a single file;
251: for \verb|ld|, \verb|$2| contains all `.o' files and libraries, and
252: \verb|$3| is \verb|a.out|, unless the \verb|-o| option is specified.
253: As suggested in the code above, \verb|ld| must also specify
254: the appropriate startup code and default libraries.
255:
256: The \verb|option| function is described below;
257: for now, use an existing \verb|option| function or one that returns \verb|0|.
258:
259: After specifying the prototypes, compile the driver by
260: \begin{verbatim}
261: $ cd etc
262: $ make HOST=hart
263: \end{verbatim}
264: where \verb|hart| is replaced by {\it yourhostname}.
265: Run the resulting \verb|a.out| with the options \verb|-v -v|
266: to display the commands that would be executed, e.g.,
267: \begin{verbatim}
268: $ a.out -v -v foo.c baz.c mylib.a -lX11
269: a.out version 1.9
270: foo.c:
271: /usr/gnu/lib/gcc-cpp -undef -DLANGUAGE_C -D_LANGUAGE_C
272: -D__LANGUAGE_C -D_unix -D__unix -Dultrix -D_ultrix -D__ultrix
273: -Dmips -D_mips -D__mips -Dhost_mips -D_host_mips -D__host_mips
274: -DMIPSEL -D_MIPSEL -D__MIPSEL -Dunix -D__LCC__ -v
275: -I/usr/local/include/ansi foo.c |
276: /usr/local/lib/rcc -v - /tmp/lcc18299.s
277: /bin/as -o foo.o -nocpp -EL /tmp/lcc18299.s
278: baz.c:
279: /usr/gnu/lib/gcc-cpp -undef -DLANGUAGE_C -D_LANGUAGE_C
280: -D__LANGUAGE_C -D_unix -D__unix -Dultrix -D_ultrix -D__ultrix
281: -Dmips -D_mips -D__mips -Dhost_mips -D_host_mips -D__host_mips
282: -DMIPSEL -D_MIPSEL -D__MIPSEL -Dunix -D__LCC__ -v
283: -I/usr/local/include/ansi baz.c |
284: /usr/local/lib/rcc -v - /tmp/lcc18299.s
285: /bin/as -o baz.o -nocpp -EL /tmp/lcc18299.s
286: /usr/bin/ld -o a.out /usr/lib/crt0.o foo.o baz.o mylib.a
287: -lX11 -lm -lc
288: rm /tmp/lcc18299.s
289: \end{verbatim}
290: Leading spaces indicate lines that have been folded manually to fit this page.
291: Note the use of a pipeline to connect the preprocessor and compiler.
292: \verb|lcc| arranges this pipeline itself; it does not call the shell.
293:
294: As the output shows, \verb|lcc| places temporary files in \verb|/tmp|.
295: Alternatives can be specified by defining \verb|TEMPDIR| in \verb|CFLAGS|
296: when making the driver, e.g.,
297: \begin{verbatim}
298: $ make CFLAGS='-DTEMPDIR=\"/usr/tmp\"' HOST=hart
299: \end{verbatim}
300: causes \verb|lcc| to place temporary files in \verb|/usr/tmp|.
301:
302: Once the driver is completed, install it by
303: \begin{verbatim}
304: $ cp a.out /usr/local/bin/lcc
305: \end{verbatim}
306: where the destination is the location chosen for \verb|lcc| in Sec.~\ref{paths}.
307:
308: The \verb|option| function is called for the options
309: \verb|-g|, \verb|-p|, \verb|-pg|, and \verb|-b| because these compiler options might
310: also affect the loader's arguments. For these options,
311: the driver calls \verb|option(arg)| to give the host-specific
312: code an opportunity to edit the \verb|ld| prototype, if necessary.
313: \verb|option| can change \verb|ld|, if necessary, and return \verb|1| to
314: announce its acceptance of the option. If the option
315: is unsupported, \verb|option| should return \verb|0|.
316:
317: For example, in response to \verb|-g|, the \verb|option| function shown above
318: changes \verb|as[3]| from \verb|""| to \verb|"-g"|, which specifies
319: the debugging option to the assembler. If \verb|-g| is not specified,
320: the \verb|""| argument is omitted from the \verb|as| command
321: because it's empty.
322:
323: Likewise, the \verb|-p| causes \verb|option| to change the name
324: of the startup code and add the name of the profiling library. Note that
325: \verb|option| has been written to support simultaneous use
326: of \verb|-g| and \verb|-p|, e.g.,
327: \begin{verbatim}
328: $ a.out -v -v -g -p foo.s baz.o -o myfoo
329: a.out version 1.9
330: /bin/as -o foo.o -g -nocpp -EL foo.s
331: /usr/bin/ld -o myfoo /usr/lib/mcrt0.o foo.o baz.o
332: /usr/lib/libprof1.a -lm -lc
333: rm /tmp/lcc18317.s
334: \end{verbatim}
335:
336: On Suns, the driver
337: passes any option beginning with \verb|-f| to \verb|option|
338: to support Sun's \verb|-f68881| option. The driver also
339: recognizes \verb|-Bstatic| and \verb|-Bdynamic| as linker options,
340: and recognizes but ignores Sun's \verb|-target|~{\it name\/} option.
341:
342: The option \verb|-Wo|{\it arg\/} causes the driver to pass {\it arg\/}
343: to \verb|option|. Such options have no other effect; this mechanism
344: is provided to support system-specific options that affect the
345: commands executed by the driver.
346:
347: The \verb|-b| option causes the compiler to generate
348: code to count the number of times each expression is executed.
349: The \verb|exit| function in \verb|etc/bbexit.c| writes these
350: counts to \verb|prof.out| when the program terminates.
351: If \verb|option| is called with \verb|-b|,
352: it must edit the \verb|ld| command accordingly,
353: as shown above. This version of \verb|option| uses
354: the \verb|access| system call to insure that \verb|bbexit.o| is installed before
355: editing the \verb|ld| command. To install \verb|bbexit.o| execute
356: \begin{verbatim}
357: $ make bbexit.o
358: $ cp bbexit.o /usr/local/lib/bbexit.o
359: \end{verbatim}
360: If necessary, change \verb|/usr/local/lib| to reflect local conventions.
361: The \verb|exit| function in \verb|etc/bbexit.c| works on the
362: systems listed in Sec.~\ref{paths}, but may need to be modified for other systems.
363: The implementation of the \verb|-b| option is described
364: in Ref.~\cite{fraser:hanson:91b}.
365: The \LaTeX\ source for the technical report version of this paper
366: is in \verb|doc/overview.tex|.
367:
368: If \verb|option| supports \verb|-b|, you should also
369: install \verb|etc/bprint.c|, which reads \verb|prof.out|
370: and generates a listing annotated with execution counts.
371: After \verb|lcc| is installed, install \verb|bprint| with the commands
372: \begin{verbatim}
373: $ make bprint
374: $ cp bprint /usr/local/bin/bprint
375: $ cp bprint.1 /usr/local/man/man1
376: \end{verbatim}
377: The \verb|makefile| uses \verb|lcc| to compile \verb|bprint.c|;
378: you must use \verb|lcc| or another ANSI~C compiler, e.g., \verb|gcc|,
379: because \verb|bprint.c| is written in ANSI~C.
380: Also, \verb|bprint.c| {\em includes\/} \verb|"../c/profio.c"|, so it must
381: be compiled in \verb|etc|.
382:
383: To complete the driver,
384: write an appropriate \verb|option| function for your system,
385: and make and install the driver as described above.
386:
387: \section{Installing a Production Compiler}\label{gen2}
388:
389: \verb|gen2| contains source code common to all of the production
390: code generators and directories for each of the supported targets:
391:
392: \begin{center}
393: \begin{tabular}{ll}
394: \tt gen2/vax & VAX code generator \\
395: \tt gen2/mips & MIPS code generator \\
396: \tt gen2/mc & Motorola 68020 \& 68881 code generator \\
397: %\tt gen2/sparc & SPARC code generator \\
398: \end{tabular}
399: \end{center}
400:
401: A production compiler, \verb|rcc|, is built by compiling it
402: with the host C compiler and then using the result to re-compile itself.
403: A test suite is used to
404: verify that the compiler is working correctly.
405: The examples below use the MIPS compiler under Ultrix
406: to illustrate this process.
407: You must have the driver, \verb|lcc|, installed in order
408: to build and test \verb|rcc|.
409: If any of the steps below fail, contact us (see Sec.~\ref{bugs}).
410:
411: The \verb|makefile| runs the shell script
412: \verb|gen2/run| on each C program in the test suite, \verb|tst|.
413: \verb|gen2/makefile| uses \verb|include| directives, which are supported by
414: most versions of \verb|make|. If your version of \verb|make|
415: doesn't support \verb|include|, build a suitable \verb|makefile|
416: by replacing the \verb|include|s with the specified \verb|makefile|s.
417: Note that the path names are relative to the \verb|gen2| directory.
418:
419: The object files, \verb|rcc|, and the generated code for
420: the programs in the test suite are placed in the directory
421: {\tt gen2/\it target\/\tt-\it system\/} where {\it target\/} and {\it system\/}
422: are the names of your target machine and its operating system, respectively.
423: There are directories for the supported {\it target\/}, {\it system\/} combinations,
424: e.g., \verb|mips-ultrix|.
425:
426: The {\it target\/} and {\it system\/} values are read from the
427: variables \verb|TARGET| and \verb|OS|, respectively.
428: Values for these variables must be specified when invoking \verb|make|
429: along with system-specific values for \verb|CFLAGS| and \verb|LDFLAGS|,
430: if necessary.
431: The following table lists the \verb|make| commands for the supported
432: {\it target\/-system\/} combinations.
433: \begin{center}\tt
434: \begin{tabular}{llll}
435: make TARGET=vax & OS=bsd\\
436: make TARGET=vax & OS=ultrix\\
437: make TARGET=vax & OS=v9\\[1ex]
438:
439: make TARGET=mips & OS=iris & CFLAGS=-cckr\\
440: make TARGET=mips & OS=ultrix\\
441: make TARGET=mips & OS=mips\\[1ex]
442:
443: %make TARGET=sparc & OS=sun & LDFLAGS='-s -Bstatic'\\[1ex]
444:
445: make TARGET=mc & OS=sun & LDFLAGS='-s -Bstatic'\\
446: make TARGET=mc & OS=next\\
447: \end{tabular}
448: \end{center}
449: For example, to build an \verb|rcc| for a MIPS running Ultrix, execute the commands
450: \begin{verbatim}
451: $ cd gen2
452: $ make TARGET=mips OS=ultrix
453: cd mips-ultrix;
454: cc -c -Dmips_ultrix -I../mips -I.. -I../../c ../../c/dag.c
455: ...
456: cd mips-ultrix;
457: cc -c -Dmips_ultrix -I../mips -I.. -I../../c ../mips/sel.c
458: cc -s -o mips-ultrix/rcc mips-ultrix/dag.o ... mips-ultrix/sel.o
459: \end{verbatim}
460: There may be a few warnings, but there should be no errors.
461:
462: Once \verb|rcc| is built with the host C compiler,
463: run the test suite to verify that \verb|rcc| is working correctly,
464: specifying the appropriate operating system from those listed
465: in Sec.~\ref{paths}, e.g.,
466: \begin{verbatim}
467: $ make TARGET=mips OS=ultrix test
468: mips-ultrix 8q:
469: mips-ultrix array:
470: mips-ultrix cf:
471: mips-ultrix cq:
472: mips-ultrix cvt:
473: mips-ultrix fields:
474: mips-ultrix front:
475: mips-ultrix incr:
476: mips-ultrix init:
477: mips-ultrix limits:
478: mips-ultrix paranoia:
479: mips-ultrix sort:
480: mips-ultrix spill:
481: mips-ultrix stdarg:
482: mips-ultrix struct:
483: mips-ultrix switch:
484: mips-ultrix wf1:
485: mips-ultrix yacc:
486: \end{verbatim}
487: For each C program in the test suite,
488: \verb|gen2/run| compiles the program and uses \verb|diff|
489: to compare the generated assembly code
490: with the expected code (the expected MIPS code for \verb|tst/8q.c| is
491: in \verb|gen2/mips-ultrix/tst/8q.s.bak|, etc.). If there are differences, the script
492: executes the generated code with the input given in \verb|tst|
493: (the input for \verb|tst/8q.c| is in \verb|tst/8q.0|, etc.)
494: and compares the output with the expected output
495: (the expected output from \verb|tst/8q.c| on the MIPS is
496: in \verb|gen2/mips-ultrix/tst/8q.1.bak|, etc.). The script also compares the
497: diagnostics from the compiler with the expected diagnostics.
498:
499: On some systems, there may be a few differences between the generated code
500: and the expected code.
501: These differences occur because the expected code is
502: generated by cross compilation
503: on a MIPS and the least-significant bits of some floating-point constants
504: differ from those bits in constants generated on your system.
505: There should be no differences in the output from executing the test programs.
506:
507: The \verb|mips-ultrix| preceding the name of each test program in the output
508: above indicates a {\it target\/\it-system\/} combination, e.g.,
509: ``generating code for a \verb|mips| running the
510: \verb|ultrix| operating system''.
511:
512: Next, build \verb|rcc| again using the just-built \verb|rcc|:
513: \begin{verbatim}
514: $ make TARGET=mips OS=ultrix triple
515: rm -f mips-ultrix/*.o
516: make TARGET=mips OS=ultrix CC='lcc -B./ -d0.1 -A'
517: CFLAGS='-N -I../../include/mips_ultrix '
518: LDFLAGS='-s' mips-ultrix/rcc
519: cd mips-ultrix;
520: lcc -B./ -d0.1 -A -c -Dmips_ultrix -N -I../../include/mips_ultrix
521: -I../mips -I.. -I../../c ../../c/dag.c
522: ...
523: lcc -B./ -d0.1 -A -s -o mips-ultrix/rcc
524: mips-ultrix/dag.o ... mips-ultrix/sel.o
525: od +8 <mips-ultrix/rcc >mips-ultrix/tst/od2
526: rm -f mips-ultrix/*.o
527: make TARGET=mips OS=ultrix CC='lcc -B./ -d0.1 -A'
528: CFLAGS='-N -I../../include/mips_ultrix '
529: LDFLAGS='-s' mips-ultrix/rcc
530: cd mips-ultrix;
531: lcc -B./ -d0.1 -A -c -Dmips_ultrix -N -I../../include/mips_ultrix
532: -I../mips -I.. -I../../c ../../c/dag.c
533: ...
534: lcc -B./ -d0.1 -A -s -o mips-ultrix/rcc
535: mips-ultrix/dag.o ... mips-ultrix/sel.o
536: od +8 <mips-ultrix/rcc >mips-ultrix/tst/od3
537: cmp mips-ultrix/tst/od[23] && rm mips-ultrix/tst/od[23]
538: \end{verbatim}
539: This command builds \verb|mips-ultrix/rcc| twice; once using the
540: \verb|mips-ultrix/rcc| built by \verb|cc|
541: and again using the \verb|mips-ultrix/rcc| built by \verb|lcc|.
542: After building each version, an octal dump of the resulting binary is made,
543: and the two dumps are compared. They should be identical, as shown
544: at the end of the output above.
545: If they aren't, our compiler is generating bad code.
546: This triple-compilation test is described in Ref.~\cite{cornelius:etal:84}.
547: (They name four generations because they number them differently.)
548:
549: The final version of \verb|mips-ultrix/rcc| should also pass the test suite;
550: i.e., the output from \verb|make TARGET=mips OS=ultrix test|
551: should be identical to that from the previous \verb|make|.
552:
553: Now install the final version of \verb|mips-ultrix/rcc|:
554: \begin{verbatim}
555: $ cp mips-ultrix/rcc /usr/local/lib/rcc
556: \end{verbatim}
557: where the destination is the location chosen for \verb|rcc| in Sec.~\ref{paths}.
558:
559: On some systems, you may be able
560: to use environment variables and \verb|make|'s \verb|-e|
561: option to avoid specifying \verb|TARGET|
562: and \verb|OS| on each \verb|make| command, and
563: the \verb|make| commands described above can be done with a single command:
564: \begin{verbatim}
565: $ TARGET=mips OS=ultrix export TARGET OS
566: $ make -e test triple test clean
567: \end{verbatim}
568: \verb|make clean| cleans up, but does not remove \verb|mips-ultrix/rcc|, and
569: \verb|make clobber| cleans up and removes \verb|mips-ultrix/rcc|.
570:
571: The software used to build the production code generators
572: is described in Ref.~\cite{fraser:sigplan89}; it is not available.
573:
574: \section{Building the Demonstration VAX Compiler}\label{gen3}
575:
576: The code generator in \verb|gen3| emits naive VAX code.
577: It is not a production code generator. It is included only
578: to illustrate the interface between the front end
579: and the code generator. If you want to replace \verb|lcc|'s code generator,
580: study it and not the larger production code generators.
581:
582: This code generator is detailed in
583: Refs.~\cite{fraser:hanson:interface:TR,fraser:hanson:91a,fraser:hanson:92}.
584: \verb|doc/interface.tex| holds the \LaTeX\ source for the latest
585: version of Ref.~\cite{fraser:hanson:interface:TR}.
586:
587: \verb|makefile| uses \verb|include| directives, which are supported by
588: most versions of \verb|make|. If your version of \verb|make|
589: doesn't support \verb|include|, build a suitable \verb|makefile|
590: by replacing the \verb|include|s with the specified \verb|makefile|s.
591:
592: The default and only acceptable \verb|TARGET| is \verb|vax|
593: and the default \verb|OS| is \verb|bsd|, so the commands
594: \begin{verbatim}
595: $ cd gen3
596: $ make test
597: \end{verbatim}
598: build and test \verb|vax-bsd/rcc|;
599: The \verb|makefile| uses \verb|lcc| instead of \verb|cc|
600: because \verb|gen3/gen.c| is written in ANSI~C.
601: If \verb|lcc| is unavailable, use another ANSI~C compiler, e.g., \verb|gcc|,
602: and use a command like
603: \begin{verbatim}
604: $ make CC=gcc test
605: \end{verbatim}
606: to build the demonstration compiler. Alternatively, you can specify
607: another ANSI~C compiler by editing \verb|gen3/makefile|.
608:
609: There may be warnings, but there should be no errors.
610: As for the production code generators, this command
611: tests \verb|vax-bsd/rcc| by running a shell script,
612: \verb|gen3/run|, on each C program in the test suite.
613: This script compiles a program and compares the generated VAX code
614: with the expected code (the expected VAX code for \verb|tst/8q.c| is
615: in \verb|gen3/vax-bsd/tst/8q.s.bak|, etc.).
616: There should be no significant differences.
617: If there are differences, the script executes the generated code
618: and compares the output with the expected output
619: (the expected output from \verb|tst/8q.c| is
620: in \verb|gen3/vax-bsd/tst/8q.1.bak|, etc.).
621:
622: \verb|make triple| is the same as for the production compilers,
623: \verb|make clean| cleans up, but does not remove \verb|rcc|, and
624: \verb|make clobber| cleans up and removes \verb|rcc|.
625:
626: \section{Building the Symbolic Compiler}\label{gen0}
627:
628: The code generator in \verb|gen0| documents the
629: interface between the front end and the code generator and is used routinely in
630: front-end development. The output of this code generator is a printable
631: representation of the input program, e.g., the dags constructed by the
632: front end are printed, and other interface functions print their arguments.
633: The output is not executable, unlike the output of the demonstration
634: VAX code generator.
635:
636: The interface is described in
637: Refs.~\cite{fraser:hanson:interface:TR,fraser:hanson:91a}.
638: The \LaTeX\ source for the latest version of
639: Ref.~\cite{fraser:hanson:interface:TR} is in \verb|doc/interface.tex|.
640:
641: \verb|makefile| uses \verb|include| directives, which are supported by
642: most versions of \verb|make|. If your version of \verb|make|
643: doesn't support \verb|include|, build a suitable \verb|makefile|
644: by replacing the \verb|include|s with the specified \verb|makefile|s.
645:
646: For the symbolic compiler, \verb|TARGET| and \verb|OS| serve only
647: to identify an include directory, and \verb|gen0/makefile|
648: specifies \verb|vax| and \verb|bsd| as defaults.
649: The commands
650: \begin{verbatim}
651: $ cd gen0
652: $ make test
653: \end{verbatim}
654: build the symbolic compiler, \verb|vax-bsd/rcc|, and tests it by running the shell script
655: \verb|gen0/run| on each C program in the test suite, \verb|tst|.
656: This script compiles a program and uses \verb|diff| to compare the generated symbolic code
657: with the expected code (the expected code for \verb|tst/8q.c| is
658: in \verb|gen0/vax-bsd/tst/8q.s.bak|, etc.). There should be no differences.
659: The script also compares the
660: diagnostics from the compiler with the expected diagnostics
661: (the expected diagnostics for \verb|tst/8q.c| are
662: in \verb|tst/8q.2|, etc.).
663:
664: \verb|make clean| cleans up, but does not remove \verb|rcc|, and
665: \verb|make clobber| cleans up and removes \verb|rcc|.
666:
667: \section{Reporting Bugs}\label{bugs}
668:
669: Bugs can be reported by sending mail with the shortest program
670: that exposes them and the details reported by \verb|lcc|'s \verb|-v|
671: option to \verb|[email protected]|.
672: Other questions, comments, and requests to be added
673: to the \verb|lcc| mailing list can be sent to \verb|[email protected]|.
674:
675: %\bibliography{refs,lib}
676: \begin{thebibliography}{1}
677:
678: \bibitem{ansi:Cstandard}
679: American National Standard Institute, Inc., New York.
680: \newblock {\em American National Standards for Information Systems, Programming
681: Language C {ANSI} X3.159--1989}, 1990.
682:
683: \bibitem{cornelius:etal:84}
684: B.~J. Cornelius, I.~R. Lowman, and D.~J. Robson.
685: \newblock Steady-state compilers.
686: \newblock {\em Software---Practice \& Experience}, 14(8):705--709, Aug. 1984.
687:
688: \bibitem{fraser:sigplan89}
689: C.~W. Fraser.
690: \newblock A language for writing code generators.
691: \newblock {\em Proceedings of the SIGPLAN'89 Conference on Programming Language
692: Design and Implementation, SIGPLAN Notices}, 24(7):238--245, July 1989.
693:
694: \bibitem{fraser:hanson:interface:TR}
695: C.~W. Fraser and D.~R. Hanson.
696: \newblock A code generation interface for {ANSI C}.
697: \newblock Technical Report CS-TR-270-90, Princeton University, Department of
698: Computer Science, Princeton, NJ, July 1990.
699:
700: \bibitem{fraser:hanson:91a}
701: C.~W. Fraser and D.~R. Hanson.
702: \newblock A code generation interface for {ANSI C}.
703: \newblock {\em Software---Practice \& Experience}, 21(9):963--988, Sept. 1991.
704:
705: \bibitem{fraser:hanson:91b}
706: C.~W. Fraser and D.~R. Hanson.
707: \newblock A retargetable compiler for {ANSI C}.
708: \newblock {\em SIGPLAN Notices}, 26(10):29--43, Oct. 1991.
709:
710: \bibitem{fraser:hanson:92}
711: C.~W. Fraser and D.~R. Hanson.
712: \newblock Simple register spilling in a retargetable compiler.
713: \newblock {\em Software---Practice \& Experience}, 22(1):85--99, Jan. 1992.
714:
715: \end{thebibliography}
716:
717: \end{document}
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.