ocaml/INSTALL.adoc

163 lines
5.8 KiB
Plaintext

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