Ekdohibs
/
ocaml
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ocaml/INSTALL.adoc

326 lines
13 KiB
Plaintext
Raw Blame History

= Installing OCaml from sources 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, 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.
* 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.config`,
`runtime/caml/m.h` and `runtime/caml/s.h`.
+
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.
`-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)`.
`-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 found, otherwise `cc`)
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.
The only use for this is to highlight errors in the toplevel using
'standout' mode, e.g. underline, rather than with '^' on a newline.
`-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`::
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 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-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.
`-no-debugger`::
Do not build `ocamldebug`.
`-no-native-compiler`::
Do not build the native compiler -- bytecode compilation only.
`-no-ocamldoc`::
Do not build `ocamldoc`.
`-no-ocamlbuild`::
Deprecated since 4.03.0, as `ocamlbuild` is now distributed separately
from the compiler distribution.
`-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`::
Do not compile support for CFI directives.
+
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
+
or:
./configure -prefix /usr -mandir '$(PREFIX)/man/manl'
* On a Linux x86-64 host, to build a 32-bit version of OCaml:
./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:
./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:
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 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 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:
./configure -cc "acc -fast" -libs "-lucb"
* For AIX 7.x with the IBM compiler `xlc`:
./configure CC=xlc
+
By default, build is 32-bit. For 64-bit build, please set environment variable `OBJECT_MODE=64`
for _both_ `configure` and `make world` phases. Note, if this variable is set for only one phase,
your build will break (`ocamlrun` segfaults).
+
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.opt
+
if your platform is supported by the native-code compiler (as reported during
the auto-configuration), or
make world
+
if not.
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 run the test suite
that comes with the compiler. To do so, do:
make tests
4. 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
|===============================================================================
+
From the top directory, become superuser and do:
umask 022 # make sure to give read & execute permission to all
make install
5. Installation is complete. Time to clean up. From the toplevel directory,
do:
make clean
6. (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.
7. 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.
Check the files `m.h` and `s.h` in `runtime/caml/`.
Wrong endianness or alignment constraints in `machine.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
`OC_CFLAGS` in `runtime/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 `runtime/`
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.
* 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`.
* 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) 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`.
* 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`.
Reference in New Issue View Git Blame Copy Permalink