1 = Installing OCaml from sources on a Unix(-like) machine =
2
3 == Prerequisites
4
5 * The GNU C Compiler (gcc) is recommended, as the bytecode interpreter takes
6 advantage of GCC-specific features to enhance performance. gcc is the standard
7 compiler under Linux, OS X, and many other systems.
8
9 * If you do not have write access to `/tmp`, you should set the environment
10 variable `TMPDIR` to the name of some other temporary directory.
11
12 * Under HP/UX, the GNU C Compiler (gcc), the GNU Assembler (gas), and GNU Make
13 are all *required*. The vendor-provided compiler, assembler and make tools
14 have major problems.
15
16 * Under Cygwin, the `gcc-core` and `make` packages are required. `flexdll` is
17 necessary for shared library support. `libX11-devel` is necessary for graph
18 library support and `libintl-devel` is necessary for the `ocamlobjinfo` tool
19 to be able to process `.cmxs` files. `diffutils` is necessary to run the test
20 suite.
21
22 == Configuration
23
24 From the top directory, do:
25
26 ./configure
27 +
28 This generates the three configuration files `Makefile.config`,
29 `runtime/caml/m.h` and `runtime/caml/s.h`.
30 +
31 The `configure` script accepts options that can be discovered by running:
32
33 ./configure --help
34 +
35 Some options or variables like (LDFLAGS) may not be taken into account
36 by the OCaml build system at the moment. Please report an issue if you
37 discover such a variable or option and this causes troubles to you.
38 +
39 Examples:
40
41 * Standard installation in `/usr/{bin,lib,man}` instead of `/usr/local`:
42 ./configure --prefix=/usr
43
44
45 * On a Linux x86-64 host, to build a 32-bit version of OCaml:
46
47 ./configure --build=x86_64-pc-linux-gnu --host=i386-linux \
48 CC='gcc -m32' AS='as --32' ASPP='gcc -m32 -c' \
49 PARTIALLD='ld -r -melf_i386'
50
51 * For AIX 7.x with the IBM compiler `xlc`:
52
53 ./configure CC=xlc
54 +
55 By default, build is 32-bit. For 64-bit build, please set environment variable `OBJECT_MODE=64`
56 for _both_ `configure` and `make world` phases. Note, if this variable is set for only one phase,
57 your build will break (`ocamlrun` segfaults).
58 +
59 If something goes wrong during the automatic configuration, or if the generated
60 files cause errors later on, then look at the template files:
61
62 Makefile.config.in
63 Makefile.common.in
64 runtime/caml/m.h.in
65 runtime/caml/s.h.in
66 +
67 for guidance on how to edit the generated files by hand.
68
69 == Building the compiler
70
71 From the top directory, do:
72
73 make
74
75 This builds the OCaml compiler for the first time. This phase is
76 fairly verbose; consider redirecting the output to a file:
77
78 make > make.log 2>&1 # in sh
79 make >& make.log # in csh
80
81 == (Optional) Running the testsuite
82
83 To be sure everything works well, you can run the test suite
84 that comes with the compiler. To do so, do:
85
86 make tests
87
88 == Installing the compiler
89
90 You can now install the OCaml system. This will create the following commands
91 (in the binary directory selected during autoconfiguration):
92 +
93 [width="70%",frame="topbot",cols="25%,75%"]
94 |===============================================================================
95 | `ocamlc` | the batch bytecode compiler
96 | `ocamlopt` | the batch native-code compiler (if supported)
97 | `ocamlrun` | the runtime system for the bytecode compiler
98 | `ocamlyacc` | the parser generator
99 | `ocamllex` | the lexer generator
100 | `ocaml` | the interactive, toplevel-based system
101 | `ocamlmktop` | a tool to make toplevel systems that integrate user-defined C
102 primitives and OCaml code
103 | `ocamldebug` | the source-level replay debugger
104 | `ocamldep` | generator of "make" dependencies for OCaml sources
105 | `ocamldoc` | the documentation generator
106 | `ocamlprof` | the execution count profiler
107 | `ocamlcp` | the bytecode compiler in profiling mode
108 |===============================================================================
109 +
110 From the top directory, become superuser and do:
111
112 make install
113
114 Installation is complete. Time to clean up. From the toplevel directory,
115 do:
116
117 make clean
118
119 After installation, do *not* strip the `ocamldebug` executables.
120 This is a mixed-mode executable (containing both compiled C
121 code and OCaml bytecode) and stripping erases the bytecode! Other
122 executables such as `ocamlrun` can safely be stripped.
123
124 == If something goes wrong
125
126 Read the "common problems" and "machine-specific hints" section at the end of
127 this file.
128
129 Check the files `m.h` and `s.h` in `runtime/caml/`.
130 Wrong endianness or alignment constraints in `machine.h` will
131 immediately crash the bytecode interpreter.
132
133 If you get a "segmentation violation" signal, check the limits on the stack size
134 and data segment size (type `limit` under csh or `ulimit -a` under bash). Make
135 sure the limit on the stack size is at least 4M.
136
137 Try recompiling the runtime system with optimizations turned off (change
138 `OC_CFLAGS` in `runtime/Makefile`). The runtime system
139 contains some complex, atypical pieces of C code which can uncover bugs in
140 optimizing compilers. Alternatively, try another C compiler (e.g. `gcc` instead
141 of the vendor-supplied `cc`).
142
143 You can also use the debug version of the runtime system which is
144 normally built and installed by default. Run the bytecode program
145 that causes troubles with `ocamlrund` rather than with `ocamlrun`.
146 This version of the runtime system contains lots of assertions
147 and sanity checks that could help you pinpoint the problem.
148
149 == Common problems
150
151 * The Makefiles assume that make executes commands by calling `/bin/sh`. They
152 won't work if `/bin/csh` is called instead. You may have to unset the `SHELL`
153 environment variable, or set it to `/bin/sh`.
154
155 * On some systems, localization causes build problems. You should try to set
156 the C locale (`export LC_ALL=C`) before compiling if you have strange errors
157 while compiling OCaml.
158
159 * On HP 9000/700 machines under HP/UX 9, some versions of `cc` are unable to
160 compile correctly the runtime system (wrong code is generated for `(x - y)`
161 where `x` is a pointer and `y` an integer). Fix: use `gcc`.
162