
               INSTALLING CAML LIGHT ON A UNIX SYSTEM


1- Edit the file src/Makefile. Change the variable definitions at
the beginning of the Makefile, to indicate which C compiler to use,
and where to install files. See the machine-specific hints at the end
of this file.

2- Configure the system. In the src/ subdirectory, do:

        make configure

This generates the two configuration files "m.h" and "s.h" in the
config/ subdirectory.  If something goes wrong during the make,
or if the generated "m.h" and "s.h" files cause errors later on, then
change to the config/ subdirectory, do

        cp m-templ.h m.h
        cp s-templ.h s.h

and edit "m.h" and "s.h" by hand, following the guidelines in the
comments.

3- From the src/ subdirectory, do:

        make world

This builds all components of Caml Light for the first time. It takes
from about two minutes on a Dec Alpha or HP Snake to more than one hour on
cheap 386 boxes. The "make" ends up with a little self-test. Don't
forget to check the results, as indicated. This phase is fairly
verbose; consider redirecting the output to a file:

        make world > log.world 2>&1     # in sh
        make world >& log.world         # in csh

4- To be sure everything works well, you can try to bootstrap the
system --- that is, to recompile all Caml Light sources with the newly
created compiler. From the src/ subdirectory, do:

        make bootstrap

or, better:

        make bootstrap > log.bootstrap 2>&1     # in sh
        make bootstrap >& log.bootstrap         # in csh

This takes slightly less time than the "make world" phase. The "make
bootstrap" checks that the bytecode programs compiled with the new
compiler are identical to the bytecode programs compiled with the old
compiler. If this is the case, you can be pretty sure the Caml Light
system has been correctly compiled. Otherwise, this does not
necessarily means something went wrong. The best thing to do is to try
a second bootstrapping phase: just do "make bootstrap" again.  It will
either crash almost immediately, or re-re-compile everything correctly
and reach the fixpoint.

5- You can now install the Caml Light system. This will create the
following commands (in the directory set to BINDIR in src/Makefile):

        camllight       the interactive, toplevel-based system
        camlc           the batch compiler
        camlrun         the runtime system
        camlyacc        the parser generator
        camllex         the lexer generator
        camlmktop       a tool to make toplevel systems that integrate
                        user-defined C primitives

From the src/ directory, become superuser and do "make install".

6- The directory where camlrun resides must be in the PATH variable
for camlc and camllight to work properly. (Actually, camlc and
camllight are shell-scripts that call "camlrun" on various
bytecode files.) Hence, if you have installed camlrun in a
non-standard directory, be careful to add it to the PATH variable
before running camlc or camllight.

7- The contrib/ directory contains libraries (Unix system calls,
X-windows interface, portable graphics, arbitrary-precision rational
arithmetic) and tools (TeX interface, "tags" utility) that may be of
interest to you.  Look into the subdirectories of contrib/, and follow
the installation instructions there.


IF SOMETHING GOES WRONG.

Check the files m.h and s.h in config/. Wrong endianness or alignment
constraints in m.h will immediately crash the bytecode interpreter.

If you get a "segmentation violation" signal, check the limits on the
stack size and data segment size (type "limit" under csh or "ulimit
-a" under bash). 512k of stack is not enough for bootstrapping on some
platforms; raise the limit to 1M or 2M.

Try recompiling the runtime system with optimizations turned off. The
runtime system contains some complex, atypical pieces of C code that
can uncover bugs in optimizing compilers. Alternatively, try another C
compiler (e.g. gcc instead of the vendor-supplied cc).

You can also build a debug version of the runtime system. Go to the
src/runtime/ directory and do "make debug". Then, copy camlrund to
../camlrun, and try again. This version of the runtime system contains
lots of assertions and sanity checks that could help you pinpoint the
problem.


COMMON PROBLEMS

* camlc or camllight complain that camlrun cannot be found. See point
6- in the installation instructions.

* The Makefiles assume that make execute commands by calling /bin/sh. They
won't work if /bin/csh is called instead. You might have to unset the SHELL
environment variable, or set it to /bin/sh.

* You can safely ignore the following warnings:

- ar or ranlib complains that fix_code.o has no symbol table.
  It's actually empty with some configurations.

- type clashes between enumeration types and integers. This is perfectly
  correct ANSI C.


MACHINE-SPECIFIC HINTS 

* On MIPS machines from MIPS Co. Add "-systype bsd43" to OPTS.
Also, some versions of the cc compiler are reportedly unable to
compile src/runtime/interp.c ("as1: internal: unexpected opcode bcond06").
Either compile without optimizations (remove -O from CFLAGS in
src/runtime/Makefile) or use gcc.

* On some Next machines: cc pretends to be gcc but is not quite gcc.
If the compilation of src/runtime/interp.c causes syntax errors, insert
#undef __GNUC__ at the very beginning of src/runtime/interp.c.

* On SGI Indigo under IRIX 4.0. "ar" emits some warnings about multiple
definitions of global variables. Ignore them; that's just ANSI pedantism.

* On Macintoshes under A/UX with gcc. You might have to add -D_SYSV_SOURCE
to OPTS.
