OPAM 1.2 and Travis CI

The new pinning feature of OPAM 1.2 enables new interesting workflows for your day-to-day development in OCaml projects. I will briefly describe one of them here: simplifying continuous testing with Travis CI and GitHub.

Creating an opam file

As explained in the previous post, adding an opam file at the root of your project now lets you pin development versions of your project directly. It's very easy to create a default template with OPAM 1.2:

$ opam pin add <my-project-name> . --edit
[... follow the instructions ...]

That command should create a fresh opam file; if not, you might need to fix the warnings in the file by re-running the command. Once the file is created, you can edit it directly and use opam lint to check that is is well-formed.

If you want to run tests, you can also mark test-only dependencies with the {test} constraint, and add a build-test field. For instance, if you use oasis and ounit, you can use something like:

build: [
  ["./configure" "--prefix=%{prefix}%" "--%{ounit:enable}%-tests"]
  [make]
]
build-test: [make "test"]
depends: [
  ...
  "ounit" {test}
  ...
]

Without the build-test field, the continuous integration scripts will just test the compilation of your project for various OCaml compilers. OPAM doesn't run tests by default, but you can make it do so by using opam install -t or setting the OPAMBUILDTEST environment variable in your local setup.

Installing the Travis CI scripts

Travis CI is a free service that enables continuous testing on your GitHub projects. It uses Ubuntu containers and runs the tests for at most 50 minutes per test run.

To use Travis CI with your OCaml project, you can follow the instructions on https://github.com/ocaml/ocaml-travisci-skeleton. Basically, this involves:

  • adding .travis.yml at the root of your project. You can tweak this file to test your project with different versions of OCaml. By default, it will use the latest stable version (today: 4.02.1, but it will be updated for each new compiler release). For every OCaml version that you want to test (supported values for <VERSION> are 3.12, 4.00, 4.01 and 4.02) add the line:
env:
 - OCAML_VERSION=<VERSION>
  • signing in at TravisCI using your GitHub account and enabling the tests for your project (click on the + button on the left pane).

And that's it, your project now has continuous integration, using the OPAM 1.2 pinning feature and Travis CI scripts.

Testing Optional Dependencies

By default, the script will not try to install the optional dependencies specified in your opam file. To do so, you need to manually specify which combination of optional dependencies you want to tests using the DEPOPTS environment variable. For instance, to test cohttp first with lwt, then with async and finally with both lwt and async (but only on the 4.01 compiler) you should write:

env:
   - OCAML_VERSION=latest DEPOPTS=lwt
   - OCAML_VERSION=latest DEPOPTS=async
   - OCAML_VERSION=4.01   DEPOPTS="lwt async"

As usual, your contributions and feedback on this new feature are gladly welcome.