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
about two minutes on a modern workstation. 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- Now that the Caml Light compiler is installed, you can compile the
tools and libraries contained in the contrib/ directory: source-level
replay debugger, X Windows user interface toolkit, "tags" program for
Emacs, arbitrary-precision rational arithmetic, Unix system calls
interface, etc. The file contrib/INDEX gives a short description of
the packages contained in contrib/ (what they do, what they require).
The subdirectories of contrib/ also contain more information in README
and INSTALL files.  Read the descriptions and choose which packages
you need.

8- Edit the file contrib/Makefile to indicate which packages to
install, which C compiler to use, where to find external libraries on
your system, and where to install files.  It is highly recommended to
use the same C compiler used to compile the core system (the one
specified in src/Makefile).

9- Make sure you have not erased any of the files in src/ that have
been generated during the compilation of the core system.  If you
have, recompile the core system (step 3- above).

10- From the contrib/ subdirectory, do:

        make all

or, better,

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

11- You can now install the packages.  From the contrib/ directory,
become superuser and do "make install".

12- Installation is complete. Time to clean up.

        (cd src; make clean)
        (cd contrib; make clean)


IF SOMETHING GOES WRONG:

Read the "common problems" and "machine-specific hints" section at the
end of this file.

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). Make sure the limit on the stack size is
at least 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 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.

If something goes wrong during the compilation of one of the packages
in contrib/, check the README and INSTALL files in the corresponding
directory for hints. If you really can't get one of the packages to
compile, remove it from the PACKAGES variable in contrib/Makefile and
go ahead with the others.


COMMON PROBLEMS:

* camlc or camllight complain that camlrun cannot be found. Make sure
that the directory containing camlrun is in your PATH (see point 6- above).

* The Makefiles assume that make execute commands by calling /bin/sh. They
won't work if /bin/csh is called instead. You may 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.

* gcc 2.6.0 has been reported to generate incorrect code for the
runtime system in -O mode. Upgrade to 2.7.2 or turn -O off.

MACHINE-SPECIFIC HINTS:

* On HP 9000/700 machines under HP/UX 9.  Some versions of cc are
unable to compile correctly the runtime system (wrong code is
generated for (x - y) where x is a pointer and y an integer). This
causes "make world" to crash when compiling in src/lib.  Fix: use
another C compiler (gcc works fine).

* On DECstations 3000 under OSF1 3.0: "make configure" hangs while
testing asynchronous I/O. This may even hang your login shell as well.
Apparently, asynchronous I/O are severely buggy in the 3.0 kernel.
Fix: comment out lines 287-290 in config/autoconf and run "make configure"
again.

* On older versions of Linux, it has been reported that sed has a
non-standard syntax for scripts that causes some of the sed-scripts in
src/runtime/Makefile and src/linker/Makefile to fail during "make world".
(We did not experience this problem with the versions of Linux we
use.) You'll have to adapt the sed scripts, then do "make clean", then
do "make world" again. It is crucial to do "make clean", otherwise
incorrectly generated files will remain.

* 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 OPTS in
src/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/misc.h.

* 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. It may be necessary to add
-D_SYSV_SOURCE to OPTS.