.. post:: 2017-05-14
   :tags: OCaml, OPAM, Cohttp
   :author: Rudi Grinberg

Cohttp Packaging Breakage Ahead
===============================

As a follow up to my :doc:`previous post
</posts/optional-dependencies-considered-harmful>` regarding optional
dependencies, I'd like to expand on how my advice will be followed in practice
in the context of the `cohttp`_ library.

the tl;dr is as follows:

* The majority users will likely need to update their opam dependencies.
* ``cohttp.js`` (xhr) users will be forced to upgrade to jsoo 3.0
* There will be a 1 to 1 mapping between cohttp opam packages and top level
  modules

Opam packaging changes
----------------------

In the next verion of cohttp (0.22.0), the library will split into the following
opam packages:

* cohttp - Contains types for various HTTP entities and IO independent code.
  Usually not useful on its own.
* cohttp-lwt - Shared code between the various Lwt backends. Unix, mirage, jsoo
* cohttp-lwt-unix - Cohttp backend for Lwt + Unix users. Confusingly, Unix
  alludes to OCaml's `Unix`_ module rather than any operating system. So this
  will work on windows as well.
* cohttp-lwt-jsoo - In browser Cohttp/Lwt client for jsoo users
* cohttp-async - Backend for Async users

If you're using cohttp, chances that your opam file will need to include more
than one of the opam packages above. Previous reliance on a lwt or async
package in the depopts section will no longer work. Please be advised.

Findlib changes
---------------

Every single one of the packages above will now install a findlib package with
the same name as the opam package. These are now the recommended findlib
packages to use. I still recommend to upgrade the build systems gradually, so
that a package supports building against both old and new versions of cohttp.

Here's a full list of the "old" findlib sub-packages that will be removed
eventually:

* ``cohttp.js``
* ``cohttp.lwt``
* ``cohttp.lwt-core``
* ``cohttp.async``

Again, these will all continue to work in the foreseeable future provided that
the corresponding opam packages are installed.

Future changes
--------------

One exciting ability that jbuilder enables is the use of module aliases instead
of module packs. What this means for cohttp is that we'll consistently provide a
single top level module for every cohttp sub package. This could have been done
previously with packs, but a combination of ocamlbuild's inability to hide a
packed module's constituents, and the slow down of builds caused by packs
discouraged this from being done. With these restrictions out of the way, the
situation will finally be harmonized. Practically, this means that the following
top level packages will be deprecated and eventually removed:

* ``String_io_lwt``
* ``Cohttp_lwt_s``
* ``Cohttp_lwt_unix_debug``
* ``Cohttp_lwt_unix_body``
* ``Cohttp_lwt_body``
* ``Cohttp_lwt_unix_net``
* ``Cohttp_lwt_unix_io``
* ``Cohttp_async_io``

Most of these are already private and are of little use to most users. But the
others will be available under their respective top level module name. E.g.
``Cohttp_lwt_unix.Body``

Summary
-------

Here's a little summarizing the naming changes the new Cohttp 0.22.0 will
bring:

.. csv-table::
   :header: "Opam Package", "Old Findlib", "New Findlib", "Top-level Module"
   :widths: auto

   cohttp,cohttp,cohttp,Cohttp
   cohttp-lwt,cohttp.lwt-core,cohttp-lwt,Cohttp_lwt
   cohttp-lwt-unix,cohttp.lwt,cohttp-lwt-unix,Cohttp_lwt_unix
   cohttp-lwt-jsoo,cohttp.xhr,cohttp-lwt-jsoo,Cohttp_lwt_xhr
   cohttp-async,cohttp.async,cohttp-async,Cohttp_async

Happy hacking and good lucky porting your packages.

.. _cohttp: https://github.com/mirage/ocaml-cohttp
.. _unix: https://caml.inria.fr/pub/docs/manual-ocaml/libref/Unix.html