Building and Publishing an OCaml Package: Q1 2017

One of the key indicators of maturity of a language ecosystem is the ease of building, managing and publishing software packages in that language. OCaml platform has made steady progress in the last few years to this end. While OPAM simplified package (and compiler) management, the developing and publishing packages remained a constant pain point. This situation has remarkably improved recently with the Topkg and Carcass. This post provides a short overview of my workflow for building and publishing an OCaml package using Topkg and Carcass.

Topkg is packager for distributing OCaml software. It provides an API for describing rules for package builds and installs. Topkg-care provides the command line tool topkg with support for creating and linting the distribution, publishing the distribution and its documentation on WWW, and making the package available through OPAM. Carcass is a library and a command line tool for defining and generating the directory structure for the OCaml package. At the time of writing this post, carcass was unreleased.

Workflow

I recently released a package for mergeable vectors based on operational transformation. The following describes my workflow to build and publish the package.

Setup

Install topkg-care and carcass:

$ opam install topkg-care opam-publish
$ opam pin add -kgit carcass https://github.com/dbuenzli/carcass

Develop

• Create the directory structure

    $ carcass body topkg/pkg mergeable_vector
  

• Init

    $ cd mergeable_vector && git init && git add . && git commit -m "First commit."
    $ git remote add origin https://github.com/kayceesrk/mergeable-vector
    $ git push --set-upstream origin master
  

• Develop: The mergeable_vector/src directory has the source files. I use this Makefile at the root of the package.

• Test the package locally with OPAM

    $ opam pin add mergeable_vector .
  

Publish

• Update the CHANGES file for the new release.
• Tag the release

    $ topkg tag 0.1.0
  

• Build the distribution

    $ topkg distrib
  

• Publish the distribution

    $ topkg publish distrib
  

  This makes a new release on Github.

• Publish the doc

    $ topkg publish doc
  

  This publishes the documentation on Github.

• Make an OPAM package info and submit it to OPAM repository at opam.ocaml.org.

    $ topkg opam pkg
    $ topkg opam submit
  

  This creates a Github PR to the opam-repository. Once the PR is merged, the package becomes available to the users.