[Caml-list] Announce: OCamlbuild to be distributed separately from the compiler

[Caml-list] Announce: OCamlbuild to be distributed separately from the compiler

[Gabriel Scherer]

Dear list,

We are going to move the OCamlbuild build system outside the standard
compiler distribution in the next few months. This has been demanded
by a part of the OCamlbuild user community for a long time¹, hoping to
lower the barrier to contribution and have a more flexible release
schedule.

The switch should happen in the following months, with the goal of
being done before the release of the next OCaml version (4.03),
planned for the first quarter of 2016. We have not planned all the
details yet, and there is still time for giving your advice on how
best to proceed.

¹: PR#6402: Move ocamlbuild to its own repository
   Hugo Heuzard, 2014-05-07
   http://caml.inria.fr/mantis/view.php?id=6402

# Impact on users (maintainers of ocamlbuild-using software)

The impact on the users should be minimal. The only difference is that
you cannot assume anymore than *any* OCaml installation has ocamlbuild
available. Projects using ocamlbuild as their build system
(directly or through OASIS) should have it marked as an explicit
compile-time dependency in their packaging descriptions.

For this purpose, I have created an "ocamlbuild" package in the main
OPAM repository, that for now is just a dummy package (for OCaml <
4.03, it does not need to actually install anything). You can already
start adding "ocamlbuild" as a dependency in the OPAM metadata² in your
development repositories (the one used by "opam pin"), and in future
uploads to the public opam repository.

For existing packages in the public opam repository, there is nothing
to do. We have used an automated transform³ to add this new dependency
to all packages that use ocamlbuild⁴, so that no change on
already-published packages should be necessary. The scripts used to do
so is publicly available⁵, so maintainers of other opam repositories
should be able to run it as well (please contact me if you have any
trouble doing so).

²: just edit your OPAM file to change

  depends: [ ... ]

into

  depends: [
    ...
    "ocamlbuild" {build}
  ]

³: https://github.com/ocaml/opam-repository/pull/5140

⁴: the heuristic used is to assume that a package uses ocamlbuild if:
   - it contains a _tags or myocamlbuild.ml file somewhere, or
   - it calls "ocamlbuild" from OPAM's build steps, or
   - it has an _oasis file which specifies ocamlbuild as build system
  2885 of the 4214 packages in the current opam-repository master
  trigger this heuristic.

  If you happened to know of a project that uses ocamlbuild despite
  failing this test, please let us know so that we can refine the
  bulk-update script.

⁵: https://github.com/gasche/opam/blob/ocamlbuild-migration-script/admin-scripts/add_ocamlbuild_dependency.ml

One notable exception would be authors of ocamlbuild plugins. The bulk
update script only adds ocamlbuild as a build-time dependency; if you
provide libraries on top of OCamlbuild's libraries, you may need
a manual update of existing opam metadata. Could you please let me
know about it, in case there is an easy way to update the migration
script?


# Impact on project development

OCamlbuild's main strength is being able to build simple OCaml
projects in an extremely simple way -- yet scale when they grow a bit
in complexity. It makes it useful to many OCaml users, and thus
a rather rewarding project to contribute to. In the past few years it
has had a relatively calm development rate, with no ground-breaking
changes, but rather small added features or usability improvements,
and the occasional bugfixes. It is also wide open to external
contributions; the 32 changes since the beginning of the 4.02 lifetime
have been contributed by 18 different people.

I have been the main regular contributor to OCamlbuild's development
in the last few releases of OCaml (with various much-appreciated
external contributions), and I plan to continue improving the tool at
a reasonable pace. Some people have requested that ocamlbuild be split
off in the past, arguing that it would increase the contributor
base -- we will see if it indeed lowers the barrier to
contribution. Last but not least, whitequark, who has done many useful
contributions in the past releases, seems willing to help supporting
the project.

Until fairly recently, the most lamented defect of OCamlbuild was
a lack of documentation. I announced a new manual⁶ this year,
and am planning to make it the default manual with the next ocamlbuild
release. Contributions to the manual are warmly welcome; Christian
Linding has contributed a lot of useful feedback and started filling
a directory of small, representative examples⁷; you should feel
free to add one for your preferred distinct use-case.

⁶: https://github.com/gasche/manual-ocamlbuild/blob/master/manual.md
⁷: https://github.com/gasche/manual-ocamlbuild/tree/master/examples

The new development repository of OCamlbuild should be hosted by the
OCaml Github organization, at

  https://github.com/ocaml/ocamlbuild

Have fun hacking (and building) OCaml software!