INSTALL

                          Building Quick C--

This document describes how to build Quick C-- from source.

Prerequisites
~~~~~~~~~~~~~

The compiler is written in the functional programming language
Objective Caml (http://caml.inria.fr). Most of the source code is
written as a literate program using the Noweb literate programming
tool.  The documentation is intended to be formatted with LaTeX.  
The build process is controlled by mk, a version of Make.  Mk was
originally written by Andrew Hume at Bell Labs, became the build tool
of the Plan 9 operating system, and then was released to the world as
part of Inferno.  We provide a version of mk derived from the Inferno
distribution. If you are using old versions of mk from Unix v7 or
similar, you will need to upgrade.

To build the compiler from source code you need:

        * Objective Caml version 3.08 (including ocamlyacc and ocamllex)
          or higher.
          [version 3.07 will work if you change names of external functions]
        * Noweb 2.9 or higher

The compiler comes with an interpreter implemented in C. For the
interpreter to compile you need in addition:

        * ANSI C Compiler, for example gcc
        * Lua 4.0 installed, including library and header files

Some source files are generated by tools that are not included in the
distribution. You can compile the generated sources, but you cannot
change the specification that led to them, For example, the abstract
syntax for C-- is specified in ASDL. We provide the library files in
asdl/ and generated sources in gen/ such that you do not need the ASDL
generator. However, we do not provide the generator which means there is
no way to re-compile the ASDL specification. 

Building Mk
~~~~~~~~~~~

Before you can build anything else, you must build mk.  You will find
instructions in mk/README.  Once you have built mk, put it on your PATH.


Building QC--
~~~~~~~~~~~~~

The recursive build process is controlled by mkfiles for mk(1). All
mkfiles include files from config/ to find tools and libraries. It
should suffice to make changes only here, if at all. The file that most
likely needs some attention is config/lua.mk. It defines the path the
Lua libraries and header files. We provide a configure script that tries
to guess platform-dependent settings such that you hopefully don't need
to edit configuration files manually.

        config/ocaml.mk         The OCaml compiler suite
        config/noweb.mk         Noweb literate programming syste,
        config/latex.mk         LaTeX for documentation
        config/man.mk           Creating manual pages with perlpod(1)
        config/c.mk             Compiling C code
        config/lua.mk           Library and header files for Lua
        config/config.mk        ./configure-generated file
        mkfile                  top-level mkfile

To compile everything, run configure and mk:

        ./configure
	mk timestamps # needed if direct from CVS repository
        mk all all.opt
	mk install install.opt

If Objective Caml cannot build a native-code binary on your platform,
you should omit the all.opt and install.opt targets.

If you don't have rights to install into /usr/local, you will need to use 

        ./configure --prefix=...

If ./configure fails it will suggest what to try; it also writes
helpful output into a configure.log file. The file it creates is
config/config.mk. You can create this file manually from
config/config.mk.default.

The invocation of mk starts the compilation process.  The first time
through, you will see quite a few warnings of the form

  warning: skipping missing include file: DEPEND: No such file or directory

These warnings are normal and should not trouble you.

Mk produces (at least) the following files:

        bin/qc--                    qc-- byte code code binary 
        bin/qc--interp              qc-- interpreter
        man/man1/qc--.1             manual page
        man/man1/qc--internals.1    hacker's manual page

There are more binaries and manual pages that are used during
development but they are not important to use qc--.
        
If the OCaml native-code compiler ocamlopt is supported in your
platform and is installed, we strongly recommend that you create a
native-code binary qc--.opt:

        mk all.opt
	mk install.opt

To execute the test suite you can also call the test and/oror test.opt
targets:

        mk test test.opt

As of November, 2004, you can expect one failure: the 'wf.test' in the
'tiger.x86.tst' suite does not work correctly.  We believe this error
indicates a fault in the C-- run-time system, but we have not yet been
able to track it down.

Under '# operator testing on random bits' you can expect such messages as
  integer widening not tested
  effect of rounding modes not tested
as well as a list of operators not implemented, if any.  These
messages are normal and do not indicate a fault.




Problems and Bug Reports
~~~~~~~~~~~~~~~~~~~~~~~~

If you have trouble building the compiler or using it, send email to
bugs@cminusminus.org.  You can view the status of bug reports at
http://www.cminusminus.org/qc--bugs.  If either this email or this URL 
fails, please send a letter of complaint to nr@eecs.harvard.edu with a 
copy to help@eecs.harvard.edu.


How the Compiler's Source Code is Organized
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can use the compiler without any of the following information, but
if you want to hack on the compiler, this information may help.

The source code of the compiler is split into different directories. 
The top level mkfile knows the dependencies between them and makes
them in the right order.  Files shared by many directories go into the
lib/ directory which is initially empty.  Once all shared files are in
place development can be continued in the sub-directories and the
mkfiles provided there. Refer to the mkfiles for the high level
targets available in each directory. The doc/ directory includes an
overview document index.nw.

In alphabetical order:


    asdl/       OCaml sources for the runtime system of AsdlGen
                generated code.
    
    aug99/      Sources for an earlier implementation of c--. Not used
                and interesting only for historical reasons.
    
    bin/        Initially empty. Contains binary after compilation.
    
    camlburg/   A burg implementation for OCaml; comes with its own
                documentation.

    cllib/      Library of OCaml modules for pretty printing and
                and parsing.

    config/     Global rule set for compiling OCaml sources and other 
                global files.
    
    doc/        Various documents, manual pages, also an overview and design
                problems.
    
    examples/   Some c-- sources. Currently empty.
    
    figures/    PostScript figures used for documentation.

    gen/        Machine generated files. 
    
    interp/     Interpreter for C--. 

    lib/        Initially empty. Contains library modules during
                compilation.
    
    lua/        An interpreter for the embedded script language Lua.
    
    man/        Initially empty. Contains manual page after
                compilation. 

    mk/         C implementation of the make-like tool mk.

    rtl/        RTL type definition.

    runtime/    The Quick C-- run-time system

    specialized/ Partially evaluated compiler sources.

    src/        Main sources for the c-- compiler.

    tdpe/       Code for partial evaluation of the compiler, see README.
                Not yet updated for Ocaml 3.04 label mode. However, this
                code is currently by default not compiled and linked.
    
    test2/      Code for testing.

    tools/      Small tools: OCamlError, NoFake, Grades.

Directories depend on each other in the following order:

    cllib lua asdl rtl gen camlburg tools src runtime test2