Installing Objective Caml 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. Versions 2.5.8, 2.6.3, 2.7.2, 2.7.2.3, 2.95 as well as egcs versions 1.0 and 2.91 have all been tested at some point and work well. 2.7.2.1 for Intel as found in Linux/RedHat 4.1 and 4.2 has known problems; upgrade to something more recent. * 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. * Under MacOS X, before you begin, 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 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 (default: /usr/local/bin) Directory where the binaries will be installed -libdir (default: /usr/local/lib/ocaml) Directory where the Caml library will be installed -mandir (default: /usr/local/man/man1) Directory where the manual pages will be installed -prefix (default: /usr/local) Set bindir, libdir and mandir to /bin, /lib/ocaml, /man/man1 respectively. -cc (default: gcc if available, cc otherwise) C compiler to use for building the system -libs (default: none) Extra libraries to link with the system -no-curses Do not use the curses library. -host (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 (default: determined automatically) -x11lib (default: determined automatically) Location of the X11 include directory (e.g. /usr/X11R6/include) and the X11 library directory (e.g. /usr/X11R6/lib). -with-pthread Use POSIX threads for the OCaml thread library instead of the default bytecode-level threading. POSIX threads support threading with native-code programs (ocamlopt) as well as bytecode (ocamlc), and also allow more flexibility in interfacing with C. However, you need a strictly conformant POSIX 1003.1c implementation on your system. For instance, this option works under Solaris 2.5 and later, Digital Unix 4.0, and recent Linux distributions (using glibc 2). -tkdefs (default: none) -tklibs (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. -verbose Verbose output of the configuration tests. Use it if the outcome of configure is not what you were expecting. Examples: ./configure -prefix /usr/bin ./configure -bindir /usr/bin -libdir /usr/lib/ocaml -mandir /usr/man/manl ./configure -cc "acc -fast" -libs "-lucb" # For Sun Solaris with the acc compiler ./configure -cc "xlc_r -D_AIX43 -Wl,-bexpall,-brtl -qmaxmem=8192" # For AIX 4.3 with the IBM compiler 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 Objective Caml 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 Objective Caml 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- (Optional) If you want to give the native-code compiler a serious test, you can try to compile the Objective Caml compilers with the native-code compiler (they are compiled to bytecode by default). Just do: make ocamlc.opt # to build a native-code version of ocamlc make ocamlopt.opt # to build a native-code version of ocamlopt make ocamllex.opt # to build a native-code version of ocamllex or make opt.opt # to build all of them 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 Objective Caml 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 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 Objective Caml editing mode and an interface for the debugger. To install these files, change to the emacs/ subdirectory and do make EMACSDIR= 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 2M. 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 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 execute 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. * 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. * 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.