ocaml/INSTALL.adoc

= Installing OCaml from sources on a Unix(-like) machine =

== Prerequisites

* A C Compiler is required.
  The GNU C Compiler (`gcc`) is recommended as the bytecode interpreter takes
  advantage of GCC-specific features to enhance performance. gcc is the standard
  compiler under Linux and many other systems.
  However `clang` - used in Mac OS, BSDs and others - also works fine.

* GNU `make`, as well as POSIX-compatible `awk` and `sed` are required.

* A POSIX-compatible `diff` is necessary to run the test suite.

* If you do not have write access to `/tmp`, you should set the environment
  variable `TMPDIR` to the name of some other temporary directory.

== Prerequisites (special cases)

* Under Cygwin, the `gcc-core` package is required. `flexdll` is also necessary
  for shared library support.

== Configuration

From the top directory, do:

        ./configure
+
This generates the three configuration files `Makefile.config`,
`runtime/caml/m.h` and `runtime/caml/s.h`.
+
The `configure` script accepts options that can be discovered by running:

        ./configure --help
+
Some options or variables like (LDFLAGS) may not be taken into account
by the OCaml build system at the moment. Please report an issue if you
discover such a variable or option and this causes troubles to you.
+
Examples:

* Standard installation in `/usr/{bin,lib,man}` instead of `/usr/local`:
    ./configure --prefix=/usr


* On a Linux x86-64 host, to build a 32-bit version of OCaml:

    ./configure --build=x86_64-pc-linux-gnu --host=i386-linux \
                CC='gcc -m32' AS='as --32' ASPP='gcc -m32 -c' \
                PARTIALLD='ld -r -melf_i386'

* For AIX 7.x with the IBM compiler `xlc`:

    ./configure CC=xlc
+
By default, build is 32-bit. For 64-bit build, please set environment variable `OBJECT_MODE=64`
  for _both_ `configure` and `make world` phases. Note, if this variable is set for only one phase,
  your build will break (`ocamlrun` segfaults).
+
If something goes wrong during the automatic configuration, or if the generated
files cause errors later on, then look at the template files:

        Makefile.config.in
        Makefile.build_config.in
        runtime/caml/m.h.in
        runtime/caml/s.h.in
+
for guidance on how to edit the generated files by hand.

== Building the compiler

From the top directory, do:

        make

This builds the OCaml compiler for the first time.  This phase is
fairly verbose; consider redirecting the output to a file:

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

== (Optional) Running the testsuite

To be sure everything works well, you can run the test suite
   that comes with the compiler. To do so, do:

        make tests

== Installing the compiler

You can now install the OCaml system. This will create the following commands
   (in the binary directory selected during autoconfiguration):
+
[width="70%",frame="topbot",cols="25%,75%"]
|===============================================================================
| `ocamlc`     | the batch bytecode compiler
| `ocamlopt`   | the batch native-code compiler (if supported)
| `ocamlrun`   | the runtime system for the bytecode compiler
| `ocamlyacc`  | the parser generator
| `ocamllex`   | the lexer generator
| `ocaml`      | the interactive, toplevel-based system
| `ocamlmktop` | a tool to make toplevel systems that integrate user-defined C
                 primitives and OCaml code
| `ocamldebug` | the source-level replay debugger
| `ocamldep`   | generator of "make" dependencies for OCaml sources
| `ocamldoc`   | the documentation generator
| `ocamlprof`  | the execution count profiler
| `ocamlcp`    | the bytecode compiler in profiling mode
|===============================================================================
+
From the top directory, become superuser and do:

        make install

Installation is complete. Time to clean up. From the toplevel directory,
   do:

        make clean

After installation, do *not* strip the `ocamldebug` executables.
   This is a mixed-mode executable (containing both compiled C
   code and OCaml bytecode) and stripping erases the bytecode!  Other
   executables such as `ocamlrun` can safely be stripped.

== 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 `runtime/caml/`.
Wrong endianness or alignment constraints in `machine.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 4M.

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

You can also use the debug version of the runtime system which is
normally built and installed by default. Run the bytecode program
that causes troubles with `ocamlrund` rather than with `ocamlrun`.
This version of the runtime system contains lots of assertions
and sanity checks that could help you pinpoint the problem.

== Common problems

* The Makefiles assume that make executes 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`.

* On some systems, localization causes build problems.  You should try to set
  the C locale (`export LC_ALL=C`) before compiling if you have strange errors
  while compiling OCaml.

* 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). Fix: use `gcc`.