01/01: doc: Document ocaml-build-system.

[julien lepiller]

roptat pushed a commit to branch master
in repository guix.

commit 3184f14ad45eb4bdbb6744f4335132481fab7cc1
Author: Julien Lepiller <address@hidden>
Date:   Sat Jan 28 12:11:42 2017 +0100

    doc: Document ocaml-build-system.
    
    * doc/guix.texi (Build Systems) [ocaml-build-system]: New definition.
---
 doc/guix.texi |   43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 8c4067f..1fbe446 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -3291,6 +3291,49 @@ specified with the @code{#:glib} parameter.
 Both phases are executed after the @code{install} phase.
 @end defvr
 
address@hidden {Scheme Variable} ocaml-build-system
+This variable is exported by @code{(guix build-sytem ocaml)}.  It implements
+a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists
+of choosing the correct set of commands to run for each package.  OCaml
+packages can expect many different commands to be run.  This build system will
+try some of them.
+
+When the package has a @file{setup.ml} file present at the top-level, it will
+run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and
address@hidden setup.ml -install}.  The build system will assume that this file
+was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will take
+care of setting the prefix and enabling tests if they are not disabled.  You
+can pass configure and build flags with the @code{#:configure-flags} and
address@hidden:build-flags}.  The @code{#:test-flags} key can be passed to 
change the
+set of flags used to enable tests.  The @code{#:use-make?} key can be used to
+bypass this system in the build and install phases.
+
+When the package has a @file{configure} file, it is assumed that it is a
+hand-made configure script that requires a different argument format than
+in the @code{gnu-build-system}.  You can add more flags with the
address@hidden:configure-flags} key.
+
+When the package has a @file{Makefile} file (or @code{#:use-make?} is
address@hidden), it will be used and more flags can be passed to the build and
+install phases with the @code{#:make-flags} key.
+
+Finally, some packages do not have these files and use a somewhat standard
+location for its build system.  In that case, the build system will run
address@hidden pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of
+providing the path to the required findlib module.  Additional flags can
+be passed via the @code{#:build-flags} key.  Install is taken care of by
address@hidden  In this case, the @code{opam} package must
+be added to the @code{native-inputs} field of the package definition.
+
+Note that most OCaml packages assume they will be installed in the same
+directory as ocaml, which is not what we want in guix.  In particular, they
+will install @file{.so} files in their module's directory, which is usually
+fine because it is in the ocaml compiler directory.  In guix though, these
+libraries cannot be found and we use @code{CAML_LD_LIBRARY_PATH}.  This
+variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
address@hidden libraries should be installed.
address@hidden defvr
+
 @defvr {Scheme Variable} python-build-system
 This variable is exported by @code{(guix build-system python)}.  It
 implements the more or less standard build procedure used by Python