For developers only

See the ocamldoc generated documentation. Read the module Types first and the description of each module type.

How to extend the code

To add a new Foo, where Foo ∈ {Rule; Experiment; Topology; Synchronism}:

Write a file foo/bar.ml following the examples provided and the ocamldoc generated documentation. This file must a functor Qux taking some Parameters (see examples) returning a module of signature Types.Foo.

Now register this foo in the code (straightforward):

• edit foo.camlmix to add your new file foo/bar.ml
• edit the value available_foos in user_interface/text.ml
• edit the function Load_foo.main in cimula.mlp to add your module Qux
• execute "./newfile"
• enjoy! (or more accurately, cycle edit file - make - edit file - make ... :-)

To study the code

My comments habits

• ocamldoc comments
• standard local comments explaining how the computation is conducted
• tiny code to test the functions in the toplevel. Ubiquitous in Femtolib. Also includes all the "#directory" and "#load" directives. Light weight / dark age version of a unit test framework. If you need one, there is a unit test framework for OCaml : it's OUnit.
• previous version of the code that should soon disappear when the new version has proven to be superior (and bug free...).

I try to have meaningful names that makes comments unecessary. They can be long, thanks to emacs completion :-) All comments are on the same line of or before the commented code.

My naming habits

Thanks to the well separated namespaces of OCaml, I often have a type and a value of this type bearing the same name. Singular and plural form of the names are meaningful.

My awful building system

I want to have modules like Plot.Line and Topology.Line, and I further want to define these modules in separate files like plot/line.ml and topology/line.ml. This isn't (yet ?) possible by default in OCaml, so like other programmers I use a small tool to concatenate plot/*.ml into plot.ml, then I can compile plot.ml and topology.ml and get the desired modules. This small concatenation tool is currently camlmix, which merely executes and insert the standard output of the caml code enclosed between double sharps: ## ... ##. Other solutions would be cpp, camlp4 or ocamlc -pack (but when I chose the building system, ocamldoc couldn't cope with plot/line.ml and topology/line.ml. I'll be glad to hear this has changed). make will compile camlmix if it isn't in the sources directory and copy it here, make clean_all will erase it.

Never edit the .ml files if there is a corresponding .camlmix file. make regenerates foo.ml if a file foo/bar.ml has changed. The Makefile itself is generated from Makefile.camlmix. It is regenerated each time Makefile.camlmix is touched. In case the Makefile get messed up, you can regenerate it by typing

  make -f Makefile.bootstrap

(make wants to generate the file .depend (since it's included in the Makefile) before issuing any command and, if the Makefile is buggy, make is unable to generate it).

In short: edit cimula.mlp, not cimula.ml. Why is cimula.mlp needed? Three lines in cimula.ml are used to save a snapshot. But this require the library Camlimages. If this lib isn't installed, we just want not to save snapshots. So configure sets the variable DEFINE_SAVE_SNAPSHOT in Makefile.config, and cimula.ml is generated from cimla.mlp by campl4. The intermediate file cimula.ml is needed for ocamldoc.