diff options
-rw-r--r-- | INSTALL.adoc | 217 |
1 files changed, 106 insertions, 111 deletions
diff --git a/INSTALL.adoc b/INSTALL.adoc index 5f177f25ca..e020507b38 100644 --- a/INSTALL.adoc +++ b/INSTALL.adoc @@ -2,16 +2,15 @@ == 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. == INSTALLATION INSTRUCTIONS @@ -197,15 +196,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 + @@ -214,18 +213,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 + @@ -234,62 +232,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 + @@ -298,37 +296,35 @@ 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 @@ -336,33 +332,32 @@ pinpoint the problem. * 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`. |