Foreword

Portability

FaCiLe requires only the OCaml system (release 3.02 or greater) and should work in any environment supporting this system. It is developed in a Linux environment on PC architecture but does not use any specificities of Unix. It should work on other operating systems (i.e. MS Windows, Mac OS...), provided that the installation process is customised to the environment.

FaCiLe Structure and Naming Conventions

The library is split into numerous modules and submodules. They are all included (possibly with a limited user-oriented interface) into the main module Facile which should be opened by any other modules using FaCiLe. All the modules are extensively described in part II of this documentation. We do not recommend to users to open modules in Facile but to use prefixed notations (e.g. function post of Cstr is written Cstr.post). The pseudo-module named Easy is the exception and should be opened: it provides several aliases to the most frequently used values (see 4.1) and functions.

To avoid interferences with other modules of the user, all the modules are aliased in the Facile module and implementation module files are all prefixed by fcl_ (except of course Facile itself). For example, implementation of module Gcc is in file fcl_gcc.ml and alias

module Gcc = Fcl_gcc

is defined in Facile (facile.ml). This alias mechanism is entirely transparent to the user of FaCiLe except for the one interested by the implementation of the library. The only possible visibility of Fcl_ prefix is given by the uncaught exceptions printer (e.g. Fcl_stak.Fail instead of Stak.fail).

The reference part of this documentation is automatically generated from module interfaces (.mli). Some available functions, types or modules are intentionally not documented or even hidden in Facile module. They are not intented to the casual user.

Values and types names try to benefit as much as possible from the modularity. For example, most of the types are named t: type of constraints is Cstr.t, type of domains is Domain.t... In the same way, printing functions are named fprint, constraints are named cstr (e.g. Gcc.cstr)...

Standard or label mode of the OCaml compiler (option -labels) may be used with the library. FaCiLe makes use of labels (labelled arguments) as less as possible; only optional arguments are labelled.

Compilation with FaCiLe

FaCiLe is provided as bytecode and native code¹ libraries.

Bytecode version is compiled with debugging information (-g option of ocamlc) and then can be used with the source-level replay debugger (ocamldebug). A lot of checks are done in this mode and exceptions may be raised revealing bad usage of the system (``fatal'' errors) or bugs in the system itself (``internal'' errors). In the second case, diligent users should send a bug report to the developers.

In the native code version, these redundant checks are not done and this mode should be used only on well-tried code.

The Makefile in the examples directory of the distribution provides generic rules to compile with FaCiLe in both modes producing .out (bytecode) or .opt (native code) executables.

The library may also be used through linked toplevel produced with the following command (after installation):

ocamlmktop -o facile -I +facile facile.cma

This is the toplevel used in the inlined examples of this documentation and invoked with the command line:

./facile -I +facile

Availability

The FaCiLe distribution and documentation are available from the web site where general information can be found:

http://www.recherche.enac.fr/opti/facile

Questions, bug reports... can be mailed to

facile@recherche.enac.fr

Installation

Installation of FaCiLe is described in the README file of the distribution. Below is a copy of the corresponding part:

INSTALLATION:

  All you need is the Objective Caml 3.02 (or greater) compiler and
standard Unix tools (make...).

  0) Configure the library. The single option of configuration is the
directory you want to put the library files in (facile.cma, facile.cmxa,
facile.a facile.cmi). Default is the subdirectory "facile" of the Ocaml
library directory (returned by "ocamlc -where").

 ./configure [--faciledir <target directory>]

  1) First compile the library with a simple

        make

  2) Check the result

        make check

     You should get a solution for the 8 queens problem.

  3) Then install the library with a (usually as root)

        make install

Examples

The directory examples of the distribution contains some examples and a generic Makefile to compile files with FaCiLe. Examples are taken from the classic litterature:

Coins: Give back change for any amount
Golf: Organize a golf tournament for 8 teams of 4 players
Golomb: Find optimal Golomb rulers
Jobshop: Solve the famous mt10 scheduling problem -- Edge-Finding inside!
Magic: To count and to be counted
Marriage: Stabilize preferences among spouses
Prolog: Use FaCiLe as a Prolog interpreter on a family tree problem
Queens: Place queens on a chessboard
Seven_eleven: My grocer's favorite arithmetic puzzle
Tiles: Tile a big square with small squares

1: If supported by your architecture. See http://caml.inria.fr/ocaml/portability.html