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

• A C compiler is required.

  • For GNU/Linux
    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.

  • For BSDs
    clang is the default C compiler on BSDs - also works fine.

  • For macOS
    clang is the default C compiler under macOS. If macOS complains no C compiler was installed while OCaml is building, please run command xcode-select --install to install command-line tools and required libraries and header files.

  • For other Unix-like systems
    It is recommended to use gcc or clang instead of the C compiler provided by the vendor of the system.

  • For Windows
    To produce native Windows executables from OCaml sources, you need to use the MSVC or MinGW-w64 ports of OCaml, described in file README.win32.adoc.
    For a more Unix-like experience, you can use WSL, the Windows Subsystem for Linux, or the Cygwin environment. You will need the GCC compiler (package gcc-core or gcc).

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

• The zstd library is used for compression of marshaled data. The option --without-zstd may be passed to configure in order to disable it.

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

• Binutils including ar and strip are required if your distribution does not already provide them with the C compiler.

From the top directory, do:

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:

Some options or variables like LDLIBS 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=i686-linux-gnu

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

• For Solaris/Illumos on SPARC machines with Sun PRO compiler only 64-bit bytecode target is supported (32-bit fails due to alignment issues; the optimization is preset to -O4 for inlining):

  ./configure CC="cc -m64"

  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.

From the top directory, do:

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

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

You can now install the OCaml system. This will create the following commands (in the binary directory selected during autoconfiguration):

From the top directory, become superuser and do:

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

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.

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 Makefile.build_config). 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.

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

• In the unlikely case that a platform does not offer all C99 float operations that the runtime needs, a configuration error will result. Users can work around this problem by calling configure with the flag --enable-imprecise-c99-float-ops. This will enable simple but potentially imprecise implementations of C99 float operations. Users with exacting requirements for mathematical accuracy, numerical precision, and proper handling of mathematical corner cases and error conditions may need to consider running their code on a platform with better C99 support.

A cross compiler is a compiler that runs on some machine, named the host, but generates code for a different machine, named the target. To build a cross compiler you first need to have a non-cross compiler of the same version installed in your $PATH. You can install that standard non-cross compiler by any means, for instance using opam or compiling it manually from source. Note though that the version of the non-cross compiler must match the version of the cross compiler since the cross compiler will be compiled by the non-cross compiler: the cross compiler will combine code compiled from source with the non-cross runtime (the build of the cross compiler will build only the runtime for the target machine).

To start the build of the cross compiler, call configure with the target triplet, possibly setting where the library will be installed on the target by setting the TARGET_LIBDIR variable. For instance, with the GCC MinGW cross compiler installed, one may use:

Notes:

• It is advisable to choose a prefix that will not end up in installing the cross compiler in your $PATH: ocamlopt should always invoke the standard non-cross compiler, not the cross one. To call the cross compiler, you will just use its full path or add temporarily its installation directory to your $PATH.

• The cross compiler to Windows needs flexdll to link the binaries. A simple way to get it is to use the flexdll submodule (git submodule update --init if needed) and let the crossopt target bootstrap flexdll.

Using the cross compiler

cross/bin/ocamlopt.opt -o test test.ml

ln -s flexlink.exe cross/bin/flexlink
(export PATH="$PWD/cross/bin:$PATH"; ocamlopt.opt.exe -o test.exe test.ml)