
               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.

2- Configure the system. In the config/ subdirectory, run

        sh autoconf

if you are going to use the standard C compiler "cc". If you are going to use
some other compiler, or add some options, give the name of the compiler as
first argument to "autoconf", as in

        sh autoconf gcc
or
        sh autoconf "cc -systype bsd43"

The "autoconf" script generates the two configuration files "m.h" and
"s.h".  If something goes wrong during the execution of "autoconf", or
if the generated "m.h" and "s.h" files cause errors later on, then 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 four minutes on a SparcStation 2 or DecStation 5000 to more than one
hour on cheap 386 or 68000 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 top directory, 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) and tools (TeX interface) 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.

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.

You can also build a debug version of the runtime system. Go to the
src/runtime/ directory and do "make camlrund". 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.

* camlc or camllight say "not enough memory for startup". If you
have an older version of Caml Light already installed, this usually
means that you're trying to execute a bytecode file compiled with Caml
Light 5 using the Caml Light runtime version 4. Since the format of
bytecode files has changed, the old runtime is confused. This can
happen if, for instance, /usr/local/bin/camlrun is the old runtime
system from version 4, you have installed the new runtime system in
/u/me/bin/camlrun, and /usr/local/bin is before /u/me/bin in your
PATH. Remove that old version 4, or clean up your PATH.

* 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:

- assignment of non-volatile pointers to/from volatile pointers, in
  interp.c and signals.c

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

* Some testers have reported problems with the awk script in
src/compiler/Makefile that generates src/compiler/opcodes.ml. Specifically,
awk reports a syntax error on line 2 and fails. Try other variants of
awk (nawk, gawk). If this does not work either, replace the lines (in
src/compiler/Makefile):

        awk '$$1=="enum" {n=0; next; } \
             {printf("let %s=%d;;\n", $$1, n++);}' > opcodes.ml
by:
        awk -f make_opcodes > opcodes.ml

and create the file src/compiler/make_opcodes with the two lines:

$1=="enum" {n=0; next; }
           {printf("let %s=%d;;\n", $1, n++);}


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 runtime/interp.c ("as1: internal: unexpected opcode bcond06").
Either compile without optimizations (remove -O from CFLAGS_OPTI), or
use gcc.

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

* 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 HP 9000/700 under OSF1 1.0. "cc" emits some warnings about
``Attempt to load or store a byte-aligned longword''. That's simply not true;
ignore the warnings (and pray that their optimizer is not too buggy).
