ocaml/INSTALL.adoc

= Installing OCaml on a Unix machine =

== PREREQUISITES

* 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, OS X, and many other systems.

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

* Under HP/UX, the GNU C Compiler (gcc), the GNU Assembler (gas), and GNU Make
  are all *required*.  The vendor-provided compiler, assembler and make tools
  have major problems.

== INSTALLATION INSTRUCTIONS

1. Configure the system. From the top directory, do:

        ./configure
+
This generates the three configuration files `Makefile`, `m.h` and `s.h`
in the `config/` subdirectory.
+
The `configure` script accepts the following options:
+
`-prefix <dir>`::                   (default: `/usr/local`)
        Set the `PREFIX` variable used to define the defaults of the following
        three options.  Must be an absolute path name.

`-bindir <dir>`::                   (default: `$(PREFIX)/bin`)
        Directory where the binaries will be installed.  Must be an absolute
        path name, or start with `$(PREFIX)`.

`-libdir <dir>`::                   (default: `$(PREFIX)/lib/ocaml`)
        Directory where the OCaml library will be installed.  Must be an
        absolute path name, or start with `$(PREFIX)`.

`-mandir <dir>`::                   (default: `$(PREFIX)/man/man1`)
        Directory where the manual pages will be installed.  Must be an absolute
        path name, or start with `$(PREFIX)`.

`-cc <C compiler and options>`::    (default: `gcc` if found, otherwise `cc`)
        C compiler to use for building the system.

`-libs <extra libraries>`::         (default: none)
        Extra libraries to link with the system.

`-no-curses`::
        Do not use the curses library.

`-host <hosttype>`::                (default: determined automatically)
        The type of the host machine, in GNU's "configuration name" format
        (CPU-COMPANY-SYSTEM or CPU-COMPANY-KERNEL-SYSTEM).  This info is
        generally determined automatically by the `configure` script, and rarely
        ever needs to be provided by hand.  The installation instructions for
        GCC or GNU Emacs contain a complete list of configuration names.

`-target <targettype>`::            (default: same as `-host`)
        The type of the target machine, in GNU's "configuration name" format
        (CPU-COMPANY-SYSTEM or CPU-COMPANY-KERNEL-SYSTEM). Setting this will
        setup OCaml as a cross-compiler which runs on `$host` and produces code
        for `$target`. This requires a C toolchain which also produces code for
        `$target` and a native OCaml compiler of the exact same version (if you
        want a cross 4.00.1, you need a native 4.00.1).

`-x11include <include_dir>`::       (default: determined automatically)
`-x11lib <lib_dir>`::               (default: determined automatically)
        Location of the X11 include directory (e.g. `/usr/X11R6/include`) and
        the X11 library directory (e.g. `/usr/X11R6/lib`).

`-no-pthread`::
        Do not attempt to use POSIX threads.

`-with-pthread`::
        Attempt to use POSIX threads (this is the default).

`-no-shared-libs`::
        Do not configure support for shared libraries.

`-dldefs <cpp flags>`::
`-dllibs <flags and libraries>`::
        These options specify where to find the libraries for dynamic linking
        (i.e. use of shared libraries).  `-dldefs` specifies options for finding
        the header files, and `-dllibs` for finding the C libraries.

`-as <assembler and options>`::     (default: determined automatically)
        The assembler to use for assembling ocamlopt-generated code.

`-aspp <assembler and options>`::   (default: determined automatically)
        The assembler to use for assembling the parts of the run-time system
        manually written in assembly language. This assembler must pre-process
        its input with the C preprocessor.

`-with-debug-runtime`::
        Compile and install the debug version of the runtimes, useful for
        debugging C stubs and other low-level code.

`-with-instrumented-runtime`::
        Compile and install the instrumented version of the runtimes, useful
        mainly for fine-tuning the GC.  Works only on Linux.

`-verbose`::
        Verbose output of the configuration tests.  Use it if the outcome of
        `configure` is not what you were expecting.

`-no-debugger`::
        Do not build `ocamldebug`.

`-no-native-compiler`::
        Do not build the native compiler -- bytecode compilation only.

`-no-ocamldoc`::
        Do not build `ocamldoc`.

`-no-ocamlbuild`::
        Deprecated since 4.03.0, as `ocamlbuild` is now distributed separately
        from the compiler distribution.

`-no-graph`::
        Do not compile the Graphics library.

`-partialld <linker and options>`:: (default: determined automatically)
        The linker and options to use for producing an object file (rather than
        an executable) from several other object files.

`-no-cfi`::
        Do not compile support for CFI directives.
+
Examples:

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


* Installation in `/usr`, man pages in section "l":

    ./configure -bindir /usr/bin -libdir /usr/lib/ocaml -mandir /usr/man/manl
+
or:

    ./configure -prefix /usr -mandir '$(PREFIX)/man/manl'

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

    ./configure -cc "gcc -m32" -as "as --32" -aspp "gcc -m32 -c" \
                -host i386-linux -partialld "ld -r -melf_i386"

* On a Linux x86-64 host, to build the run-time system in PIC mode, no special
  options should be required -- the libraries should be built automatically.
  The old instructions were:

    ./configure -cc "gcc -fPIC" -aspp "gcc -c -fPIC"
+
On a 64-bit POWER architecture host running Linux, OCaml only operates in a
  32-bit environment.  If your system compiler is configured as 32-bit, e.g.
  Red Hat 5.9, you don't need to do anything special.  If that is not the case
  (e.g. Red Hat 6.4), then IBM's "Advance Toolchain" can be used.  For example:

    export PATH=/opt/at7.0/bin:$PATH
    ./configure -cc "gcc -m32" -as "as -a32" -aspp "gcc -m32 -c" \
      -partialld "ld -r -m elf32ppc"

* On a OS X 10.5/Intel Core 2 or OS X 10.5/PowerPC host, to build a 64-bit
  version of OCaml:

    ./configure -cc "gcc -m64"

* On OS X Intel, to build a 32-bit version of OCaml:

    ./configure -host "i386-apple-darwin13.2.0" -cc "gcc -arch i386 -m32" \
      -as "as -arch i386" -aspp "gcc -arch i386 -m32 -c"

* For Sun Solaris with the `acc` compiler:

    ./configure -cc "acc -fast" -libs "-lucb"

* For Sun Solaris on Sparc 64bit, to compile natively (32bit only)

    ./configure -cc "gcc -m32" -as "as -32" -aspp "gcc -m32 -c"

* For AIX 4.3 with the IBM compiler `xlc`:

    ./configure -cc "xlc_r -D_AIX43 -Wl,-bexpall,-brtl -qmaxmem=8192"
+
If something goes wrong during the automatic configuration, or if the generated
files cause errors later on, then look at the template files:

        config/Makefile-templ
        config/m-templ.h
        config/s-templ.h
+
for guidance on how to edit the generated files by hand.

2. From the top directory, do:

        make world
+
This builds the OCaml bytecode compiler for the first time.  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

3. (Optional) To be sure everything works well, you can try to bootstrap the
   system -- that is, to recompile all OCaml 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
+
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 system has been correctly
compiled. Otherwise, this does not necessarily mean 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 fix-point.

4. If your platform is supported by the native-code compiler (as reported during
   the auto-configuration), you can now build the native-code compiler.  From
   the top directory, do:

        make opt
+
or:

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

5. anchor:step-5[] Compile fast versions of the OCaml compilers, by compiling
   them with the native-code compiler (you will have only compiled them to
   bytecode in steps 2-4).  Just do:

        make opt.opt
+
Later, you can compile your programs to bytecode using ocamlc.opt instead of
ocamlc, and to native-code using ocamlopt.opt instead of ocamlopt.  The ".opt"
compilers should run faster than the normal compilers, especially on large input
files, but they may take longer to start due to increased code size.  If
compilation times are an issue on your programs, try the ".opt" compilers to see
if they make a significant difference.
+
An alternative, and faster approach to steps 2 to 5 is

        make world.opt          # to build using native-code compilers
+
The result is equivalent to `make world opt opt.opt`, but this may fail if
anything goes wrong in native-code generation.

6. 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
|===============================================================================
+
and also, if you built them during <<step-5,step 5>>: `ocamlc.opt`,
`ocamlopt.opt`, `ocamllex.opt`, `ocamldep.opt` and `ocamldoc.opt`
+
From the top directory, become superuser and do:

        umask 022       # make sure to give read & execute permission to all
        make install

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

        make clean

8. (Optional) The `emacs/` subdirectory contains Emacs-Lisp files for an OCaml
   editing mode and an interface for the debugger.  To install these files,
   change to the `emacs/` subdirectory and do:

        make EMACSDIR=<directory where to install the files> install
+
or

        make install
+
In the latter case, the destination directory defaults to the
`site-lisp` directory of your Emacs installation.

9. After installation, do *not* strip the `ocamldebug` and `ocamlbrowser`
   executables. These are mixed-mode executables (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 `config/`. Wrong endian-ness 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 4M.

Try recompiling the runtime system with optimizations turned off (change
`CFLAGS` in `byterun/Makefile` and `asmrun/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 build a debug version of the runtime system. Go to the `byterun/`
directory and do `make ocamlrund`.  Then, copy `ocamlrund` to
`../boot/ocamlrun`, 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

* The Makefiles do not support parallel make (e.g. make -j2).
Fix: do not pass the -j option to make, and be patient.

* The Makefiles use the `include` directive, which is not supported by all
  versions of make. Use GNU Make if this is a problem.

* Solaris make mishandles a space in our Makefiles, so you have to use GNU make
  to build on Solaris.

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

* GCC 2.7.2.1 generates incorrect code for the runtime system in `-O` mode on
  some Intel x86 platforms (e.g. Linux RedHat 4.1 and 4.2). If this causes a
  problem, the solution is to upgrade to 2.7.2.3 or above.

* Some versions of GCC 2.96 for the Intel x86 (as found in RedHat 7.2,
  Mandrake 8.0 and Mandrake 8.1) generate incorrect code for the runtime system.
  The `configure` script tries to work around this problem.

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

* Under OS X 10.6, with XCode 4.0.2, the `configure` script mistakenly detects
  support for CFI directives in the assembler. Fix: give the `-no-cfi` option to
  `configure`.