Skip to content

Commit

Permalink
Update INSTALL.adoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@shindere
shindere committed May 21, 2019
1 parent 1d7740f commit 7527450
Showing 1 changed file with 27 additions and 185 deletions.
212 changes: 27 additions & 185 deletions INSTALL.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
= Installing OCaml from sources on a Unix(-like) machine =

== PREREQUISITES
== 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
Expand All @@ -19,166 +19,34 @@
to be able to process `.cmxs` files. `diffutils` is necessary to run the test
suite.

== INSTALLATION INSTRUCTIONS
== Configuration

1. Configure the system. From the top directory, do:
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:
The `configure` script accepts options that can be discovered by running:

./configure --help
+
`-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.
Some options or variables like (LDFLAGS) may not be taken into account
by the OCaml build system at the moment. Please report an issue if you
discover such a variable or option and this causes troubles to you.
+
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

./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"
./configure --build=x86_64-pc-linux-gnu --host=i386-linux \
CC='gcc -m32' AS='as --32' ASPP='gcc -m32 -c' \
PARTIALLD='ld -r -melf_i386'

* For AIX 7.x with the IBM compiler `xlc`:

Expand All @@ -197,7 +65,9 @@ files cause errors later on, then look at the template files:
+
for guidance on how to edit the generated files by hand.

2. From the top directory, do:
== Building the compiler

From the top directory, do:

make world.opt
+
Expand All @@ -214,12 +84,16 @@ 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
== (Optional) Running the testsuite

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
== Installing the compiler

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%"]
Expand All @@ -241,33 +115,19 @@ fairly verbose; consider redirecting the output to a file:
+
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,
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
After installation, do *not* strip the `ocamldebug` executables.
This is a mixed-mode executable (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
== If something goes wwong

Read the "common problems" and "machine-specific hints" section at the end of
this file.
Expand All @@ -292,13 +152,7 @@ directory and do `make ocamlrund`. Then, copy `ocamlrund` to
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.
== Common problems

* 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`
Expand All @@ -308,18 +162,6 @@ lots of assertions and sanity checks that could help you pinpoint the problem.
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`.

0 comments on commit 7527450

Please sign in to comment.