install.html

lcc source code enjoy your self

src/alloc.c:
...
strip $BUILDDIR/sparc-solaris/[12]rcc
dd if=$BUILDDIR/sparc-solaris/1rcc of=$BUILDDIR/sparc-solaris/rcc1 bs=512 skip=1
1270+1 records in
1270+1 records out
dd if=$BUILDDIR/sparc-solaris/2rcc of=$BUILDDIR/sparc-solaris/rcc2 bs=512 skip=1
1270+1 records in
1270+1 records out
if cmp $BUILDDIR/sparc-solaris/rcc[12]; then \
        mv $BUILDDIR/sparc-solaris/2rcc $BUILDDIR/sparc-solaris/rcc; \
        rm -f $BUILDDIR/sparc-solaris/1rcc $BUILDDIR/sparc-solaris/rcc[12]; fi</pre>
</blockquote>

<p>This command builds <code>rcc</code> twice; once using the <code>rcc</code> built by <code>cc</code>
and again using the <code>rcc</code> built by <code>lcc</code>. The resulting binaries are
compared. They should be identical, as shown at the end of the output above. If they
aren't, our compiler is generating incorrect code; <a HREF="#bugs">contact</a> us.</p>

<p>The final version of <code>rcc</code> should also pass the test suite; that is, the
output from</p>

<blockquote>
  <pre>% make TARGET=sparc/solaris test</pre>
</blockquote>

<p>should be identical to that from the previous <code>make test</code>.</p>

<p>The command &quot;<code>make clean</code>&quot; cleans up, but does not remove <code>rcc</code>,
etc., and &quot;<code>make clobber</code>&quot; cleans up and removes <code>lcc</code>, <code>rcc</code>,
and the other accessories. Test directories under <code>BUILDDIR</code> are <em>not</em>
removed; you'll need to remove these by hand, e.g.,</p>

<blockquote>
  <pre>% rm -fr $BUILDDIR/sparc</pre>
</blockquote>

<p>The code generators for the other targets can be tested by specifying the desired <em>target</em><code>/</code><em>os</em>
and setting an environment variable that controls what <code>src/run.sh</code> does. For
example, to test the MIPS code generator, type</p>

<blockquote>
  <pre>% setenv REMOTEHOST noexecute
% make TARGET=mips/irix test</pre>
</blockquote>

<p>As above, <code>src/run.sh</code> compares the MIPS code generated with what's
expected. There should be no differences. Setting <code>REMOTEHOST</code> to <code>noexecute</code>
suppresses the assembly and execution of the generated code. If you set <code>REMOTEHOST</code>
to the name of a MIPS machine to which you can <code>rlogin</code>, <code>src/run.sh</code>
will <code>rcp</code> the generated code to that machine and execute it there, if
necessary. See <code>src/run.sh</code> for the details.</p>

<p>You can use lcc as a cross compiler. The options <code>-S</code> and <code>-Wf-target=</code><em>target/os</em>
generate assembly code for the specified target, which is any of those listed in the file <code>src/bind.c</code>.
For example, </p>

<blockquote>
  <pre>% lcc -Wf-target=mips/irix -S tst/8q.c</pre>
</blockquote>

<p>generates MIPS code for <code>tst/8q.c</code> in <code>8q.s</code>.</p>

<p>lcc can also generate code for a &quot;symbolic&quot; target. This target is used
routinely in front-end development, and its output is a printable representation of the
input program, e.g., the dags constructed by the front end are printed, and other
interface functions print their arguments. You can specify this target with the option <code>-Wf-target=symbolic</code>.
For example,</p>

<blockquote>
  <pre>% lcc -Wf-target=symbolic -S tst/8q.c</pre>
</blockquote>

<p>generates symbolic output for <code>tst/8q.c</code> in <code>8q.s</code>. Adding <code>-Wf-html</code>
causes the symbolic target to emit HTML instead of plain text. Finally, the option <code>-Wf-target=null</code>
specifies the &quot;null&quot; target for which lcc emits nothing and thus only checks the
syntax and semantics of its input files.</p>

<h2><a NAME="win32">Installation on Windows</a></h2>

<p>On Windows, lcc is designed to work with Microsoft's Visual
C++ (VC), version 5.0 and above, and Microsoft's Assembler, MASM. It uses the VC header files,
libraries, and command-line tools, and it uses MASM to assemble the code it generates. 
You must use MASM 6.11d or later,
because earlier  releases generate incorrect COFF object files. MASM 
6.15 is available as part of the free
<a href="http://msdn.microsoft.com/vstudio/downloads/ppack/default.asp">Visual 
C++ 6.0 Processor Pack</a>.</p>

<p>Building the distribution components from the ground up requires Microsoft's Visual
C/C++ compiler, Microsoft's make, <code>nmake</code>, and the standard Windows command
interpreter. <a HREF="../makefile.nt"><code>makefile.nt</code></a> is written to use only <code>nmake</code>.
As on UNIX systems, the compilation components are installed in a single <em>build
directory</em>, and the top-level programs, <code>lcc.exe</code> and <code>bprint.exe</code>,
are installed in a directory on the PATH. If the conventions used below are followed, the
Windows-specific parts of the driver program, <code>lcc.exe</code>, can be used
unmodified.</p>

<p>Building from the source distribution on a Windows system involves the following steps.
Below, the build directory is referred to as <code>BUILDDIR</code>, and the distribution
is in <code>\dist\lcc</code>. 

<ol>
  <li>Create the build directory, perhaps using a version- and platform-specific naming
    convention as suggested in <a HREF="#unix"><em>Installation on UNIX</em></a>, and record
    the name of this directory in the <code>BUILDDIR</code> environment variable:<blockquote>
      <pre>C:\dist\lcc&gt;set BUILDDIR=\progra~1\lcc\<i>version</i>\bin
C:\dist\lcc&gt;mkdir %BUILDDIR%</pre>
    </blockquote>
    <p>The default build, or installation, directory is <code>\Program Files\lcc\</code><i>version</i><code>\bin</code>, 
    where <i>version</i> is the version number, e.g., 4.2, but the <code>nmake</code> commands require that you use the corresponding 8.3 file name, <code>progra~1</code>,
    instead of <code>Program Files</code>.</p>
  </li>
  <li><a HREF="../etc/win32.c"><code>etc\win32.c</code></a> is the Windows-specific part of
    the driver. It assumes that environment variable <code>include</code> gives the locations
    of the VC header files and that the linker (<code>link.exe</code>) and the assembler (<code>ml.exe</code>)
    are on the PATH. It also assumes that the macro <code>LCCDIR</code> gives the build
    directory. If necessary, revise a copy of <a HREF="../etc/win32.c"><code>etc\win32.c</code></a>
    to reflect the conventions on your computer (see <a HREF="#driver"><em>Building the Driver</em></a>),
    then build the driver, specifying the default temporary directory, if necessary:<blockquote>
      <pre>C:\dist\lcc&gt;nmake -f makefile.nt HOSTFILE=etc/win32.c lcc
...
        cl -nologo -Zi -MLd -Fd%BUILDDIR%\ -c -Fo%BUILDDIR%\lcc.obj etc/lcc.c
lcc.c
        cl -nologo -Zi -MLd -Fd%BUILDDIR%\ -c -Fo%BUILDDIR%\host.obj etc/win32.c
win32.c
        cl -nologo -Zi -MLd -Fd%BUILDDIR%\ -Fe%BUILDDIR%\lcc.exe %BUILDDIR%\lcc.obj %BUILDDIR%\host.obj</pre>
    </blockquote>
    <p>If you make a copy of <code>etc\win32.c</code>, specify the path of the copy as the
    value of <code>HOSTFILE</code>. For example, if you copy <code>etc\win32.c</code> to <code>BUILDDIR</code>
    and edit it, use the command</p>
    <blockquote>
      <pre>C:\dist\lcc&gt;nmake -f makefile.nt HOSTFILE=%BUILDDIR%\win32.c lcc</pre>
    </blockquote>
  </li>
  <li>Build the preprocessor, compiler proper, library, and other accessories (see <a
    HREF="#rcc"><em>Building the Compiler</em></a>):<blockquote>
      <pre>C:\dist\lcc&gt;nmake -f makefile.nt all</pre>
    </blockquote>
    <p>This command uses the VC command-line tools <code>cl</code> and <code>lib</code> to
    build <code>bprint.exe</code>, <code>cpp.exe</code>, <code>lburg.exe</code>, <code>liblcc.lib</code>,
    <code>librcc.lib</code>, and <code>rcc.exe</code>, all in <code>BUILDDIR</code>. There may
    be some warnings, but there should be no warnings.</p>
  </li>
  <li>Create a test directory and run the test suite:<blockquote>
      <pre>C:\dist\lcc&gt;mkdir %BUILDDIR%\x86\win32\tst
C:\dist\lcc&gt;nmake -f makefile.nt test</pre>
    </blockquote>
    <p>This command compiles each program in <a HREF="../tst">tst</a>, compares the generated
    assembly code and diagnostics with the expected assembly code and diagnostics, executes
    the program, and compares the output with the expected output (using <code>fc</code>). For
    example, when the nmake command compiles <a HREF="../tst/8q.c"><code>tst\8q.c</code></a>,
    it leaves the generated assembly code and diagnostic output in <code>%BUILDDIR%\x86\win32\tst\8q.s</code>
    and <code>%BUILDDIR%\x86\win32\tst\8q.2</code>, and it compares them with the expected
    results in <code>x86\win32\tst\8q.sbk</code>. It builds the executable program in <code>%BUILDDIR%\x86\win32\tst\8q.exe</code>,
    runs it, and redirects the output to <code>%BUILDDIR%\x86\win32\tst\8q.1</code>, which it
    compares with <code>x86\win32\tst\8q.1bk</code>. The output from this step is voluminous,
    but there should be no differences and no errors.</p>
  </li>
  <li>Run the &quot;triple&quot; test, which compiles <code>rcc</code> with itself and
    verifies the results:<blockquote>
      <pre>C:\dist\lcc&gt;nmake -f makefile.nt triple
...
 Assembling: C:/TEMP/lcc2001.asm
        fc /b %BUILDDIR%\1rcc.exe %BUILDDIR%\2rcc.exe
Comparing files %BUILDDIR%\1rcc.exe and %BUILDDIR%\2RCC.EXE
00000088: B4 D5</pre>
    </blockquote>
    <p>This command builds <code>rcc</code> twice; once using the <code>rcc</code> built by VC
    and again using the <code>rcc</code> built by <code>lcc</code>. The resulting binaries are
    compared using <code>fc</code>. They should be identical, except for one or two bytes of
    timestamp data, as shown at the end of the output above (which will be 
    different on your system). If <code>1rcc.exe</code> and <code>2rcc.exe</code> aren't 
    identical, our compiler is
    generating incorrect code; <a HREF="#bugs">contact</a> us.</p>
  </li>
  <li>Copy <code>lcc.exe</code> and <code>bprint.exe</code> to a directory on your PATH, e.g.,<blockquote>
      <pre>C:\dist\lcc&gt;copy %BUILDDIR%\lcc.exe \bin
        1 file(s) copied.

C:\dist\lcc&gt;copy %BUILDDIR%\bprint.exe \bin
        1 file(s) copied.</pre>
    </blockquote>
  </li>
  <li>Finally, clean up:<blockquote>
      <pre>C:\dist\lcc&gt;nmake -f makefile.nt clean</pre>
    </blockquote>
    <p>This command removes the derived files in <code>BUILDDIR</code>, but does not remove <code>rcc.exe</code>,
    etc.; &quot;<code>nmake -f makefile.nt clobber</code>&quot; cleans up and removes all
    executables and libraries. Test directories under <code>BUILDDIR</code> are <em>not</em>
    removed; you'll need to remove these by hand, e.g.,</p>
    <blockquote>
      <pre>C:\dist\lcc&gt;rmdir %BUILDDIR%\x86 /s
%BUILDDIR%\x86, Are you sure (Y/N)? y</pre>
    </blockquote>
  </li>
</ol>

<h2><a NAME="bugs">Reporting Bugs</a></h2>

<p>lcc is a large, complex program. We find and repair errors routinely. If you think that
you've found a error, follow the steps below, which are adapted from the instructions in
Chapter 1 of <cite>A Retargetable C Compiler: Design and Implementation</cite>. 

<ol>
  <li>If you don't have a source file that displays the error, create one. Most errors are
    exposed when programmers try to compile a program they think is valid, so you probably
    have a demonstration program already.</li>
  <li>Preprocess the source file and capture the preprocessor output. Discard the original
    code.</li>
  <li>Prune your source code until it can be pruned no more without sending the error into
    hiding. We prune most error demonstrations to fewer than five lines.</li>
  <li>Confirm that the source file displays the error with the <em>distributed</em> version of
    lcc. If you've changed lcc and the error appears only in your version, then you'll have to
    chase the error yourself, even if it turns out to be our fault, because we can't work on
    your code.</li>
  <li>Annotate your code with comments that explain why you think that lcc is 
  wrong. If lcc dies with an assertion failure, please tell us where it died. If 
  lcc crashes, please report the last part of the call chain if you can. If lcc 
  is rejecting a program you think is valid, please tell us why you think it's 
  valid, and include supporting page numbers in the ANSI Standard or the
    appropriate section in <cite>C: A Reference Manual</cite>, 4th edition by S. B. Harbison
    and G. L. Steele, Jr. (Prentice Hall, 1995). If lcc silently generates incorrect code for
    some construct, please include the corrupt assembly code in the comments and flag the
    incorrect instructions if you can.</li>
  <li>Confirm that your error hasn't been fixed already. The latest version of lcc is always
    available for anonymous <code>ftp</code> from <code>ftp.cs.princeton.edu</code> in <a
    HREF="ftp://ftp.cs.princeton.edu/pub/lcc"><code>pub/lcc</code></a>. A <a
    HREF="ftp://ftp.cs.princeton.edu/pub/lcc/README"><code>README</code></a> file there gives
    acquisition details, and the <a HREF="../LOG"><code>LOG</code></a> file reports what errors
    were fixed and when they were fixed. If you report a error that's been fixed, you might
    get a canned reply.</li>
  <li>Post your program to the newsgroup <a href="news:comp.compilers.lcc"><code>comp.compilers.lcc</code></a> 
  using a USENET newsreader like those at <a href="http://www.dejanews.com/">http://www.dejanews.com/</a> 
  and <a href="http://groups.google.com/">http://groups.google.com/</a>.
    Please post only valid C programs; put all remarks in C comments so that we can process
    reports semi automatically.</li>
</ol>

<h2><a NAME="mailinglist">Keeping in Touch</a></h2>

<p>The USENET newsgroup <a href="news:comp.compilers.lcc">comp.compilers.lcc</a> is an
unmoderated newsgroup that serves as a forum for all topics related to the installation,
use, and development of lcc. You can post messages to comp.compilers.lcc using any USENET
newsreader or by visiting <a href="http://www.dejanews.com/">http://www.dejanews.com/</a>,
which also includes an archive of recent postings.</p>

<hr>

<address>
  <a HREF="http://www.research.microsoft.com/~cwfraser/">Chris Fraser</a> / <a
  HREF="mailto:[e-mail]">[e-mail]</a><br>
  <a HREF="http://www.research.microsoft.com/~drh/">David Hanson</a> / <a
  HREF="mailto:[e-mail]">[e-mail]</a><br>
  $Revision: 1.45 $ $Date: 2002/09/04 18:33:24 $ 
</address>
</body>
</html>