forked from colinbenner/ocaml-llvm
/
INSTALL
330 lines (240 loc) · 12.9 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
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, MacOS X,
and many other systems.
* Under MacOS X 10.5, you need version 3.1 or later of the XCode
development tools. The version of XCode found on MacOS X 10.5
installation media causes linking problems. XCode updates
are available free of charge at http://developer.apple.com/tools/xcode/
* Under MacOS X up to version 10.2.8, you must raise the limit on the
stack size with one of the following commands:
limit stacksize 64M # if your shell is zsh or tcsh
ulimit -s 65536 # if your shell is bash
* 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
have major problems.
* GNU make is needed to build ocamlbuild and camlp4. If your system's
default make is not GNU make, you need to define the GNUMAKE environment
variable to the name of GNU make, typically with this command:
export GNUMAKE=gnumake
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:
-bindir <dir> (default: /usr/local/bin)
Directory where the binaries will be installed
-libdir <dir> (default: /usr/local/lib/ocaml)
Directory where the Caml library will be installed
-mandir <dir> (default: /usr/local/man/man1)
Directory where the manual pages will be installed
-prefix <dir> (default: /usr/local)
Set bindir, libdir and mandir to
<dir>/bin, <dir>/lib/ocaml, <dir>/man/man1 respectively.
-cc <C compiler and options> (default: gcc if available, cc otherwise)
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). 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 emacs contain a complete list of configuration names.
-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).
-tkdefs <cpp flags> (default: none)
-tklibs <flags and libraries> (default: determined automatically)
These options specify where to find the Tcl/Tk libraries for
LablTk. "-tkdefs" helps to find the headers, and "-tklibs"
the C libraries. "-tklibs" may contain either only -L/path and
-Wl,... flags, in which case the library names are determined
automatically, or the actual libraries, which are used as given.
Example: for a Japanese tcl/tk whose headers are in specific
directories and libraries in /usr/local/lib, you can use
./configure -tklibs "-L/usr/local/lib -ltk8.0jp -ltcl8.0jp"
-tkdefs "-I/usr/local/include/tcl8.0jp -I/usr/local/include/tk8.0jp"
-tk-no-x11
Build LablTk without using X11. This option is needed on Cygwin.
-no-tk
Do not attempt to build LablTk.
-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 preprocess 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.
-verbose
Verbose output of the configuration tests. Use it if the outcome
of configure is not what you were expecting.
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
On a MacOSX 10.5/Intel Core 2 or MacOSX 10.5/PowerPC host,
to build a 64-bit version of OCaml:
./configure -cc "gcc -m64"
On a MacOSX 10.6/Intel Core 2, to build a 32-bit version of OCaml:
./configure -cc "gcc -m32" -as "as -arch i386" -aspp "gcc -m32 -c"
On a Linux x86/64 bits host, to build a 32-bit version of OCaml:
./configure -cc "gcc -m32" -as "as --32" -aspp "gcc -m32 -c"
On a Linux x86/64 bits host, to build the run-time system in PIC mode
(enables putting the runtime in a shared library,
at a small performance cost):
./configure -cc "gcc -fPIC" -aspp "gcc -c -fPIC"
For Sun Solaris with the "acc" compiler:
./configure -cc "acc -fast" -libs "-lucb"
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 fixpoint.
4- If your platform is supported by the native-code compiler (as
reported during the autoconfiguration), 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- Compile fast versions of the OCaml compilers, by compiling them
with the native-code compiler (you have only compiled them to bytecode
so far). 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):
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 Caml code
ocamldebug the source-level replay debugger
ocamldep generator of "make" dependencies for Caml sources
ocamldoc documentation generator
ocamlprof execution count profiler
ocamlcp the bytecode compiler in profiling mode
and also, if you built them during step 5,
ocamlc.opt the batch bytecode compiler compiled with ocamlopt
ocamlopt.opt the batch native-code compiler compiled with ocamlopt
ocamllex.opt the lexer generator compiled with ocamlopt
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 Caml bytecode; 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 endianness 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
that 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.
* 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) generates 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.