OCaml Weekly News

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!)

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

• Repo: https://github.com/yawaramin/dream-html
• API docs: https://yawaramin.github.io/dream-html/dream-html/Dream_html/index.html

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]

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.

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.

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.

Greetings!

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!

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.

https://tech.ahrefs.com/profiling-dune-builds-a8de589ec268

I have typed a little monadic programming tutorial.

https://www.sinerj.org/~loyer/monadic_programming/monadic_programming/index.html

Hope this helps. Your comments are welcomed.

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.

I propose the following tutorial

https://www.sinerj.org/~loyer/caqti_ppx_rapper/caqti_ppx_rapper/index.html

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)

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)

Here are links from many OCaml blogs aggregated at the ocaml.org blog.

• OCaml: Introduction
• Improving OCaml.org to Provide an Engaging UX and Trusted User Resources