We all have various functions, types, or even whole modules that we use in many different programs or libraries, but that somehow we don't put in a separate library. I see two reasons for this:

• we don't have or take the time to extract this code and create a separate library, with a Makefile, a README, a configure script, etc..., and of course all the code should be consistent in term of parameter names and order, usage of labels, ..., which takes a lot of time, too.
• the functions, types, ..., we use this way don't necessarily have anything in common: functions can manipulate strings, as well as trees, files, ....

Moreover, even if we took the time to isolate groups of consistent elements or put together elements doing the same kind of treatments, we would not, because it would make the programs or libraries we distribute depend on these small libraries. These dependencies can make the installation of the final software a real pain, especially when it is distributed in source only. So, in the hope that more people try and use the final software, we keep the "little functions" inside, in various Misc and Stuff modules. Worse, we sometimes find a bug in one of these functions (or we improve them), and must think about fixing them in all the places we copy-pasted the code.

So the idea behind Caml-get is to make copy-paste easier, and keep track of it, to automatically change it when the original source code is modified. As an extension, it can be used to distribute this code so that other developers can use what would never have been put in a distributed library anyway.

It is possible with a language like OCaml, because writing polymorphic and/or general usage code is very easy and comes naturally.

Caml-get comes with a Cameleon2 plug-in to perform operations on the repositories, and browse available elements.

An element can be an OCaml value, a type, a module, or an exception. An implementation code and an interface code are associated to each element.

Each element has a name, which can be different from the real name in the OCaml code, in order to organize distributed elements in a different way from the files they come from.

There are two different activites: distributing code, and using distributed code.

The distributed code is put in a Caml-get archive, on a web server (by now, supported protocols are "HTTP://" and "file://"), (usually) by the author of the code. This archive contains the functions, types, modules and exceptions, along with their name, version number, comment (à la ocamldoc), and of course interface and implementation code. To create an archive, see distributing code. The archive can be seen as the server side.

Using the distributed code can be seen as the client side. The repository is the file containing the available elements and sources. By default it is ~/.camlget_repository. This repository will be filled by retrieving the content of Caml-get archives. Then, some Caml-get commands can be used to extract code of elements from the repository and put it in your own source code files, or to upgrade the code of elements (in your code) with a newer version found in the repository. See using distributed code.

Assertions are a good way to specify the behaviour of a function or a module. Such assertions could also be used as test cases for the function or module.

To do so, we define a new @cgtest tag for OCamldoc comments. Each "code" elements of the text in the tag will be used as an assertion and must be a valid OCaml expression of type bool. The "code" elements in OCamldoc texts are indicated between [ and ] or <[ and ]>.

For example, let's define the following function, used to compare version numbers, represented by lists of integers:

let (<<) =
  let rec iter = function
      ([], []) -> false
    | ([], _) -> true
    | (_,[]) -> false
    | (h1::q1, h2::q2) ->
        (h1 < h2) or
        (h1 = h2 && (iter (q1,q2)))
  in
  fun v1 v2 -> iter (v1,v2)

In the OCamldoc comment, we write:

(** [v1 << v2] returns true if version [v1] is strictly inferior to version [v2].
   @cgtest The following assertions hold:
- [[1;2] << [1;3]]
- [not ([1;2] << [1;2])]
- [let v = [ 1; 2 ; 3] and w = [ 1; 2] in w << v ]
*)

In the comment, we indicate three assertions, i.e. three OCaml expressions of type bool which should be evaluated to true:

• [1;2] << [1;3]
• not ([1;2] << [1;2])
• let v = [ 1; 2 ; 3] and w = [ 1; 2] in w << v

Then the following commands use the odoc_cgtest OCamldoc custom generator to gather these assertions and generate code in a file check.ml. After compiling this file, we can run the check.x program:

ocamldoc -g odoc_cgtest.cmo -o check.ml myfile.ml
ocamlc -o check.x myfile.cmo check.ml
./check.x
All test passed

If we add a bad assertion, for example [1;2]<<[1;2], the same procedure will fail, indicating that the assertion number 3 (starting from 0) for value Myfile.(<<) is false:

The following tests failed:
Myfile.(<<) [3]

To make the defined assertions appear in the documentation, we can use the odoc_htmlcg OCamldoc custom HTML generator also included in the Caml-get distribution.

Even though Caml-get works, a lot of features are still missing:

• support for classes must be added,
• maybe a dependency system could be added (but it's a lot of work, and I don't know yet if it would be really needed; using Caml-get will tell),
• maybe the history of versions of each element should be kept in the Caml-get archives and/or in the repository,
• an emacs interface would be useful to insert code from the repository at the position of the cursor.

Caml-get is distributed under the LGPL license version 3.