Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


(* ------------------------------------------------------------ *)
(* The build system                                             *)
(* ------------------------------------------------------------ *)

Important files:

* build_libs contains the external and internal mlstate libraries to be used

    internal libname [dir [installdir]]
        defines library lib with source in directory dir (optional)
        there must be an according .mllib file.
    external libname [dir]
        defines an external library

When dir is omitted, it's the name of the library. When installdir is omitted,
it's dir. This defines the use_libname tags and the installation of these libs
in MLSTATELIBS. Lines starting with # are comments

* build_tools contains the build-tools that we compile and use (eg. trx)

    internal toolname path
        defines an internally-built compilation tool. path is as understood
        by ocamlbuild (eg. trx_ocaml_main.native)
    external toolname path
        defines an external binary tool

Lines starting with # are comments

* build_rules.ml is included in our ocamlbuild plugin. It must contain one ocaml
  expression of type unit. Several functions and macros can be used:

  - shared_namespace_dir <dir>
  - include_subdirs <dir>
  - tool_deps <toolname>
  - get_tool <toolname>
  - def_stubs ~dir:<dir> <name>
  - mlstatelibs
  - and the usual ocamlbuild stuff

How it works:

Compilation is controlled by three things:

1) The _tags files in all directories. Local ones have higher priorities than
   more general ones.

2) The build_* files that handle definitions of libraries for linking, define
   specific tags and custom parameters.

3) Target files: these include .mllib, .clib, .itarget, .mlpack, which contain a
   list of modules or targets to be built.
   .mllib gives .cma, .cmxa
   .clib gives .a
   .itarget gives (the virtual file) .otarget
   .mlpack gives .cmo, .cmx

Remarks on the build system:

* Usage of the tag "include" is forbidden, it pollutes the namespace. Instead,
  build libraries and use the tag use_<libname>.  If a directory *really* needs
  access to the contents of another, use "Pathname.define_context" in
  build_rules.ml (see the examples in libqmlcompil).

* Keep the top-level _tags minimal, and use manually the tag "traverse" on any
  path that contains ocamlbuild-handled sources.

* Building libraries:
  you need
  - a toplevel .mllib file, supplying all the modules to be included
    (with the syntax path/to/OcamlModule)
  - a definition in build_libs

While all the modules in the mllib are compiled, only the .cmi included in the
main library directory are seen from the outside. This is *good*: it makes a
partition between public and private modules possible. You can add private
modules in subdirectories, and make them share the namespace of your library by
specifying "shared_namespace_dir" in build_rules.ml (see the examples).

This gives you three things: the rules for the creation of your .cma and .cmxa,
the definition of the tag use_<libname> that puts the right "-I" during
compilation and links to your lib, and the installation via bld.