OCaml Boilerplate Project Skeleton
		  ==================================

This project is a boilerplate OCaml project skeleton with the
following features already integrated in it:

- The OASIS (http://oasis.forge.ocamlcore.org/) build-system,
- The OCamlDoc automatic documentation generation,
- The OUnit testing framework,
- The Bisect code coverage framework,
- A default module and submodules hierarchy.


Dependencies
------------
In order to compile this project, you will need:
 * ocaml
 * findlib
 * oasis
 * ounit
 * bisect

You can either go through opam or install it through the packaging
system of your distribution. If you are going through opam:

    $> opam init
    $> opam install oasis ounit bisect


Setup and Build the Project
---------------------------

The OASIS framework is based on a `setup.ml` program that handle any
high-level operation on the project source (build, clean, tests, doc,
install, ...).

First, you have to generate this `setup.ml` file:

    $> oasis setup

Then, you need to configure the build-system in order to check that
all the dependancies are satisfied and to find what and where are the
tools to use:

    $> ocaml setup.ml -configure

Or, with the exact same result:

    $> ./configure

Note that, if you want to enable the test framework, you need to add
the option `--enable-tests', for example:

    $> ./configure --enable-tests

Then, you can build the project:

    $> make

Similarly the following commands would lead to the exact same result:

    $> make build
    $> ocaml setup.ml -build


Running Tests, Generating Documentation and more...
---------------------------------------------------
Running the test suite is only possible if you have triggered the
`--enable-tests` flag during the configuration phase (`configure`).
But, then, running the test suite only require to do:

    $> make tests

Or:

    $> ocaml setup.ml -tests

In the exact same way, generating the documentation with OCamlDoc is done through:

    $> make doc

Or:

    $> ocaml setup.ml -doc

Then, cleaning the project is done either through the `clean` command
or, if you want to get back to the original development distribution,
through the `distclean` command.

Installation and uninstallation of the software is handled by the
commands `install` and `uninstall`.

Here is a summary of all the commands of `setup.ml`:

 -configure [options*] Configure the whole build process
 -build [options*]     Build executables and libraries
 -doc [options*]       Build documents
 -test [options*]      Run tests
 -all [options*]       Run configure, build, doc and test targets
 -install [options*]   Install libraries, data, executables and documents
 -uninstall [options*] Uninstall libraries, data, executables and documents
 -reinstall [options*] Uninstall and install libraries, data, executables and documents
 -clean [options*]     Clean files generated by a build
 -distclean [options*] Clean files generated by a build and configure
 -version              Display version of OASIS used to generate this setup.ml
 -no-catch-exn         Don't catch exception, useful for debugging
 -quiet                Run quietly
 -info                 Display information message
 -debug                Output debug message
 -ignore-plugins       Ignore plugin's field
 -help, --help         Display this list of options


Project Hierarchy
-----------------
The project has four modules which are structured as follow:

     A
     +-B
       |-C
       +-D

Where A is the main library module of the project, B is a
submodule of A.

The module B contains a factory method pattern that will create a 'b'
object with either a 'c' or a 'd' implementation depending on the
argument given to the factory method.


Issues and Todo-list
--------------------

* The module hierarchy is still not yet totally clear to me, we still
  can directly access to the B module without needing to write A.B. It
  would be nice to know how to prevent leakage of the API without
  going through A.

  I guess that I need to dig a bit more in the *.mli file and in the
  ways to mask API.

* The Bisect code coverage module is not yet working, it is "work in
  progress". I do not think it is something difficult, I just have to
  spend some time on it.

* More extended OUnit2 test cases would be interesting, at least find
  how to use the 'bracket' feature that is used for setting/unsetting
  the tests context (fixtures such as SetUp and TearDown usual
  functions).

* Exploring other features of OCaml... Lets see what I need in the future...