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

move install file to asciidoc

master
Simon Cruanes 2015-09-22 11:21:31 +02:00
parent 62da50c7ba
commit 066022aa8a
1 changed files with 83 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

153
INSTALL → INSTALL.adoc
View File

@ -1,7 +1,6 @@
Installing OCaml on a Unix machine
----------------------------------
= Installing OCaml on a Unix machine =
PREREQUISITES
== PREREQUISITES
* The GNU C compiler gcc is recommended, as the bytecode
interpreter takes advantage of gcc-specific features to enhance
@ -21,43 +20,43 @@ PREREQUISITES
export GNUMAKE=gmake
INSTALLATION INSTRUCTIONS
== INSTALLATION INSTRUCTIONS
1- Configure the system. From the top directory, do:
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.
The "configure" script accepts the following options:
-prefix <dir> (default: /usr/local)
+
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)
-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)
-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)
-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)
-cc <C compiler and options>:: (default: gcc if available, cc otherwise)
C compiler to use for building the system
-libs <extra libraries> (default: none)
-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)
-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
@ -65,7 +64,7 @@ The "configure" script accepts the following options:
hand. The installation instructions for gcc or emacs contain a
complete list of configuration names.
-target <targettype> (default: same as -host)
-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
@ -74,138 +73,148 @@ The "configure" script accepts the following options:
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)
-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
-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
-no-shared-libs::
Do not configure support for shared libraries
-dldefs <cpp flags>
-dllibs <flags and 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)
-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.
-with-debug-runtime
-with-debug-runtime::
Compile and install the debug version of the runtimes, useful
for debugging C stubs and other low-level code.
-verbose
-verbose::
Verbose output of the configuration tests. Use it if the outcome
of configure is not what you were expecting.
-no-debugger
-no-debugger::
Do not build ocamldebug.
-no-ocamldoc
-no-ocamldoc::
Do not build ocamldoc.
-no-ocamlbuild
-no-ocamlbuild::
Do not build ocamlbuild.
-no-graph
-no-graph::
Do not compile the Graphics library.
-partialld <linker and options> (default: determined automatically)
-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
or:
+
or:
./configure -prefix /usr -mandir '$(PREFIX)/man/manl'
On a Linux x86-64 host, to build a 32-bit version of OCaml:
* 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,
* 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"
./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 MacOSX 10.5/Intel Core 2 or MacOSX 10.5/PowerPC host,
* On a MacOSX 10.5/Intel Core 2 or MacOSX 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 Intel Mac OS X, 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"
For Sun Solaris on Sparc 64bit, to compile natively (32bit only)
* For Sun Solaris on Sparc 64bit, to compile natively (32bit only)
./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
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:
2. From the top directory, do:
make world
+
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
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
+
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
@ -215,21 +224,23 @@ 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
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:
make opt
+
or:
make opt > log.opt 2>&1 # in sh
make opt >& log.opt # in csh
5- Compile fast versions of the OCaml compilers, by compiling them
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:
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
@ -237,15 +248,15 @@ 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
6. You can now install the OCaml system. This will create the
following commands (in the binary directory selected during
autoconfiguration):
@ -262,38 +273,40 @@ autoconfiguration):
ocamldoc documentation generator
ocamlprof execution count profiler
ocamlcp the bytecode compiler in profiling mode
+
and also, if you built them during 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
+
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
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
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
+
or
make install
make install
+
In the latter case, the destination directory defaults to the
"site-lisp" directory of your Emacs installation.
9- After installation, do *not* strip the ocamldebug and ocamlbrowser
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.
IF SOMETHING GOES WRONG:
== IF SOMETHING GOES WRONG
Read the "common problems" and "machine-specific hints" section at the
end of this file.
@ -314,12 +327,12 @@ 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
'../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:
== 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.