diff options
Diffstat (limited to 'INSTALL.adoc')
| -rw-r--r-- | INSTALL.adoc | 413 |
1 files changed, 204 insertions, 209 deletions
diff --git a/INSTALL.adoc b/INSTALL.adoc index aaee76f3f9..cdea168dac 100644 --- a/INSTALL.adoc +++ b/INSTALL.adoc @@ -1,143 +1,145 @@ -= Installing OCaml on a Unix machine = += Installing OCaml on a Unix(-like) 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. +* 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, OS X, and many other systems. -* If you do not have write access to /tmp, you should set the environment - variable TMPDIR to the name of some other temporary directory. +* 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 +* 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 tools have major problems. +* Under Cygwin, the `gcc-core` and `make` packages are required. `flexdll` is + necessary for shared library support. `libX11-devel` is necessary for graph + library support and `libintl-devel` is necessary for the `ocamlobjinfo` tool + to be able to process `.cmxs` files. `diffutils` is necessary to run the test + suite. + == 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. +This generates the three configuration files `Makefile`, `m.h` and `s.h` +in the `config/` subdirectory. + The `configure` script accepts the following options: + --prefix <dir>:: (default: '/usr/local') - Set the PREFIX variable used to define the defaults of the - following three options. Must be an absolute path name. +`-prefix <dir>`:: (default: `/usr/local`) + Set the `PREFIX` variable used to define the defaults of the following + three options. Must be an absolute path name. --bindir <dir>:: (default: '$(PREFIX)/bin') - Directory where the binaries will be installed. - Must be an absolute path name, or start with "$(PREFIX)" +`-bindir <dir>`:: (default: `$(PREFIX)/bin`) + Directory where the binaries will be installed. Must be an absolute + path name, or start with `$(PREFIX)`. --libdir <dir>:: (default: '$(PREFIX)/lib/ocaml') - Directory where the OCaml library will be installed - Must be an absolute path name, or start with "$(PREFIX)" +`-libdir <dir>`:: (default: `$(PREFIX)/lib/ocaml`) + Directory where the OCaml library will be installed. Must be an + absolute path name, or start with `$(PREFIX)`. --mandir <dir>:: (default: '$(PREFIX)/man/man1') - Directory where the manual pages will be installed - Must be an absolute path name, or start with "$(PREFIX)" +`-mandir <dir>`:: (default: `$(PREFIX)/man/man1`) + Directory where the manual pages will be installed. Must be an absolute + path name, or start with `$(PREFIX)`. --cc <C compiler and options>:: (default: gcc if available, cc otherwise) - C compiler to use for building the system +`-cc <C compiler and options>`:: (default: `gcc` if found, otherwise `cc`) + C compiler to use for building the system. --libs <extra libraries>:: (default: none) - Extra libraries to link with the system +`-libs <extra libraries>`:: (default: none) + Extra libraries to link with the system. --no-curses:: +`-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 or CPU-COMPANY-KERNEL-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. - --target <targettype>:: (default: same as -host) - The type of the target machine, in GNU's "configuration name" - format (CPU-COMPANY-SYSTEM or CPU-COMPANY-KERNEL-SYSTEM). - Setting this will setup OCaml as a cross-compiler which runs on - $host and produces code for $target. This requires a C toolchain - which also produces code for $target and a native OCaml - compiler of the exact same version (if you want a cross 4.00.1, - you need a native 4.00.1). - --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). - --no-pthread:: +`-host <hosttype>`:: (default: determined automatically) + The type of the host machine, in GNU's "configuration name" format + (CPU-COMPANY-SYSTEM or CPU-COMPANY-KERNEL-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 GNU Emacs contain a complete list of configuration names. + +`-target <targettype>`:: (default: same as `-host`) + The type of the target machine, in GNU's "configuration name" format + (CPU-COMPANY-SYSTEM or CPU-COMPANY-KERNEL-SYSTEM). Setting this will + setup OCaml as a cross-compiler which runs on `$host` and produces code + for `$target`. This requires a C toolchain which also produces code for + `$target` and a native OCaml compiler of the exact same version (if you + want a cross 4.00.1, you need a native 4.00.1). + +`-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`). + +`-no-pthread`:: Do not attempt to use POSIX threads. --with-pthread:: +`-with-pthread`:: Attempt to use POSIX threads (this is the default). --no-shared-libs:: - Do not configure support for shared libraries +`-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. +`-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) +`-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. +`-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 pre-process + 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. +`-with-debug-runtime`:: + Compile and install the debug version of the runtimes, useful for + debugging C stubs and other low-level code. --with-instrumented-runtime:: - Compile and install the instrumented version of the runtimes, - useful mainly for fine-tuning the GC. Works only on Linux. +`-with-instrumented-runtime`:: + Compile and install the instrumented version of the runtimes, useful + mainly for fine-tuning the GC. Works only on Linux. --verbose:: - Verbose output of the configuration tests. Use it if the outcome - of configure is not what you were expecting. +`-verbose`:: + Verbose output of the configuration tests. Use it if the outcome of + `configure` is not what you were expecting. --no-debugger:: - Do not build ocamldebug. +`-no-debugger`:: + Do not build `ocamldebug`. --no-native-compiler:: +`-no-native-compiler`:: Do not build the native compiler -- bytecode compilation only. --no-ocamldoc:: - Do not build ocamldoc. +`-no-ocamldoc`:: + Do not build `ocamldoc`. --no-ocamlbuild:: - Deprecated since 4.03.0, as ocamlbuild is now distributed separately +`-no-ocamlbuild`:: + Deprecated since 4.03.0, as `ocamlbuild` is now distributed separately from the compiler distribution. --no-graph:: +`-no-graph`:: Do not compile the Graphics library. --partialld <linker and options>:: (default: determined automatically) - The linker and options to use for producing an object file - (rather than an executable) from several other object files. +`-partialld <linker and options>`:: (default: determined automatically) + The linker and options to use for producing an object file (rather than + an executable) from several other object files. --no-cfi:: +`-no-cfi`:: Do not compile support for CFI directives. + Examples: -* Standard installation in /usr/{bin,lib,man} instead of /usr/local: +* Standard installation in `/usr/{bin,lib,man}` instead of `/usr/local`: ./configure -prefix /usr -* Installation in /usr, man pages in section "l": +* Installation in `/usr`, man pages in section "l": ./configure -bindir /usr/bin -libdir /usr/lib/ocaml -mandir /usr/man/manl + @@ -150,32 +152,32 @@ or: ./configure -cc "gcc -m32" -as "as --32" -aspp "gcc -m32 -c" \ -host i386-linux -partialld "ld -r -melf_i386" -* On a Linux x86-64 host, to build the run-time system in PIC mode, - no special options should be required---the libraries should be built - automatically. The old instructions were: +* On a Linux x86-64 host, to build the run-time system in PIC mode, no special + options should be required -- the libraries should be built automatically. + The old instructions were: ./configure -cc "gcc -fPIC" -aspp "gcc -c -fPIC" + -On a 64-bit POWER architecture host running Linux, OCaml only operates - in a 32-bit environment. If your system compiler is configured as 32-bit, - e.g. Red Hat 5.9, you don't need to do anything special. If that is - not the case (e.g. Red Hat 6.4), then IBM's "Advance Toolchain" can - be used. For example: +On a 64-bit POWER architecture host running Linux, OCaml only operates in a + 32-bit environment. If your system compiler is configured as 32-bit, e.g. + Red Hat 5.9, you don't need to do anything special. If that is not the case + (e.g. Red Hat 6.4), then IBM's "Advance Toolchain" can be used. For example: export PATH=/opt/at7.0/bin:$PATH ./configure -cc "gcc -m32" -as "as -a32" -aspp "gcc -m32 -c" \ -partialld "ld -r -m elf32ppc" -* On a MacOSX 10.5/Intel Core 2 or MacOSX 10.5/PowerPC host, - to build a 64-bit version of OCaml: +* On a OS X 10.5/Intel Core 2 or OS X 10.5/PowerPC host, to build a 64-bit + version of OCaml: + ./configure -cc "gcc -m64" -* On Intel Mac OS X, to build a 32-bit version of OCaml: +* On OS X Intel, to build a 32-bit version of OCaml: ./configure -host "i386-apple-darwin13.2.0" -cc "gcc -arch i386 -m32" \ -as "as -arch i386" -aspp "gcc -arch i386 -m32 -c" -* For Sun Solaris with the "acc" compiler: +* For Sun Solaris with the `acc` compiler: ./configure -cc "acc -fast" -libs "-lucb" @@ -183,12 +185,12 @@ On a 64-bit POWER architecture host running Linux, OCaml only operates ./configure -cc "gcc -m32" -as "as -32" -aspp "gcc -m32 -c" -* For AIX 4.3 with the IBM compiler xlc: +* 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 +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 @@ -200,15 +202,15 @@ for guidance on how to edit the generated files by hand. make world + -This builds the OCaml bytecode compiler for the first time. This -phase is fairly verbose; consider redirecting the output to a file: +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: +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 + @@ -217,18 +219,17 @@ 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: +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 fix-point. + +4. If your platform is supported by the native-code compiler (as reported during + the auto-configuration), you can now build the native-code compiler. From + the top directory, do: make opt + @@ -237,62 +238,62 @@ or: make opt > log.opt 2>&1 # in sh make opt >& log.opt # in csh -5. anchor:step-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: +5. anchor:step-5[] Compile fast versions of the OCaml compilers, by compiling + them with the native-code compiler (you will have only compiled them to + bytecode in steps 2-4). 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. +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 OCaml code - ocamldebug the source-level replay debugger - ocamldep generator of "make" dependencies for OCaml sources - ocamldoc documentation generator - ocamlprof execution count profiler - ocamlcp the bytecode compiler in profiling mode -+ -and also, if you built them during <<step-5,step 5>>, +The result is equivalent to `make world opt opt.opt`, but this may fail if +anything goes wrong in native-code generation. - 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 +6. 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 +|=============================================================================== ++ +and also, if you built them during <<step-5,step 5>>: `ocamlc.opt`, +`ocamlopt.opt`, `ocamllex.opt`, `ocamldep.opt` and `ocamldoc.opt` + 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". +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 +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 + @@ -301,71 +302,65 @@ or make install + In the latter case, the destination directory defaults to the -"site-lisp" directory of your Emacs installation. +`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 OCaml bytecode; stripping erases the bytecode!) -Other executables such as ocamlrun can safely be stripped. +9. After installation, do *not* strip the `ocamldebug` and `ocamlbrowser` + executables. These are mixed-mode executables (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. +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. +Check the files `m.h` and `s.h` in `config/`. Wrong endian-ness 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. +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). +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 which 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. +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 use the `include` directive, which is not supported by all + versions of make. Use GNU Make if this is a problem. -* Solaris make mishandles a space in our Makefiles, so you have to use GNU -make to build on Solaris. +* Solaris make mishandles a space in our Makefiles, so you have to use GNU make + to build on Solaris. -* 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. +* 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 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. +* 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. +* Some versions of GCC 2.96 for the Intel x86 (as found in RedHat 7.2, + Mandrake 8.0 and Mandrake 8.1) generate 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. +* 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`. -* Under MacOS X 10.6, with XCode 4.0.2, the configure script mistakenly -detects support for CFI directives in the assembler. -Fix: give the "-no-cfi" option to configure. +* Under OS X 10.6, with XCode 4.0.2, the `configure` script mistakenly detects + support for CFI directives in the assembler. Fix: give the `-no-cfi` option to + `configure`. |