OCaml Weekly News

Previous Week Up Next Week


Here is the latest OCaml Weekly News, for the week of February 06 to 13, 2024.

Table of Contents

Sherlodoc, a search engine for OCaml documentation

Emile Trotignon announced

We (@art-w, @EmileTrotignon) are pleased to announce the first release of Sherlodoc on opam!

Sherlodoc is a search engine for OCaml documentation, which supports search by name, documentation and fuzzy type search (similar to Hoogle in the Haskell world). You can try it at doc.sherlocode.com on the libraries published in the opam repository, thanks to all the documentation available on OCaml.org.

  • The main focus of this release is the integration with Odoc (and support for dune build @doc is in progress). The latest release of Odoc 2.4.0 introduces a search bar in its static html documentation, which enables a javascript search engine to run client-side (without a server). Since Sherlodoc is fully implemented in OCaml, it was straightforward to compile it to javascript using js_of_ocaml. See for example the Cmdliner package documentation with search hosted on github static pages.
  • Sherlodoc now uses the odoc.search library and is hence able to search for modules, types, constructors, record fields, etc as well as inside documentation comments. (Protip for library authors: Sherlodoc heavily favors documented functions ;) )
  • There is also a new command-line interface that you could use to locally search packages installed in your switch, although the CLI was developed for debugging and could use some love!

Instructions for trying out this new version can be found in the readme, but it can be as simple as:

$ opam install sherlodoc odig
$ odig odoc
$ export SHERLODOC_DB=/tmp/sherlodoc.marshal
$ sherlodoc index $(find $OPAM_SWITCH_PREFIX/var/cache/odig/odoc -name '*.odocl'  | grep -v "__")
$ sherlodoc search "list map"

We hope you enjoy it to find your way in the ever-growing OCaml ecosystem! <3

This is an early release: if you believe that having a great search engine is important, please help us by reporting any issue you encounter, queries with unexpected results, or by contributing new PRs! (to e.g. improve the CLI, the website or even the algorithms if you ever wanted to learn how a search engine works!)

dream-html 3.0.0

Yawar Amin announced

Hi, dream-html 3.0.0 has been released to opam: https://ocaml.org/p/dream-html/3.0.0

Dream-html is a library for generating HTML, closely integrated with Dream. It can be used as an alternative to Dream’s built-in Embedded ML templating language and comes with all current htmx attributes defined out of the box.

In this release, I made a breaking change (hence major version bump) to restrict the role attribute to only the acceptable values for ARIA roles. Previously it was accepting any format string.

Plus a major new feature: all the ARIA attributes with the types of their values narrowed as much as possible. Eg:

open Dream_html
open HTML

let toast ?(idval="toast") msg =
p [id "%s" idval; Aria.live `polite] [txt "%s" msg]

OCaml.org Newsletter: January 2024

Sabine Schmaltz announced

Welcome to the January 2024 edition of the OCaml.org newsletter! This update has been compiled by the OCaml.org team. You can find previous updates on Discuss.

Our goal is to make OCaml.org the best resource for anyone who wants to get started and be productive in OCaml. The OCaml.org newsletter provides an update on our progress towards that goal and an overview of the changes we are working on.

We couldn’t do it without all the amazing OCaml community members who help us review, revise, and create better OCaml documentation. Your feedback enables us to better prioritise our work. Thank you!

This newsletter covers:

  • OCaml Documentation: New documentation has been released, and existing documentation has been improved.
  • Dark Mode: There’s been good progress on implementing the upcoming dark mode.
  • General Improvements: As usual, we also worked on general maintenance and improvements based on user feedback, so we’re highlighting some of our work below.

Open Issues for Contributors

We created many issues for external contributors. The majority of them are suitable for OCaml beginners, and we’re happy to review and provide feedback on your pull requests!

You can find open issues for contributors here!

OCaml Documentation

We released multiple new documents, most notably on Modules, Functors, Libraries with Dune, as well as a new tutorial on using the OCaml.org Playground. The documentation on Labelled Arguments, Sets, and Options has been improved.

To better understand how effective the new documentation is, we are running user tests (announced on Discuss and on Twitter/X) to compare the old documentation content on v2.ocaml.org with the new documentation on ocaml.org. A sufficient number of newcomers to OCaml volunteered to help us with this. Thanks so much!

In addition, there is an open survey that asks you to rate the new documentation in relation to the old content: We would love to have your input on this survey, even if you only drop us some numeric ratings!

Relevant PRs and Activities:

We started opening issues marked with “help wanted” to enable external contributors to help improve the docs. The response has been overwhelmingly positive, and we’re thrilled to keep this up and make the OCaml documentation truly great with your help!

Upcoming Dark Mode

In December, oyenuga17 started to implement the new dark mode on OCaml.org. Plans are to complete and activate the dark mode based on browser/operating system preferences by early March. It looks like we are on track to achieve this.

We continuously merge small patches into OCaml.org, and you can take a look at completed dark mode pages on https://staging.ocaml.org. We placed a button at the bottom of the page to toggle the dark mode on staging. (This is not going to be released. It is only a means for us to review the dark mode pages.)

Completed Pages:

General Improvements

Most Notable Changes TLDR:

  • We merged a basic documentation search feature to enable search inside the OCaml documentation. It is available on the Learn area “Overview” page! There’s room for improvements here, the most notable of which would be adding typo correction, and unifying package and documentation search in the top navigation bar’s search box.
  • A long-standing bug where wrong library names were displayed in the package documentation module tree view has been fixed!
  • The package overview page now links to a new page that lists all package versions with their publication dates.
  • The changelog is now reachable from the main landing page.
  • We now link the prerequisites of tutorials and recommended next tutorials in the YAML metadata of the tutorial’s Markdown page. This ensures that these links between tutorials will stay valid.

Many thanks go out to the many contributors who helped improve OCaml.org in January. Find them listed below!

Relevant PRs and Activities:

OCaml 5.2.0, first alpha release

octachron announced

Two months after the release of OCaml 5.1.1, the set of new features for the future version 5.2.0 of OCaml has been frozen. We are thus happy to announce the first alpha release for OCaml 5.2.0.

This alpha version is here to help fellow hackers join us early in our bug hunting and opam ecosystem fixing fun (see below for the installation instructions). More information about the whole release process is now available in the compiler repository, and we will try to propagate this information to ocaml.org shortly.

The progresses on stabilising the ecosystem are tracked on the opam readiness for 5.2.0 meta-issue.

The full release is expected around April.

If you find any bugs, please report them on OCaml’s issue tracker.

If you are interested in the ongoing list of new features and bug fixes, the updated change log for OCaml 5.2.0 is available on GitHub.

Installation Instructions

The base compiler can be installed as an opam switch with the following commands on opam 2.1 and later:

opam update
opam switch create 5.2.0~alpha1

For previous version of opam, the switch creation command line is slightly more verbose:

opam update
opam switch create 5.2.0~alpha1

The source code for the alpha is also available at these addresses:

  • Fine-Tuned Compiler Configuration

    If you want to tweak the configuration of the compiler, you can switch to the option variant with:

    opam update
    opam switch create <switch_name> ocaml-variants.5.2.0~alpha1+options <option_list>

    where option_list is a space separated list of ocaml-option-* packages. For instance, for a flambda and no-flat-float-array switch:

    opam switch create 5.2.0~alpha1+flambda+nffa ocaml-variants.5.2.0~alpha1+options
    ocaml-option-flambda ocaml-option-no-flat-float-array

    The command line above is slightly more complicated for opam version anterior to 2.1:

    opam update
    opam switch create <switch_name> --packages=ocaml-variants.5.2.0~alpha1+options,<option_list>

    In both cases, all available options can be listed with opam search ocaml-option.

Release of ppxlib.0.32.0

Nathan Rebours announced

The ppxlib dev team is happy to announce the release of ppxlib.0.32.0.

The main feature of this release, implemented by @burnleydev1 during their Outreachy internship, is a huge improvement of the handling of located exceptions raised by ppx-es. Whenever a rewrite of the AST throws such an exception, the ppxlib driver catches it and resumes the rewriting using the latest valid AST it knows of. All caught exceptions are appended to the final AST as [%%ocaml.error ..] nodes. This means the driver returns a valid AST instead of one composed of a single error node corresponding to the first raised exception. This leads to a much better experience for ppx users as merlin now has a valid AST to work with when this happens, allowing it to properly function and report all errors, from ppx-es or otherwise. Note that despite this change we still recommend ppx authors to embed errors in the rewritten AST rather than throw exceptions.

The release also comes with a few bug fixes on longident parsing or windows compatibility and a new simplified API for ppx authors using attributes as flags (i.e. attributes without payloads such as [@ignore] for instance).

You can read the full patch notes here.

We’d like to thank our external contributors for this release:

  • @burnleydev1 for their improvement of the driver exception handling
  • @dianaoigo for their addition of the new attribute flags API
  • @jonahbeckford for their fix of the windows compatibility

We’d also like to thank the OCaml Software Foundation who has been funding my work on this release.

Looking for Ideas for the Community Page at OCaml.org

Shakthi Kannan announced


As we continue to make great strides in 2024, we would like to support and grow our OCaml community!

In this regard, we need to overhaul the OCaml.org Community page, similar to how we have revamped the Package Overview page and the Learn Area based on your feedback.

What are the specific topics or features that you would like to prominently display on the Community landing page?

Are there specific resources, links, and content that you find valuable?

Show us any pages from other communities that you find are well done, and tell us what you think about them.

Please share your thoughts and suggestions for the Community Area page.

Let’s discuss!

Profiling OCaml programs

Louis Roché announced

Ahrefs recently had to do some profiling to investigate build times. @jchavarri used this opportunity to regroup different techniques in a single document, which was then turned into this blog post.

The post focuses on dune, as it was our target this time. But it applies to basically all ocaml programs.

We hope that it can serve as a starting point if you ever have to conduct similar investigations.


Monadic programming tutorial

Frédéric Loyer announced

I have typed a little monadic programming tutorial.


Hope this helps. Your comments are welcomed.

Tutorial on GADTs

Raphaël Proust announced

I’ve written a three-part tutorial on GADTs. The first part shows the very basic. It is intended for anyone who already knows OCaml but hasn’t written a GADT before. The second part is a collection of different techniques you can use when making your own GADT. It is intended as a follow-up of the first part or for programmers who have written GADTs before but feel like they still have things to learn. The third part is a gallery of GADTs found in the public OCaml software ecosystem. It’s intended for anyone who wants to see practical-use examples.

I intend to expand the gallery of GADTs (part three). Let me know if you have suggestions.

Caqti/ppx_raper tutorial

Frédéric Loyer announced

I propose the following tutorial


It is about Caqti and ppx_rapper use. The tutorial also uses the Lwt_result monad and its (let*) binding operator. This avoid any explicit error handling.

I hope this will be interesting, and will be glad to get some advice to improve this first copy.

Perhaps I should add a section about processing a list of queries (ex: a query returns a list of item and we want to execute a new query for each row)

Re: dune 3.13

Etienne Millon announced

And dune 3.13.1 is available with the following fixes:

  • Fix performance regression for incremental builds (#9769, fixes #9738, @rgrinberg)
  • Fix dune ocaml top-module to correctly handle absolute paths. (#8249, fixes #7370, @Alizter)
  • subst: ignore broken symlinks when looking at source files (#9810, fixes #9593, @emillon)
  • subst: do not fail on 32-bit systems when large files are encountered. Just log a warning in this case. (#9811, fixes #9538, @emillon)
  • boot: sort directory entries in readdir. This makes the dune binary reproducible in terms of filesystem order. (#9861, fixes #9794, @emillon)

Other OCaml News

From the ocaml.org blog


If you happen to miss a CWN, you can send me a message and I’ll mail it to you, or go take a look at the archive or the RSS feed of the archives.

If you also wish to receive it every week by mail, you may subscribe to the caml-list.