Reformat other sections of INSTALL.adoc
David Allsopp
Gabriel Scherer
parent
5da78d01a6
commit
97ff08fcdf
213
INSTALL.adoc
213
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.
|
||||
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 autoconfiguration), you can now build the
|
||||
native-code compiler. From the top directory, do:
|
||||
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.
|
||||
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
|
||||
6. You can now install the OCaml system. This will create the following commands
|
||||
(in the binary directory selected during autoconfiguration):
|
||||
+
|
||||
and also, if you built them during <<step-5,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
|
||||
[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:
|
||||
|
||||
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 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
|
||||
+
|
||||
|
|
@ -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`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue