![[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.