README

	  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...