Cohttp Packaging Breakage Ahead

As a follow up to my previous post 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:

Opam Package

Old Findlib

New Findlib

Top-level Module

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.

Optional Dependencies Considered Harmful   Monadic Generators in OCaml

Comments

comments powered by Disqus