Jon Ludlam's blog

Summer notes

2026-09-08T00:00:00Z

Getting back to writing notes! Here's a dump of what's been going on. More detailed write-ups to follow at some point!

First class docs

The notion of making docs a 'first class' feature of OCaml seemed pretty important to me, so I applied to present it at the OCaml Workshop, and it got accepted! I was really looking forward to going and discussing with everyone important in OCaml development how to progress this, and then life intervened and I found out that my daughter Skylark had a rather major surgery scheduled for exactly the day of the workshop. I stayed here to be with her, and happily it all went well. Meanwhile in France they played a recording I had made of my talk, and Paul Elliot answered questions. The slides are here

It has managed to start a discussion, so we'll see where that ends up.

Odoc fixes

As part of this, I needed to make sure that installing the odoc files wasn't going to be just a massive waste of space. An initial investigation showed the odoc files were roughly as large as the entire lib directory - so installing them doubled its size. This was clearly unacceptable, so I spent some time looking at saving space. We'd not even looked at this before, so I was pretty confident we'd find some good space savings.

There were 3 straightforward changes that made a big difference. Firstly, and most obviously, enabling compression. This was straightforward as OCaml itself has been compressing files since 5.1.0. Secondly, removing some optimisation in the representation of Identifiers that's become redundant since it was put in. This was a larger PR, but mostly mechanical. The one moderately interesting part of it was modifying the hash function of the identifiers to ensure we always traverse right to the Root constructor in deeply nested identifiers. The last fix was just in the AST representing comments. In it, a paragraph is an inline_element with_location list - a list of inline_elements that each have a location - a start and end point. The inline_elements themselves are [Word of string], [Space], [`Code_span _] and so on. That means each word and each space has its own location recorded in the AST. This seemed a big waste, since we never (ish) use them, so the third optimisation was just to join the words and spaces up into one entry. With these three in place, the space usage went down by 6-7 times to a much more reasonable size.

While in an upstreaming mood I've also pulled out several other optimisations that were made for handling OxCaml-produced heavily templated code.

Odd

Odd is my tool to simulate the "First Class Docs" world by installing odoc files with odd_driver (a mini fork of odoc_driver) as an opam hook. I thought I might try getting an AI agent to use it to help write some OCaml programs, and then it could critique the tool and suggest improvements. This turned out to be very useful. I set up a few tasks that required using the Jane Street libraries, as these tend to have mli files that are less easily read than many others in the OCaml ecosystem. Not only did it end up suggesting a number of useful bugfixes and improvements to odd, but it also found several bugs in odoc that I submitted fixes for. A fix for extended opens, a fix to prevent hidden items leaking into the docs, some inconsistent strengthening of module types. It also spurred me on to fixing a long-standing issue - how to handle a hand-written wrapper module that doesn't expose everything.

I was using a mix of Claude and DeepSeek-V4-Flash-0731 for these tests - the latter running entirely locally on my laptop with antirez/ds4. For the agent for DeepSeek I used pi.dev. While being slower than Claude, this model was perfectly capable of passing each and every test, which I found quite amazing.

The obvious next step was to see whether odd was actually helpful to the agents. To this end I changed the tasks to have 3 different prompts - one with just the task, one suggesting to look in the opam lib dir for the mli files, and one suggesting using odd. I set these all going, using openrouter rather than ds4 for speed. I've not completely analysed the results yet but it does seem that odd isn't significantly helpful!

Docs CI

I switched over ocaml.org to the new docs CI running on dill.caelum.ci.dev. This is using "day11", which is a variant of Mark Elvers's day10. The switch-over was relatively smooth, but there were two issues. The first was that the rendering of package-wide markdown docs disappeared, leading to a PR to revert the switch. Fortunately I was able to fix it and rebuild everything within a day, so the PR was closed without merging.

The second issue was a bit more insidious. The docs CI machine, dill, has a layered storage solution - a pair of mirrored 7TB spinning disks with a 2TB SSD dm-cache in front. At that point I was doing manual pruning of the old layers, and it had got a bit full. I triggered a cache prune at roughly the same time as a big rebuild came in (within an hour or so, at least), and this ended up completely filling up the 2TB dm-cache disk. This caused the whole machine to grind to a halt for a few hours.

The way it's supposed to work is that when someone requests a documention page on ocaml.org, the ocaml.org server requests a json representation of the page from dill, then renders that as the body back to the client. In order to make this as fast as possible, it's not the ocaml-docs-ci server that actually sends the page back, but a caddy server sitting in front of it. This works nicely most of the time, but when the machine was busy with flushing the dm-cache blocks it was taking quite a long time to respond to these requests. This led to the ocaml.org server running out of fds and crashing!

The two-fold solution was firstly to increase the fd limit on the ocaml.org server, and secondly to stick the layer pruning in a cron job that runs in the middle of the night. That keeps the size of the layers used in the docs down to around 1TB, and so we shouldn't run out of cache blocks.

Monitoring

The old docs-ci machine was quite difficult to maintain. It was hard to see what it was doing, why it was doing it, and to get to the relevant logs. As a consequence, the new incarnation had much more of a focus on being able to figure out what's going on. This manifests in two ways - firstly being able to browse the packages, the build and docs logs and classifying failures correctly, and secondly by having a much more useful grafana dashboard telling me how healthy the machine is.

The interesting thing about this dashboard is that Claude created it entirely, and via config files rather than driving the UI. It's not perfect - the 'Uptime' graph is a little odd - but it certainly shows me almost everything that's interesting. The screenshot only shows the top of the dashboard - there's a lot more if you scroll down.

OxCaml VMM

A new project. I had a catchup with Dave Scott and while reminicing about the good ol' XenServer days he mentioned the project libkrun. An OCaml version of this sounded like fun - and an OxCaml one even more so, as we should be able to use some of the OxCaml features to make it really quite efficient.

It's very early days for this now, but it's capable of booting a linux VM on my macbook and on my Raspberry Pi 4. It's already a useful playground for looking at how modes can help us write idiomatic looking code that doesn't allocate. Right now there's nothing to be gained with the multicore modes, but that may happen as I move beyond one vCPU. I'll do a bit more of a write-up of this soon. Code is here

A bit of fun

While I was waiting in the hospital I needed something to take my mind off the surgery. I can't remember what got me on this track, but I was thinking about old Amiga demos, and I remember one in particular - ARTE by Sanity that was spectacular. On effect I enjoyed particularly was a texture mapped sphere. It was something I had tried to write myself back in the day, involving, if I recall correctly, a lookup table that was created using AMOS basic. I wondered if Claude could take a look into it and figure out precisely how it worked.

It was fascinating watching Claude work at the problem. It pulled down a copy of amiberry, which exposes a socket over which you can control the emulator. I had bought a copy of Amiga Forever a few years back so I had all the kickstart roms and workbench disks around, so it used them, downloaded the ARTE adf and booted it up. I then paused it at the effect I was interested in, and Claude interrogated the state of the VM over the socket. It then searched around and found a copy of the Sanity Operation System which matched was was used to assemble the demo, in particular figuring out where local state was stored. It took quite a while to figure out the bitplane trickery, and there were several round trips where the output was messed up in various ways, but it got there in the end.

Of course, most of the interesting bits about the effect is that it worked at all on the Amiga hardware, and we miss out on all that in reproducing in modern OCaml, but nevertheless it's quite fun to see it running!

First Class Docs in OCaml

2026-06-22T00:00:00Z

The quality of reference documentation available in OCaml for libraries has improved enormously over the past few years. Docs are now built for every package in opam, hosted on ocaml.org, with search, source rendering, inline media, a navigation sidebar and many other features.

However, it's still not the case that documentation in OCaml has what I'd call "First Class" status. What do I mean by this? Well, let's give some examples of what I think it should look like.

High quality API and package documentation should be installed with every opam package, meaning that all build systems ought to be able to do this, and that docs should be checked by CI systems.
Editors should offer completion in docs, highlight any errors when you're editing with clear actions to fix them, and display rendered docs natively.
It should be possible to read and search through the documentation easily, through your IDE and in the terminal. So why aren't we there yet? What needs to be done? Let's first start by explaining a little about why it's harder in OCaml than in many other languages. If you already know this, skip to the what to do about it section!

Why it's tricky

API docs in OCaml are written using specially formatted comments, much like they are in many other languages. We usually write our documentation in mli files:

type t
(** The docs for the type [t] go here *)

val wrangle : t -> t list
(** Here we can talk about [wrangle] and how it relates to {!t} *)

What makes OCaml more tricky than many other languages is OCaml's module system. A simple example is this:

type t
(** Here are my docs for [t] *)

module TMap : Map.S with type t = t
(** This module is a map from the standard library *)

module TMap is a module found within our module, containing lots of types and values that all need docs, but its definition is in another module - in the standard library in this case. The standard library isn't particularly special, and functors aren't the only way this can happen, so to produce the correct docs we need to have access to the docs of all of our dependencies, just in case they turn out to be necessary to fully document our own interfaces.

The information we need is all in the typedtrees - the .cmt and .cmti files - of our own files and all our dependencies, but there's a non trivial amount of work that goes into processing these, so we effectively compile those .cmti files into .odoc files to make this process efficient.

The upshot of this is that in order to produce fully processed docs for any particular package, we need to have the .odoc files for all of the dependency packages available somewhere.

The approaches that work today all build the docs after the package has been installed, which is how tools like like odig and odoc_driver work. But what would it take to ensure it happens at package install package, and for all packages?

What to do?

Odig exists, of course, and it does a great job of building docs when you ask for them. But it's an optional install, and the odoc files it builds are squirreled away in its own var/cache/odig directory, and not necessarily up to date, by design.

The key thing is to define the standard place in the opam tree where the odoc and odocl files will live, and ensure that packages are responsible for doing this. With this in place, we simply know that, if a package is installed, its libraries will have their compiled module docs installed and its package docs will be installed in their appropriate places. This gives all other tooling a reliable source of .odoc/.odocl files for whatever they need them for.

Build system and CI integration

The most-used developer tool to build docs today is dune, and it's woefully short of where we'd like it to be. Without the odoc files from other packages the docs it builds are full of unresolved links and unexpanded modules, and the error messages it gives are almost useless.

We're working on a "local" fix for this, meaning that dune will know how to build docs for the dependency packages. The docs produced are far better, the error messages much more useful and it will greatly improve the standard of self-published docsets and what's published on ocaml.org. However, it would be far better if the docs for the dependency packages were installed already. Then dune would only have to concern itself with the docs of the workspace packages, and the implementation would be simpler.

For a truly first-class docs experience, all OCaml build systems would have to be able to build docs themselves. We've got quite clear instructions on how to drive odoc at a low level, but we need better instructions at a higher level, for which the main source of info right now is the reference driver.

As a stop-gap measure, we could tweak odoc_driver and use it as a black box for doing the job. We can use this for all packages that don't yet install their own docs as a post-processing step after the opam build. Clearly this would be significantly less developer friendly than integrating it properly with the build system. For example, it wouldn't be able to do incremental rebuilds.

Once we've got the build systems working, checking things with CI would be pretty straightforward. Even before we're at that point, we could wire up odoc_driver which already provides reasonable error messages.

Editor support

The main additional features I'd like to see in editors would be:

Tab-completion of references. With all the odoc files installed this would be easy enough, but I'm not sure if it would be quick enough right now. If it isn't, it should be straightforward enough to add in an index.
Error reporting. This is a bit trickier, but is not dissimilar from how Merlin does its work - we would rely on the build system to build the odoc files for the rest of the project, then have something that can report errors from a buffer.
Preview of docs. When incremental builds of docs are available, this should be straightforward. The dune rules we've been working on already can do this.

Search

And, of course, there's search. We currently have search in odoc output powered by Sherlodoc. However, Sherlodoc is focused on searching of API functions, and doesn't index mld pages at all. We can augment sherlodoc with search powered by other mechanisms, such as BM25 or using LLM embeddings, as we demonstrated last year, to provide a more holistic search function for package documentation.

So now let's focus on how we get to the point where all the odoc files are installed.

The path to success

What gets installed?

First we need to define what actually gets put into the filesystem. The docs we've got on driving odoc are great at the level of individual commands, but not anything with a ecosystem-wide view on actually how to lay out the files, where to put package docs vs library docs vs rendered source files, what we definitely need installed, and what's more of a convenience file that's generated while we're building docs.

The starting point for this is probably what odoc_driver produces as part of the builds for ocaml.org. We can easily see what these are by just running odoc_driver and supplying output paths for the intermediate files. For example, odoc_driver --odoc-dir _odoc --odocl-dir _odocl. These files are more-or-less what should be installed somewhere in your opam switch directory.

Having figured all this out, we then need to figure out how to make that happen. Let's first consider the ambitious plan - one that might take some time to do.

The ambitious plan

Let's upstream the necessary parts of odoc into ocaml/ocaml!

If we want packages to install their own docs, and we need odoc available to do that, then we should arrange for odoc to be part of the first package that needs docs - and that would be the compiler itself. Otherwise, the way we work with stdlib will always be different from many other packages.

We don't need all of odoc, just the parts that are essential for other packages to be able to produce their docs correctly. So essentially we need enough to run the compile and link phases, and at least one output format.

All of the tooling for additional uses - search, html output, completion, and so on, can be packaged up in additional tools packages. It's not completely clear exactly where to draw the line, so we'll have to figure that out as a community.

The ocaml repository already contains ocamldoc which is used to build the manual for OCaml. We've had support for building the manual with odoc since OCaml 4.13, so replacing ocamldoc with odoc isn't too far of a stretch, particularly as odoc has really been the standard doc tool for OCaml for many years now.

The additional quicker plan

The ambitious plan will take a while to sort out, but while we're working on it we can explore what life would be like with this all working using a shortcut. If we have a tool that can install the odoc files on behalf of the packages without having to actually modify the packages to do it, we can work on some of the integration tasks and try them out.

Odig obviously does a lot of this already, but it's missing quite a few of the modern odoc 3 features. Odoc_driver is closer to what we'd need, but we need a couple of tweaks to make it really fit.

We can then execute this package-by-package after they're installed, and if we do this using opam's post-install hooks, we can simulate what it would be like had the packages installed the docs themselves. It doesn't quite work, an obvious example of which is that opam's view of what the packages have installed won't contain the odoc files. But it's certainly good enough to try out things like CLI-based doc viewing, or completion of references.

With these changes, the "energy barrier" to writing good docs for your OCaml packages will be significantly reduced, and the ubiquity of the docs in all opam switches will result in tools and workflows that really make the most of this enormously useful, but currently underused resource.

Weeknotes 2026 week 24-25

2026-06-22T00:00:00Z

I have now finally finished almost all of the end-of-term duties, incuding marking of 128 Foundations of Computer Science exam questions. Phew! It ended up being quite a week, with the unwelcome additional burden of having my car written off due to a minor prang.

The main things I've been working on have been finalising the new ocaml-docs-ci implementation, and working on a plan for "first class docs" in OCaml. The latter I've written up here. The former is currently running on a rebuilt https://dill.caelum.ci.dev, building docs for all versions of all packages.

First-class docs

I've written up a post on what 'First Class Docs' in OCaml might mean, and in parallel I've made a little tool to see how it feels. I've not put it on the main post, but I'll share a little video of it here:

It's a tiny tool that auto-builds docs for your switch, keeping them up to date automatically as packages are added and removed. It's got sherlodoc-based search, it can show docs in markdown in the terminal for any item in any package, completion of odoc-style references, and the completion is integrated with zsh so you can do `odd doc Odoc_<tab>` and it will show you sensible completions.

Next step is to create a skill for LLMs to use this tool. I'm pretty sure they'll find it very helpful!

Source is here: https://tangled.org/jon.recoil.org/odd

Docs CI

The work on docs-ci was not terribly exciting, but should be leading to a switch over in the next few weeks, once I'm happy that the service is more stable than the current one (which isn't a particularly high bar).

The new way of running meant fewer docker containers, so the deployment had to be changed
I added a Caddy webserver rather than nginx, and updated the configuration so that it can serve multiple profiles
I've only enabled the 'quick' profile and the 'full' profile for now - the other two I've been using are 'oxcaml' and 'odoc-master' that do the obvious things.
I've added a few more bits of info when you're browsing the state - things like the latest commit on the opam repositories being used, a diff view between snapshots, some instructions on what to do when your package fails
Some more minor tidying for "release" I've now left it running for a while just to see how it behaves. It's looking pretty good, though there were a few issues to iron out. The first was to do with epochs, which is a mechanism to allow deployment of new versions of odoc, sherlodoc, odoc_driver and so on whilst keeping the older version "live" until you want to switch over to the new version - the new epoch. The problem was that it was keying the epoch off the full solves of the tools rather than just the versions of the tools themselves. The consequence was far too rapid cycling of epochs, so I had to fix that. The second was that the switch to the new epoch did a synchronous GC of the older epochs, which led to a very long pause. Then the release of OCaml 5.5 turned out to be very useful, as while all the packages built as expected, none of the docs appeared. We have an override in the profile to be able to select the compiler version used to build odoc_driver and related tools, which was set to 'None' to mean 'latest version'. However, in this case, 'latest version' meant 'pin to the latest version of the compiler' as opposed to 'best version that has a solution'. This constraint, along with js_of_ocaml not yet working with OCaml 5.5, meant that there was no solution for the tools, hence no docs! The quick fix for this was to put a pin in place to OCaml 5.4.1 and the docs popped right out.

Some info: A full build took about 12 hours. This is on roughly the same hardware as the current docs ci, where it takes the best part of a week to do the same, so the day10/day11 architecture has made it much faster. Each snapshot builds about 17600 packages, in about 31,000 build layers, and 31,000 doc layers. The total space for one complete snapshot is on the order of 1.1Tb. The OCaml 5.5 release rebuilt most of the packages, so we're currenly up to about 2.3Tb of storage used.

Week 23, June 2026

2026-06-08T00:00:00Z

...and previous weeks.

Current topics

General odoc directions

While docs are, in general, better than they were a few years back, it's definitely not "done". I've been considering what life would look like if docs were "first class". I'm writing this up, but for now I'll at least point at the first few bullet points.

High quality API and package documentation should be installed with every opam package. This implies that every build system is capable of producing them, and CI should check them.
Editors should offer completion in docs, highlight errors when you're editing, and offer a way to display docs natively.
Searching for docs, in editor or via the CLI, should be straightforward and useful. The last point is particularly useful for LLMs.

Obviously there's a lot of work required here! I'm currently thinking about a pathway that gets us most of the benefits ASAP, with a longer term outlook of doing it without "hacks". I'd like to get the 'ASAP' tooling published so that other people can have a go and get some of these benefits.

.cmt vs .odoc

As part of this, I wanted to take a good look at the cmt/cmti format to see what's in there and why, and where the odoc file format differs. They both are based on the underlying source tree, so it's quite reasonable to ask where the similarities and differences are, especially if I'm suggesting installing odoc files as well as cmti!

I realised in doing this that while we've got docs for users of odoc, we've not got great coverage for developers. So I've spent some time this week working on this. I initially started writing this for this blog, but quickly realised that it really should be in the odoc repo, so that'll be coming soon. I'll try to get this done without spending too much time polishing it.

Idents vs Identifiers

In the interests of seeing closer parallels between odoc files and cmt/i files, I got Claude to spend some time investigating using local idents instead of identifiers in the odoc files, and switching to identifiers when writing out the odocl files. This would remove one big source of difference between the formats, and potentially make the code more easier to read for people used to OCaml's module implementation. A side benefit could also be an improvement in performance, as we spend quite a lot of time converting between these two types as odoc runs. Unfortunately this proved a little too tricky for Claude and while it made some progress, it seems I'll need to spend a lot more time describing the change, and/or working through it with more supervision.

OCaml Docs CI

This has been dragging. So I'm currently on a sprint to get this sorted by cutting out any nice-to-haves. It's already in a state where it's better than current ocaml-docs-ci, so my focus now is on doing the absolutely necessary bits to have it in a sensible state for ocaml.org. These are:

Deployability - fix up the docker files / ansible / ocurrent-deployer such that getting a new version running is as simple as pushing to github.
Wire in the epoch management mechanism. This has proven invaluable with the current ocaml-docs-ci, and was relatively simple to put in place.
Ensure docs are good enough for others to debug/maintain/fix it. So the other neat bits of it are deprioritised - building oxcaml packages, building latest odoc master branch, local override repositories, etc. Let's get it out and being used so it's no longer dragging me down!

Dune Odoc rules

Paul-Elliot and Arthur have been doing a good job cutting up my branch into smaller chunks, but it seems to have hit a got a bit mired in the mud. There are a few good small commits, and a few have been upstreamed, but there's going to be a big chunk that's still quite hard to put into manageable commits. I'll be looking over what's been done so far to see if I can figure out a pathway forward.

Exams!

The exam for the Foundations of Computer Science course I lectured this year is coming up this week, so I'll be spending a lot of time marking for a while!

Weeknotes May 2026 weeks 18-19

2026-05-11T00:00:00Z

Over the past two weeks I've been mainly wrestling with odoc.

I made a release of odoc - 3.2.0 - and a PR to opam-repository. In parallel, I also just managed to make an ocaml-docs-ci job that tracked the master branch of odoc. I was pretty horrified therefore to see a glaring error in the docs build of base.

It turned out that one of the patches we made for OCaml 5.5.0, to support modular explicits, had an issue. It caught me by surprise because I didn't think that anything already existed that uses this, but in fact the new constructors in the AST are being used by pre-existing language constructs, so even without source changes we were exercising the new logic. This turned out to be quite useful as it showed that there was some missing transformations in the code causing a hard failure. Fortunately the fix was .

With this success of the new docs ci, I thought we could do some more serious runs, so I set a job going building docs for the latest version of everything in opam using the master branch of odoc. After getting this running the following few days was spent sorting out the issues that came up - and .

The second here showed up a problem in the fix for . In that, as I wrote about previously, the fix was to rewrite module types being included without inline module substitutions. The code that did that effectively rewrote the following:

sig
  ...
  module Foo := Bar
  ...
end

sig
  module Foo = Bar
end with module Foo := Bar

The problem that the docs ci found was an instance that looked more like this:

sig
  module A
  ...
  module Foo := A
  ...
end

and of course, in this, we can't simply do the above transformation as module A is only defined within the scope of the signature, so we can't reference it from outside.

A few months back I had rewritten this code so that rather than going through the Fragmap functions it directly used a substitution, but I hadn't quite completed this. It seemed a good opportunity to dig it out and give it a whirl, resulting in a nice patch. With the power of the new docs CI I set this going, and while it fixed that issue, it exposed another. At this point I felt that it was getting a bit hairy for a last-minute fix, as we needed to release odoc rather quickly for OCaml 5.5 support. So I shelved that plan, and instead went for the rather less dangerous fallback of doing nothing when we hit that pattern. The thought was that issue is relatively rare, but the fragmap fix is applied to all includes. The 'local substitution' pattern is also rare, as it was only a few packages that showed the error when I did the full docs run. So the chances of hitting both we can expect to be even rarer! We went with in the end.

The other small defect I found was an interesting one. There is an with odoc related to building docs for colibri2. What I happened to notice with the docs ci build was that the docs build was succeeding. After a bit of debugging I finally figured out that this was due to missing dependency libraries during the build. Without these, it failed to do some expansions, which meant that it didn't hit the problematic case. This led to , and colibri2 is back to failing.

Thanks to panglesd's quick review, these were merged, and we were finally able to release 3.2.1 and put it .

Docs CI and universes

Docs CI has always had this concept of consistent "universes" of packages which are layered together. As a simplified example, imagine one universe for each version of the OCaml compiler. Then there are several versions of findlib, each of which can compile with each version of ocaml, so now we have n*m possible universes. Obviously this would lead to a combinatorial explosion if we wanted to have every possible universe, but in practise there's a huge amount of overlap, even when we're trying to build every version of every package. So we exploit this by having a triple that defines every build - the package name, the package version, and a hash representing the dependencies of the package.

A core principle of these universes is that the docs produced are also consistent. For example, if your package was built with OCaml 5.4.1, no matter where you click, you'll never end up on a package that was build with a different version of OCaml. Similarly for every other dependency of the package whose docs you are browsing. You will always stay within the dependency universe.

When we introduced "forward links" in odoc 3.0, we retained this. These forward links are links from a package's docs that should go to a reverse dependency of the package. For example, odoc's docs link to odoc-driver and odig, as examples of tools that use odoc. This is a straightforward extension of docs generation if all involved packages are already installed, as odoc has had split compile and link phases since very early versions. Compilation must be done in strict dependency order, as when odoc processes a cmt(i) files it requires the odoc files of dependencies. In contrast, linking only looks at odoc files, so once we've computed all of these we can link in any order we wish.

The approach taken in ocaml-docs-ci is different. Because we want to avoid processing packages more than once, we process each package individually. If a package has no forward links, we can do both compilation and linking for that package in one go. If package "a" has forward links to package "b" that depends upon "a", we have to:

1. compile the odoc files for package "a", 2. compile the odoc files for package "b", ensuring that the odoc files of package "a" are available 3. link the odoc files for package "a", ensuring that the odoc files of package "b" are available 4. link the odoc files for package "b", ensuring that the odoc files of package "a" are available.

This is obviously more complex than if there were no forward links, as then it would be just a two step process - compile and link "a", then compile and link "b". The only complixity is in ensuring that the odoc files for "a" are available when doing the compile and link for "b".

A further wrinkle is that your forward links might require packages with version constraints. For example, odoc might have links to documented features in odoc-driver that are only in recent versions. Even worse: there might be multiple versions of "b" that all use the same version of "a", and here we hit against the principle outlined above; that no matter where you click you never leave your universe. If there are multiple versions of "b" that link to the same version of "a", then when you click the reverse links, you must end up back on the same "b" you started with. That means there must be multiple different versions of the docs for "a", even if they're all built with the same set of build dependencies!

So if we're being as efficient as possible, we need to divorce the build universe from the docs universe. That way we only need to build the package "a" once, even if we build docs for it multiple times. Currently day11 doesn't do this, and is inefficiently doing multiple redundant builds for some packages. This doens't affect the output as it's the docs universes that are important there, but it does mean it's wasting resources.

oi docs

All of which brings me on to oi. I had a very useful discussion with Anil on whether we need to bring all of this complexity into oi to build docs there. When you're working on a package in oi, whilst it manages many different universes, it will only instantiate one for your package. Therefore we don't need to worry so much about staying in the same universe - there can be only one.

So he suggested doing late binding of the forward links somehow, to enable building docs alongside the standard package build. The forward links would be unresolved, but we could arrange for the link to be resolved once you installed the package to be linked to. This could be done in a variety of ways. One thought I had was that I could use a branch I'd been working on a while ago which simply enumerates the possible link targets in an odocl file. The thing that makes this achievable is that we're only talking about cross-package references, so a lot of machinery that exists within odoc is unnecessary. We'll only allow canonical reference, and scoping isn't a problem as they will all be fully qualified references.

I'll be working on making this work for the rest of this week.

Random ideas

Some random ideas I had:

Package API diff

It's always been a nice idea to use the data we generate in docs CI in more creative ways than just producing the docs. A fairly obvious idea is to generate diffs to show what's changed in between versions of the packages. However, this was always a bit problematic because your own package doesn't necessarily uniquely define your API signatures. This is, of course, the whole reason we produce multiple universes of docs. However, in odoc 3.1 we added a neat feature that was intended to help you by only showing errors when they exist in your own packages, which worked by keeping track on a signature level of the package from which the signature came. What I realised is that we can use this info to discard diffs between package version builds so that they only show what's changed in the package being queried, rather than differences due to your dependencies.

A quick example. Odoc has several maps such as Component.ModuleMap that are constructed from the standard library functor, and therefore the elements in them you can see at that link have various 'since' markers - but those all refer to the OCaml version, not the odoc version, even though these are odoc's docs. If we're trying to find the difference between two versions of odoc, we might observe differences in these just because we happened to compile the two odoc's with different compilers. Using the info put in for the warnings would eliminate this.

Fuzzing odoc-parser

We ought to fuzz odoc-parser. There are some nice tests in there - mostly expect tests - but a proper comprehensive fuzz will definitely show up some issues, as it's a hand-rolled parser. We spent some time a while back building a menhir parser, but the error paths were very hard to get working as well as the current implementation handles them. Fuzzing could help strengthen the case for using the menhir parser.

Thomas has a neat fuzzing skill for Claude that he's been using to great effect with his protocol development work, so I'd quite like to take a look into using that to give that a whirl.

Weeknotes 2026 weeks 16-17

2026-04-28T00:00:00Z

A two week update this week. Most of this fortnight has been spent on different sides of the same problem: getting OCaml documentation into a state where an LLM (or a human) can actually rely on it — search, packaging, performance, and infrastructure.

Docs and LLMs

It seems fairly obvious, but having docs available for libraries is very important for LLMs to be able to use them effectively, especially if they're new or private. There have been various papers on the subject — for instance the 2022 paper on tool documentation and the more recent work on the importance of example code — as well as our own contribution to the OCaml workshop last year.

Examples in OCaml libraries often live in mld files, and the correctness of these can be automatically tested using mdx, which works well on mld files.

Sherlodoc deliberately skips mld files, because plain English in mld pages drowns the API hits — when indexing was originally enabled it ended up polluting the API results too much, with generic text appearing way too often. Sherlodoc doesn't do any of the interesting stemming or other BM25-style weighting, so as more mld content lands in packages we'll likely need to investigate a hybrid approach to searching the docs.

Oi!

Anil's just shipped a neat new tool in OCaml land — oi!, built on top of day10 and relocatable OCaml. This is a really neat little tool that you can use to run OCaml tools and scripts without having a dedicated opam setup.

As I've been getting my Claude-built day10 successor, day11, into shape as a replacement for the guts of the current ocaml-docs-ci, I thought I'd check to see if the libraries I'd made could work as a drop-in for the d10 part of oi (Anil's vendored copy of the relevant bits of day10). This indeed worked nicely, without huge impact on the rest of oi (aside from excising a chunk of it, of course).

Next step is to see if we can get decent doc support into oi. It'd be great to be able to run oi doc or oi doc search in a project and have accurate docs pop out. More on this to come!

Odoc performance investigation

A particular problem with getting the docs to 'just pop out' is that some docs take a long time and too much memory to build with odoc. So much so that the Github Action workflow that generates them can just die, particularly when trying to build the docs for the oxcaml branches of base and core. So I've spent a little time investigating this over the last couple of weeks, and made some quite significant progress.

Headline figures on my laptop: wall time 549 s → 474 s (−14%), total allocation 381 GB → 230 GB (−40%), peak RSS 2.00 GB → 1.81 GB.

Particularly bad for odoc was an include-expansion explosion: a single source line in container_intf.ml was being walked 10,777 times during html-generate, because each ppx_template monomorphisation produced its own Include whose expansion nested further Includes. I had previously noted this issue and tackled the most awful of the problems, but there was more to fix!

The includes are effectively a workaround for the lack of layout polymorphism in the current oxcaml compiler. A quick investigation showed that of the 155,828 doc comments in container_intf.ml there were only 33 unique strings, once the ppx_template duplication was de-duped. Memoising the parsing of these led to a substantial improvement.

In addition, many of the includes end up flattened in the resulting HTML due to their module-type being either a signature or pointing at a hidden item. Includes come with a fair bit of overhead, so rather than flattening them at the point we're generating the HTML, we can spot this pattern and flatten them much earlier in the process.

The single biggest html-generate win was a one-liner. segment_to_string was doing Format.asprintf "%a%s" where the %a formatter just emits "<kind>-" or nothing. A direct pattern-match killed ~60% of html-generate allocation on stdlib, ~50% on core.

I'll tidy up these patches, double check that they don't affect the output, and see how much of an improvement they make on Anil's oxmono repo.

Day11

I mentioned last time about replacing the innards of ocaml-docs-ci with the day11 libraries. This has worked out really nicely. The shape of the resulting tool is that we've got an ocurrent pipeline that watches the opam-repository on GitHub, and triggers the day11 build when it notices a change. Each layer corresponds to an ocurrent job. On top of the normal UI I've added in some pages that make it easier to spot emerging problems in the docs build. My ultimate plan is to put an LLM in charge of this so it can watch the status of it every day, and then let me know if it thinks I need to do something!

Docs CI showing the status of the current "snapshot"

Improved site

I made some small improvements to the site too. I added a @figure plugin, and a margin notes plugin {&margin Margin notes look like this!} , and added tags to my pages. You're already reading the result — the Docs CI screenshot above uses the new @figure plugin, and you can see the margin notes.

Until next week!

Weeknotes 2026 week 15

2026-04-14T00:00:00Z

Once again, the docs CI went down. This time, something had scribbled over the docker partition and so we needed to do a full build from scratch. Fortunately the docs themselves were not in a docker volume and so we didn't have to rebuild everything to get the HTTP server up and running for ocaml.org. However, we did have to set a full build going so that we can build docs for new packages.

This keeps happening, and is very annoying! So, that brings me onto the next topic: day11.

Day11

I've posted multiple times about Mark Elvers' day10 project. For me, it was an obvious extension of this to get it to build docs, and, as with most of my work recently, I set Claude on the task. However, Claude failed to integrate it nicely into the codebase. Taking a closer look at day10, it's a specialised tool that does its thing really well, but isn't built in a way that makes it easy to adapt in the ways that the docs needed. Clearly separating the AI generated code from the hand-written code is very important, so rather than going that route, I decided that I'd try to build a more general day10 with Claude - day11!

It's already at the point where it's been able to build the docs for all packages in opam-repository relatively quickly. Running it on dill, which is roughly equivalent to sage, where the docs are currently built, it takes about 6 hours or so to build everything, where sage with ocaml-docs-ci takes several days.

Some intriguing directions we might take this in:

It's a generic build plaform for opam packages, therefore could possibly be used for easily executing binaries from opam packages.
It can build _itself_ - including new/different dependencies. Interesting for a self-modifying tool!
It's easy to drop into a container with precisely the correct dependencies for any package, so useful for debugging build failures. This is partially implemented already.
We can already provide overlay opam-repositories for testing of new/altered packages One really nice test of whether the organisation of the libraries in day11 is correct is whether we can plumb it into the docs-ci ocurrent pipeline easily, and have the CLI tools for it coexist nicely.

Odoc performance

Running odoc on with some of the oxcaml libraries exposes some critical weaknesses of the current code - in particular performance problems with particular styles of code. We can't build the docs for Anil's oxmono repo with GHA as it simply runs out of memory. I've therefore been investigating some of the more egregious memory problems. I've got quite a few patches already with some good results, but nothing yet that's going to make it into upstream odoc without some more testing.

Other bits and bobs

I had fun hour or so putting together an odoc plugin to replicate the experience of davesnx's parseff site. The plugin is here, and to use it, see my modified parseff repo:

git clone https://github.com/jonludlam/parseff.git#odoc-plugins
opam switch create . --with-doc
dune build @doc

A screenshot of the parseff site produced by the plugin

There are a number of advantages and disadvantages to this. As @davesnx wrote, his concern with the markdown output was to be able to integrate the odoc output seamlessly with an existing site, and it does this very well. However, it's at a cost - we lose links in the API docs, links to source, the source rendering itself, and so on. Whereas the plugin I made keeps all of those nice features, but is still tricky to integrate with a larger site.

Odoc and OCaml Notebooks

2026-04-06T00:00:00Z

As the chief maintainer of OCaml's odoc, I'm required to think hard about its future. What impact will advances in agentic programming, collaborative literate coding, and the dramatic increase in web platform capabilities through wasm and WebGPU have — both on how odoc works and on how we develop it?

I find the best way to explore these topics is to build something, so I've gone all-in on Claude and used it to rewrite my website with all new odoc-built dune-friendly client-side Jupyter-style notebooks as an integral part of it! Those of you that have read this blog for a while will know I've been tinkering with notebooks for a year or so now, and I've had an extremely long-running fascination with scientific visualisation in the browser, but I really wanted to push this hard and see how adding Claude into the mix would work out.

A client-side notebook using TESSERA

It's very helpful to have a specific use-case in mind for the notebooks to guide the exploratory work. This was an easy choice: My group has been spending a lot of time recently on TESSERA, and this provided a perfect demonstration for the notebooks, as it heavily relies upon being able to use interactive maps to choose areas of interest, and to visualise the embeddings and picture the output as map overlays. As well as being a fine motivating example, it's also given me an excellent reason to learn more about geospatial coding, which I've been wanting to do for a while. The specific example I chose to port required adding support for various interactive widgets in the browser-based programming environment, where I'd only previously been able to render static rich content.

Also, inspired by my colleagues' experiences with notebooks, I've been experimenting with the execution model and interactivity to ensure reproducibility, and considering the implications of the FAIR (findability, accessibility, interoperability, reusability) principles of the Fairground paper, which provides a perfect framework of requirements for the odoc notebooks. These more ambitious goals meant a more ambitious approach to the changes.

Despite this, with this rewrite I've thought much harder to ensure that what I've done will fit into the upstream ecosystem. It's now all built using dune with the standard rules I've already started upstreaming, and by using plugins with odoc I've minimised the necessary changes to the core of odoc. While there's work to be done, there's a far clearer path to ensuring this work can be used by everyone.

I've chosen to use OxCaml both for the build environment and the runtime environment on the web. While the choice doesn't make a huge difference in the browser, a longer-term vision is to have a choice of execution environments, and oxcaml for running high-performance numerical code makes a lot of sense.

The implementation work can roughly be split into three parts: Infrastructure and Odoc, the Js_top_worker and widgets libraries, and the actual TESSERA code. Then I've got some thoughts on the implications of the experience, for open source development in general and odoc and the notebooks specifically.

Infrastructure and Odoc

In order to have a fast build cycle I needed an incremental build. Last year I wrote up my experiences writing the dune rules for odoc with Claude. I opened the PR, representing a "feature complete" replacement for the current rules, in that it can completely replace what's in dune now, but doesn't extend the rules for the new features of odoc. Since then we've merged the first part of it, and happily my colleague Paul-Elliot is back from his brief sabbatical working on slipshow to work on getting the rest of it merged.

The incremental build, together with "--warn-error" is very helpful when fixing documentation bugs!

To support my goals though, I've had to extend the rules by quite a lot from that initial work. I've got support for assets so I can put images on my blog posts, support for source rendering so that you can see the code I'm using. There's markdown output for Claude to consume, and sherlodoc native support so you (or your agent) can run sherlodoc queries on the command line. The prefix for all output is configurable, so that I was able to put everything dune built under "/reference", and pass arbitrary options to the various invocations of odoc so that I could specify global defaults like the Javascript toplevel worker and opam repository to use in my notebooks. We've also now got smarter rules that don't pull in as many dependencies as the current PR, so that I didn't have to install any extra packages I wasn't using just to build my own docs.

Sherlodoc database generation and search using dune. Note that the output is rendered with markdown!

Most of these changes will be useful to the wider OCaml community, so it makes sense to try to upstream them. They're also fairly orthogonal to each other, and are obviously dependent on the original PR, and hence they can be made as independent PRs once the big one has been merged.

Odoc

OxCaml support for odoc was contributed by Luke Maurer early on after OxCaml was released. However, this only fixed the build of odoc, it didn't give it any mode or layouts, nor any of the other new features of OxCaml. I asked Claude to look through the way the toplevel prints these annotations and port them to odoc, and that's been implemented on this site. For example, see Base.Uniform_array.length - you can see there the portable, local and contended annotations on the type. If you click on the source link, you'll see I also added some improvements to the source rendering - there are many more links now and we've got the ability to link to source from doc comments and mlds.

Output from odoc, showing the oxcaml extensions

One of the earliest things I did was to give Odoc a new plugin system that has been hugely enabling for building the new features. I'm using dune's site feature for the plugins, which really "just worked". It was very easy both to add the feature to odoc and to create the plugins themselves. Building a whole variety of plugins has also been very useful in testing the shape of the plugin API, and I've made numerous changes to it as I've built them and they expose various problems.

The plugins are activiated in a few different ways. The first is to allow custom tags, e.g. @foobar <content>, a feature of ocamldoc that odoc didn't previously support. The plugin registers handlers for a particular set of tags, and when odoc encounters that tag it calls the plugin to find out what should be rendered. The second way is for plugins to handle particular source-code blocks, e.g. {@baz k1=v1 k2=v2[ ... ]}. Once again when odoc encounters a matching block it gets passed to the plugin to determine what should be rendered.

Let's take a brief look through the plugins I've made.

Admonitions

This is a feature we've wanted to add to odoc for a while - and we have a design sketched out for it.

NoteThis is a "note" admonition. This is more-or-less a throwaway plugin as we'll be doing this "properly" and won't need it. It made for a nice first test though and the functionality is useful and quite important. I've been using it to mark the truly agent-coded libraries where I've not seen the code at all, as opposed to those where I've been far more involved in the changes and I'm slightly more confident in how they work.

The code for this is on tangled, and is a good example of a very simple plugin.

Diagrams

I've got 3 diagramming plugins - odoc-mermaid-extension, odoc-msc-extension and odoc-dot-extension. These were particularly useful in understanding the need to determine the lifecycle of any javascript glue that's required, especially when we're dynamically loading pages like ocaml.org does. And in fact I've put the Mermaid extension to use documenting the issues in the extensions documentation.

Here's a diagram showing the dependencies of my TESSERA libraries:

graph LR
    tessera-zarr --> tessera-geotessera
    tessera-zarr --> tessera-linalg
    tessera-zarr --> zarr-v3
    tessera-zarr-jsoo --> tessera-zarr
    tessera-zarr-jsoo --> zarr-v3
    tessera-geotessera --> tessera-linalg
    tessera-geotessera --> tessera-npy
    tessera-geotessera-jsoo --> tessera-geotessera
    tessera-tfjs --> tessera-linalg
    tessera-viz --> tessera-linalg
    tessera-viz-jsoo --> tessera-viz
    zarr-v3-unix --> zarr-v3

Interactive pages (notebooks)

My previous efforts at creating notebooks involved a separate pipeline to build them, but with this plugin it became trivial to have them built as part of the normal 'dune build' process.

The odoc-interactive-extension uses art-w's x-ocaml to add interactivity to the mld files. The plugin itself is rather simple, really just finding marked ocaml code blocks and outputting an <x-ocaml> element into the HTML. The metadata in the code block is translated directly into attributes in the x-ocaml tag allowing arbitrary parameters to be passed.

I have some more detail on x-ocaml and js_top_worker later in this post.

Scrollycode

The odoc-scrollycode-extension is based on Rodrigo Pombo's work and similar scroll-linked tutorial sites like MLU's decision trees page. I initially had Claude come up with a sketch to show it working, complete with Merlin integration so that types-on-hover work:

One of claude's mockups of the idea

With that as "proof-of-concept" I then built a new odoc plugin so that you can just insert special markup in the source and you get lovely animated tutorials:

The output from odoc's plugin

The screen recording above is from one of the test pages, and currently shows only the incremental building of a module. Rather more interesting is something like Rodrigo's original build your own react page that showcases modification of the source as you scroll though, where it starts with a very simple program and progressively builds in more features. I'd like to extend my plugin to support this soon.

HTML shells

The "traditional" way that you embed odoc output into another webpage, like ocaml.org does, is to output JSON. This works well where you've got a smart server that can read the JSON and render it on demand, but when you're trying to build a static website like the dune rules produce, it's rather less convenient.

The HTML shells extension is part of the odoc plugin system, and allows you to swap out the default HTML renderer for another completely customisable one. I have two plugins that use this system:

odoc-docsite which produces a more modern SPA-style site.
jons-shell which produces this website. The advantage of using these is that it doesn't affect the flow of the documentation pipeline, so there are no changes required to the dune rules for it to produce a very different output. You just install the plugin, add the '--shell <...>' to the dune file or dune-workspace file at the root of your repository, and run dune build @doc.

The second of these plugins is a good example of a bit more of an involved one - see the source code.

X-OCaml and Js_top_worker

x-ocaml is art-w's excellent tool to to add interactivity to any web page. It works by registering a new HTML element x-ocaml that can be used like any normal HTML element, producing a Codemirror-backed editor with a "run" button that will execute your code in your browser using a web worker.

In order to use OxCaml in my notebooks, I needed a stronger separation between the code running in the browser context and the "execution engine" running in the web worker. I switched from Marshal for the communications layer to JSON, as marshal is incompatible between OxCaml and OCaml, which meant that a single frontend implementation can now talk to both OxCaml and OCaml workers running in the web worker.

My fork is using js_top_worker as the library and tool that's used to manage the javascript toplevels. The goal of the tool is to use it to have toplevels or interactive notebooks for every package in opam-repostiory, so it's important that it's careful about what can be cached. As such, the design is that there's a single toplevel worker, and libraries can be dynamically loaded in via #require, just like the standard toplevel. Each library is compile from a cma to a cma.js, and the cmis are also dynamically fetched as they're needed. The worker, the cma.js files and cmis are then hosted alongside META files and an index.

The Toplevel index file:

{"meta_files":
  [ "lib/yojson/META",
    "lib/uutf/META",
    "lib/uri/META",
    ...
    "lib/js_top_worker-rpc/META"
    ],
 "compiler":
   {"worker_url": "worker.js"}
}

One important new feature of js_top_worker that I've built for the notebooks is the ability to use interactive widgets. This requires two-way communications between the main javascript thread and the web-worker backend as we want to be able to trigger changes from both sides. Rather than hard-coding all the widgets that can be made, the design allows new ones using standard OCaml libraries, so you can dynamically load in the widgets you require into your notebook, or even write new widgets there directly.

Each widget either has direct DOM callbacks, or injects some javascript glue code into the frontend, which then communicates between back and frontend using JSON. This layer is mostly "stringly typed" using the widget library. On top of that you can then build more strongly typed libraries like the Leaflet library that give a more pleasant interface. Communications happen in both directions, so code can cause widgets to change, and interaction with the widgets can cause code to execute.

Click to fly, executing via OCaml

Try the demo out yourself here.

Execution model

My colleague Michael Dales wrote about the challenges of balancing interactivity and incremental computation in notebooks, and his post he settled on Marimo. The approach that Marimo takes is to analyse the code and build a dependency graph so that as values are adjusted, any affected part of the computation can be re-evaluated. You can then create values with UI elements attached, and the whole experience is very pleasant.

The "usual" approach to this sort of UI interaction in OCaml is to use an incremental library of some sort, like Jane Street's Bonsai or React. In this way we can build the dependency graph and re-evaluation semantics within the language. In these examples, I've used Note. The interesting wrinkle in this work is that because all interactions are being mediated by js_top_worker, we've got a single place where we could record the interactions that have happened, and then potentially "play them back".

With support for OxCaml, widgets and dynamic library loading, and integration into the docs pipeline via the odoc interactive plugin, it was time to create a real-world notebook to verify that it could be used to do "proper science"!

TESSERA notebooks

One of the most exciting things to come out of our group recently has been TESSERA, a pixel-wise Earth observation foundation model. The code and demos for this are mostly in Python, particularly using Jupyter notebooks. This provided me with an excellent stress test that tied together many of the strands of this work and validated that they could be used together to build something useful. A simple python notebook showing the basic workflow already existed, so I decided to port it to OxCaml, and more specifically to make an odoc notebook. You can run the resulting OxCaml notebook in your own browser, with no server required at all.

The notebook works by first presenting a map, and asking the user to select an area to download the TESSERA embeddings. Once we've got the 128-dimensional per-pixel values, we then need to display them. Rather than simply picking 3 dimensions as our RGB values, we do a PCA computation to choose some vectors for our colours. This is then overlaid on the map by first turning it into a .png, then encoding it as a base64 data URL, and passing it to the frontend to overlay on the map. The user then picks some points on the map, categorising them into arbitrary groups. We then run a knn classifier over the whole downloaded area and finally overlay that image.

I struggled a little with co-ordinate systems, mostly because the distortion if you dont map is fairly small, so it looks pretty good. However, you can see clearly on this image that the A14 (the red road at the bottom left) is a little bit off:

An earlier attempt, showing the distortion

In the newer notebook where I do the remapping correctly, it matches much better. You can see the remapping by looking at the left and right sides of the overlay, where they're no longer quite vertical.

Remapped overlay showing better matching with the map

This version uses the Numpy interface to TESSERA, which downloads the embeddings in quite large (100M) chunks. While it was nice that this worked, it meant it was quite slow to see anything actually happening. I then switched to using the Zarr_v3 format, which is far more efficient, using range requests, compression and better encoding to reduce the bandwidth requirements. This version is here.

This really demonstrated that the approaches I've made with the various different strands of work can all be knitted together in a very useful way, allowing us to bring the strong type system of OCaml together with the ubiquitous runtime of the browser, and using the power of WebGPU to run calculations that can help to change our world for the better.

Implications

I've written (or caused to be written) a lot of code for this project. It's all "open source" in that the code is available, though this is the very minimalist sense of the term. I've both modified other people's code, and written other things from scratch, and pushed everything publicly on the repostiory. It's been a fundamentally different experience than everything I've done in the past 25 years or so of OSS development.

Traditionally with open source software, most people never change the code. The vast majority of people take the code, run it, use it, and get on with their lives, grateful to varying degrees to the authors. A much smaller number of people will make changes to the code. This requires an enormous investment of effort, firstly in learning to code at all and then learning the specific codebase sufficiently well to make a change. A small subset of these people go to the additional effort of trying to upstream the code, and open a PR. At this point, the maintainers of the code now also need to put in a lot of effort to review what's been sent, and engage with the contributor to address any issues with the code. So it's hard work. Why do people bother?

This process is helpful to the contributor as maintaining patches on an open source project is not only work, but unpredictable work. Upstream changes can require you to have to fix your modifications at any time, and those fixes might be anywhere from trivial to completely impossible. Getting your patch upstreamed means that there's a much better chance that whatever it is that was fixed or improved remains that way without further effort.

On the part of the maintainer, the effort of reviewing and interacting with the contributor will hopefully both improve the code, but also effectively enlarge your workforce as the contributor learns more about the project. The more people who know about the project, the easier maintenance becomes.

LLMs have totally upset the balance of these motivations. From the contributor's perspective, the effort now required to maintain your own fork of a project is much smaller, as you don't need to learn the codebase anywhere near as deeply, and you don't have to worry anywhere near as much about maintaining your fork as upstream changes. So it's both easier for there to be code changes, and it's less rewarding to try and upstream them. From the perspective of the maintainer, there may be many more low quality pull requests, and in many cases there will be limited value in trying to cultivate new contributors as the LLMs can't learn directly from the feedback, and the humans guiding the LLMs will know much less about the project as they haven't needed to in order to make the PR.

Where these adjusted values will lead is very hard to predict. Empirically though, I find that I've made few PRs over the last few months, but I've amassed a lot of new repositories and forks of existing repos, and it's been very easy to slip into this mode of working. The effect on non-programmers hasn't begun to happen really, but there will be an effect and it will be profound. I'll know when that moment arrives when my artist-rather-than-scientist family members are using LLMs to alter code - which to them will just be the latest change in MacOS that's happened, but I'll know what's going on.

Attribution

My early purely-agentic commits were all authored by me and co-authored by Claude. This is a lie. Morally, I found I couldn't carry on like this so I've switched now to having the commits authored by "Jon's Agent". My plan is to rewrite the author when I've gone through it line by line, and even then, I feel that Claude ought to be marked as Author and I should just be adding my "Reviewed-by" line onto it. In either case, for a pull request to be made the human in the loop has the responsibility to justify the changes, and therefore has to be totally familiar with both the changes and the code being changed. I'm not at all fundamentally opposed to having LLMs involved in the process of making changes to open source code, but in my experience so far, there's a huge amount of effort that needs to go into it even after you've got working code and tests. I've tested the waters with my dune PR, and have merged a simple bugfix or two to odoc. Even these one-liners needed careful thought and attention before I felt I could make a PR though, and the dune PR took much more effort than that.

Bug-discovery

One thing that I've found tremendously useful is narrowing down bugs. Armed with a repro, setting Claude off to track down issues has been a wonderful time saver. Additionally, asking it to explain the issue in detail with links to the source is very handy indeed. It's not, however, able to discover all bugs, even with a lot of time. When working on the fix for a particularly nasty bug, I found that with the patch applied we'd get a different error somewhere deep in some of Jane Street's async ecosystem. I had a good suspicion of what the problem was given the changes that had been made already, as the code I had altered had an analogue elsewhere in the codebase that hadn't been fixed, so I thought this would be quite a good test for Claude. I gave it lots of hints, but it flailed at the problem for several hours, often giving up, sometimes blaming the OxCaml compiler, and sometimes upstream OCaml. In the end I couldn't get Claude to make useful progress so I implemented what I thought should be the fix and indeed the problem went away. So there are clearly classes of bugs that are still beyond Claude's capabilities to understand, which isn't an unexpected result.

API boundaries

I've found it very helpful to have API boundaries to help structure the code that Claude has been producing. Anil has long been enthusiastically pushing the idea that we should write the mli files first, which constrain what types and values are available between the modules. We can then write tests that target these interfaces, and then adjust them where the tests have shown them to be inelegant or downright unusable. We can then write the implementations and watch the tests start to pass. A particularly interesting example of this is the odoc plugin interface. The experience of writing several very different plugins that all extended odoc in different directions was very helpful, and I adjusted the interface quite a few times. I also adjusted the documentation, where qualities about how the interface behaved that weren't obvious from the types could be carefully noted, for example how scripts might be made to behave correctly when the odoc pages were in an SPA shell. Far too often in the OCaml community we've relied just on types and modules as documentation for our libraries, and this is rarely enough.

Failure modes

When I was working on the dune rules, I made the mistake of going too long without giving Claude some architectural constraints, and I ended up with a Big Ball of Code that I then had to spend time unpicking and teasing apart into sensible looking modules. I had rather hopefully believed this to be a Claude Opus pre-4.5 problem, but I still hit this recently when adding a new feature, when it just added vast amounts of code to one file to implement it, and the code was all very unstructured and unsatisfactory. This was despite going through a design process where we went through the goals, the use cases and desired features, but crucially, not at the level of the code.

Another failure mode I observed was my failure. It's very easy, and very tempting, to get your agent to do the next neat thing on the roadmap. Especially when you've just spent a while going through the design and planning for the previous feature and Claude has got started on it. The problem is that this can generate a large amount of code that kind-of-works but has a bunch of bugs, which can end up costing a lot more time and effort. The cost of starting the agent going is much smaller than the cost of wading through the results, and it's quite easy to end up drowning under a load of very interesting and partly cool half results. I'm very much reminded of Dr Ian Malcolm's words from Jurassic Park: "your scientists were so preoccupied with whether or not they could, they didn't stop to think if they should."

What's next?

In the more immediate future though, perhaps with my odoc-maintainer hat on, I still want to make sure that I extract the useful parts of what I've done and get them upstreamed. While everything I've done is all open source and published, there's a lot of work I need to do so that others in the community will benefit from my changes. While it's technically possible to add my opam-repo to your switch, and install my versions of odoc, dune, and my various plugins, I don't think many people are actually going to do that. Worse than that, people might get their agents to just grab the source and mutate it further, just diluting the efforts going into it.

Fortunately I've been talking with Paul Elliot, who has volunteered to shepherd the dune PR through to completion. I'll be working with him on this of course, but I'm hoping he'll be doing the lion's share of the work.

The OxCaml work will be taken on by art-w who's already done an excellent job getting Luke Maurer's patches into shape and PR'd to ocaml/odoc.

We'll be having a forward-looking odoc meeting on the 8th April to think about the roadmap for odoc, and I'm confident that my work will help us in the discussions of what directions odoc will be heading in over the next year or so. Whilst the bigger picture of how the world is evolving plays out we need to at least carry on maintaining the community software, and use LLMs wisely and carefully as another tool in our toolbox to help us keep the code as useful and bug free as possible.

Weeknotes 2026 week 13

2026-03-31T00:00:00Z

What did I do?

I spent rather a long time this week working an a review of the past few months of work, writing, rewriting, checking what I've written, rearranging, scratching my head and pondering. Too long. I did do some other stuff too though:

Standalone TESSERA page

I had built the Js_top_worker code with the intention of having it runnable in any old web page, not necessarily one hosted on the same site as the code. However, I hadn't actually demonstrated this working, so I set up a tangled-hosted site at https://jonludlam.tngl.io and put a basic Tessera notebook there. This (fortunately) worked more-or-less first time.

Standalone TESSERA notebook

The source for this is just a single html page. The repository is on tangled.

Oxmono docs build

Anil pointed out that his docs build in oxmono had stopped working - or perhaps never started working? I'd looked at this a couple of weeks back and found it was to do with the source rendering, which wasn't working correctly in the presence of multiple implementations of virtual libraries. I had "fixed" that on the 3.22 branch by disabling the source rendering rules by default, but I found out subsequently that dune 3.22 had some issues with oxcaml, so I needed to get the fix back onto the 3.21.1 branch. With that done, I tried running the docs build again, but it's OOMing on the rather limited (7G) workers that we get for free with GHA. Now it's definitely suspect that we can build the code itself but not the docs, so there's some odoc work to do there, but we should probably just build it on one of our servers before we tackle that.

Potential scrolly improvements

While writing the review, I had another look at the examples I've got in the Scrollycode plugin and rediscovered that they are quite underwhelming. They're obviously Claude-generated placeholders, but I've always had a particular use-case in mind. About 10 years ago I gave a series of seminars at Citrix, where, using the database code as example, I showed how we can use GADTs to improve upon what we had. The talks were structured by starting with some very simple code and improving it gradually, in much the same way that the build-your-own-react example of scrollycode does. This seems to me a good way to validate the odoc plugin, so I've dug that out. What's missing from the plugin, though, is modification support - currently we can only add code, so that will need to be fixed first.

What's next?

I've more-or-less achieve what I set out to do with the TESSERA notebook - I've demonstrated that OCaml is a perfectly capable platform for using in a notebook context to do purely client-side processing of geospatial data. For the next steps, I'm going to need to talk to my colleagues to figure out what the most useful thing to do is for TESSERA. There's plenty to do, but to prioritise everything correctly is going to need some discussion.

There are some open questions / areas to investigate in the purely notebook space:

The worker and cma.js/cmi files have a dependency tree. Maybe it'd be interesting to publish the metadata for these using the at:// protocol?
Better discoverability. You can '#require' things, but what's available?
Docs links. Each of the packages I've published has the docs available. It'd be nice to link them up somehow.
AI agent integration. Most of the notebooks I've "written" recently have been generated by Claude. Can you paste in a token and get claude in your notebooks?
Reuse/remix of notebooks. The Fairground paper emphasises that you can treat your notebooks as libraries. What does this look like for these?
Persistence? The exam-question notebooks in the examples do persist your edits right now, but that's ad-hoc and specific. What's the longer-term story?
Editing beyond the code blocks. What about editing the prose in the browser? Some more thoughts. Marimo uses python source as the primary source of the notebooks. One easy thing to do would be to have an ml file as the primary source for these. We've got easy access to the comments, which are already written in odoc markup. If we did this we'd get the power of merlin in the editor, which would be pretty nice.

Weeknotes 2026 week 12

2026-03-23T00:00:00Z

What did I do?

End of term this week, so my tutorial interviews kept me quite busy for some of the week. Then Paul-Elliot has returned from his sojourn working on Slipshow, so I had a useful few hours working with him to try and begin the process of handing over the dune odoc PR.

I mentioned last week that the TESSERA reprojection was causing issues with the overlay alignment. Now the original loading of the patches was taking ages, so I switched to zarr to be more efficient. Also, the PCA was slow, so I switched that over to tensorflow.js to use the GPU.

With these two optimisations in place, it was now a lot quicker to see if the misalignment was still there. It seemed likely that the issue was translating between the UTM grid that TESSERA uses and the WGS84 coordinate system that Leaflet.js is using. It was quite quick to whip up a conversion routine (click on 'source' to see the gory details!). With that in place, the overlay now matches up precisely as you can see on the map below. Be patient while it runs, you'll see the overlay on the map in a few seconds!

#require "tessera-zarr-jsoo";; #require "tessera-viz-jsoo";; #require "tessera-tfjs";; #require "js_top_worker-widget-leaflet";; open Widget_leaflet;; register ();; (* Load fzstd (Zstd decompressor) and TensorFlow.js *) let () = let open Js_of_ocaml in let import url : unit = Js.Unsafe.fun_call (Js.Unsafe.get Js.Unsafe.global (Js.string "importScripts")) [| Js.Unsafe.inject (Js.string url) |] in import "https://cdn.jsdelivr.net/npm/fzstd@0.1.1/umd/index.js"; import "https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@4/dist/tf.min.js"

Reprojection test

Create the map, fetch embeddings from the Zarr store, run PCA via TensorFlow.js, and overlay — all in one cell so the async pipeline completes before the overlay is drawn:

let status_view text = let open Widget.View in Element { tag = "div"; attrs = [Style ("padding", "8px"); Style ("font-family", "monospace")]; children = [Text text] }

let () = Widget.display ~id:"status" ~handlers:[] (status_view "Initialising...")

let map = Leaflet_map.create ~center:(52.30690, -0.03296) ~zoom:14 ~height:"500px" ()

let bbox = Geotessera.{ min_lat = 52.29924; min_lon = -0.05845; max_lat = 52.31745; max_lon = -0.00755; }

let downsample mat ~h ~w ~max_pixels = let n = h * w in if n <= max_pixels then (mat, h, w) else let stride = int_of_float (ceil (sqrt (float_of_int n /. float_of_int max_pixels))) in let h' = (h + stride - 1) / stride in let w' = (w + stride - 1) / stride in let out = Linalg.create_mat ~rows:(h' * w') ~cols:mat.Linalg.cols in for i = 0 to h' - 1 do for j = 0 to w' - 1 do let si = min (i * stride) (h - 1) in let sj = min (j * stride) (w - 1) in for f = 0 to mat.Linalg.cols - 1 do Linalg.mat_set out (i * w' + j) f (Linalg.mat_get mat (si * w + sj) f) done done done; (out, h', w')

let () = Widget.update ~id:"status" (status_view "Opening Zarr store..."); Lwt.async (fun () -> let open Lwt.Syntax in let* store = Tessera_zarr_jsoo.open_store () in let progress msg = Widget.update ~id:"status" (status_view msg) in let* (mat_full, h_full, w_full, geo_bounds) = Tessera_zarr.fetch_region ~progress ~store bbox in Widget.update ~id:"status" (status_view (Printf.sprintf "Fetched %d×%d. Downsampling..." h_full w_full)); let (mat, h, w) = downsample mat_full ~h:h_full ~w:w_full ~max_pixels:500_000 in let bounds = Leaflet_map.{ south = geo_bounds.Geotessera.min_lat; north = geo_bounds.Geotessera.max_lat; west = geo_bounds.Geotessera.min_lon; east = geo_bounds.Geotessera.max_lon; } in Widget.update ~id:"status" (status_view (Printf.sprintf "Computing PCA on %d×%d mosaic..." h w)); let proj = Tfjs.pca mat ~n_components:3 in let img = Viz.pca_to_rgba ~width:w ~height:h proj in let url = Viz_jsoo.to_data_url img in Leaflet_map.add_image_overlay map ~url ~bounds ~opacity:0.7 (); Widget.update ~id:"status" (status_view (Printf.sprintf "Done. Input bbox: S%.5f W%.5f N%.5f E%.5f | Overlay bounds: S%.5f W%.5f N%.5f E%.5f" bbox.min_lat bbox.min_lon bbox.max_lat bbox.max_lon bounds.south bounds.west bounds.north bounds.east)); Lwt.return_unit)

Weeknotes 2026 week 11

2026-03-18T00:00:00Z

What did I do?

TESSERA

I Started looking at fixing my TESSERA notebook to make it actually correct:

Removing the OCaml native PCA to replace with a tensorflow.js one. This should be much faster and probably more accurate.
Investigating the slightly-off-seeming embeddings - you can see features like roads on the embeddings and they don't quite match up with the map. The problem is to do with WGS84 vs UTM, which I need sort out.
Looking at UNets as part of replicating Sadiq's Solar Panel detection example. Not much to show yet though.

Odoc release

We need an Odoc release soon, partly to support markdown output in dune, and partly to fix some bugs that were discovered when doing the odoc v3 dune rules. I merged a lot of stuff this week, but we've still got Arthur's OxCaml patches to merge, which are waiting on a test fix. I also looked into OCaml 5.5 compatibility. The big item looks to be the merge of Modular Explicits, which will require a bit of work to support. I'm considering a mechanical fix to at least get odoc compiling with 5.5 for the odoc release, and a larger release later to properly support the 5.5 features.

OxCaml docs builds

Anil has merged my PR to his oxmono repo to do docs, and that works nicely if you're generating all of the docs for your monorepo, including dependencies, which is what you get when you run dune build @doc-full. Running dune build @doc doesn't quite work as there's no external place like ocaml.org where you can expect your dependency libraries docs to be. Mark's day10 project is already building all of the oxcaml packages, so I had a look to see what it would be like to extend that to build the docs too. This is more-or-less working, but not yet as a reliable place that you can expect to be up to date. I had a thought that keeping the docs build running nicely is something that an AI agent should be able to do really well, so I'm investigating this. A neat thing it's already been able to do is to sort the build problems by number of other packages that they block, and numbers one and two were PPX issues (ppx_deriving_yojson and lwt_ppx). It was then able to come up with some patches that enabled both of these to build, unblocking all of those downstream packages. This, of course, is of wider interest than just the docs, so I need to figure out what to do with those patches.

Bugfixing my monorepo

I've been polishing the monorepo that's powering my website with a view to publishing a retrospective of the work that I've been doing over the past few months. Most importantly, adding '--warn-error' to all my odoc invocations to actually notice all the warnings it's been diligently reporting, and I've been ignoring. Looking further than my own failings though, this has really helped solidify in my mind the areas where Claude excels and the things we should be much more wary of letting it do. More on this in the retrospective!

Weeknotes 2026 week 10

2026-03-09T00:00:00Z

Here are my weeknotes for the last week, while I'm still writing up some more focused posts on some specific topics - like the experience of putting everything in a monorepo to create this site, and more notes on Claude and Agentic coding in general, and its impact on the world of software. But for now, here's what I've been up to.

What did I do?

New site design. The old site was a bit of a mess and was simply reusing odoc's default default styling. I've also rearranged the content a bit to make it more navigable and cohesive.
TESSERA in the browser is a hot topic right now, so I've applied the work I've been doing with x-ocaml, js_top_worker and odoc plugins to make a TESSERA notebook that's based on the example notebook.
I was interested in whether we'll be able to do inference in reasonable time using these notebooks. ONNX has a web version of its runtime, so I got Claude to make some bindings, and checked it was working by doing a sentiment analysis notebook. This is working nicely, so the next step is to do something a bit more useful. Try it here.
The docs CI was again causing problems. This time it had decided that it had never built anything, and therefore needed to rebuilt the entire world. However, despite being set up as a custom dedicated runner, all its jobs were queued waiting to start. It turned out that the runner paused itself when the docker partition reached 70%. This was a little surprising on two counts - firstly we don't actually use docker for running the jobs, we use obuilder, which doesn't share space with docker. Secondly, with that in mind, how did it get to 70%? It turned out to be the job logs - including 250 gigs of older logs from a previous instance. Simply blowing those away caused everything to restart and so it's now live again.
I met up with Andrés C. Zúñiga-González to have a chat about how he's using interactive maps and notebooks. He pointed me at his blog, some of which which is using quarto, which he rates very highly. An example of quarto output.
Our group seminar this week was Tom Bearpark who talked about his proposed 'Carbon at Risk' measure in order to compare diverse ways of removing carbon from the atomsphere to help with the carbon removal market.

What's next?

More writing before more coding, I think.

Weeknotes 2026 week 9

2026-03-02T00:00:00Z

Let's make this really terse!

What did I do?

Got docs working with github actions on Anil's oxmono monorepo. Results are here. This includes experimental support for oxcaml modes/layouts.
Got markdown mode output into Sherlodoc's db so you can query it - great for agents!
Widgets in the JS OCaml toplevels - using FRP for the interactions. The neat thing here is that using FRP via Daniel Bunzli's note library is that all the interactions are all purely functional, no refs or mutables in sight. You provide a little wrapper scripts that's run in the frontend and the interactions and send back and forth with the worker running the code where it's translated into Events and Signals. My proof-of-concept of this is a widget that works with the leaflet.js library:

Demo coming soon!

Consolidating all of the Odoc toplevel bits and pieces into the one monorepo. Again, demo of this coming soon!

What am I going to do?

New website!
Odoc plugins showcase
Writing writing writing writing

Weeknotes weeks 7-8

2026-02-24T00:00:00Z

A combination one again as I took some time off due to school half term.

Finished off my exam questions

This was a lot of fun! Obviously I can't talk about it, but while it was stressful and worrying and anxiety inducing and scary, it was also engaging and interesting and thought-provoking. Having some ideas come together to make a nice coherent whole was very cool.

Testing LLMs on past paper questions

Similar to our work on the ticks that Sadiq, I and others did last year, I wanted to try to see how well LLMs could answer tripos questions. Partly I wanted to do this so I could check that my own questions were of the right sort of level, and partly it was just a displacement activity while I wasn't making progress on the actual exam questions! I've not done a useful analysis of the results yet, but seemed in line with our experience with the ticks, though the pass rate was lower for the same models (qwen).

Claude from a sunbed

I went away for a vitamin-D boosting bit of sun. Before I went, I got Claude to spin me up a little Telegram bridge so that I could tell it what to do, while it's still running in safeties-off mode on my sacrificial VM. This was kind of fun - I got to just indulge thoughts as they came to me, and off it would go and do stuff. It was a bit limited in how it talked back to me, which wasn't by design but turned out to be nice for this sort of workflow. The downside is that I've now got a load of stuff to sift through - much of which is a 'good start', but none of it is likely to be usable without a good deal more effort. Here's a short-list of things I had it do:

Resurrect Fay Carson's work on the Menhir parser for odoc, pushed here
Added some instrumentation to Odoc to do some performance experiments
Ran some simple experiments to measure the impact of various pre-existing performance knobs/switches
Resurrected an old patch of mine to unify the two path representations in odoc to measure its effect on performance.
Tested aggresively reuse of records if their fields don't change during compile/link
Mixed up the scrollycode backend and the x-ocaml backend and stuck a playground on at each step
Unified the oxcaml/ocaml branches of js_top_worker and x-ocaml via cppo
Added oxcaml mode/layout annotations to odoc

OxCaml

I investigated the oxcaml docs build, which I had got working last week. Anil reported that it wasn't working for him, so I looked at the build I had and it definitely was working. However, I was building on our machine Monteverde, which is a bit of a beast, so I checked the memory usage and it was enormous! I tried the build again on my 64 gig VM and it OOM'd. I'd noticed before that the cmti files for base, in particular base__Container.cmti were absolutely massive, and so had just assumed that the problem was that. Luke had also mentioned that some of the output from the template machinery was hidden. However, I had Claude look into this and it couldn't see any doc stop comments. So I asked it to look a little closer and figure out what was using all the memory. It took an unexpectedly large number of prods from me to finally figure out what was going on - it was to do with how odoc processes includes - specifically an include sig ... end. Essentially an include of that type ends up doubling the storage required of the signature. As the ppx_template extension does quite a lot of this, and in particular nests them, this ends up going exponential and this turned out to be the cause of most of the memory usage. With a fair bit more prodding by me, Claude and I eventually got to a solution, which I'll be upstreaming soon - the fix applies to OCaml as well as OxCaml, but it's this particularly pathalogical usage of includes that ppx_template uses where it'll make the most difference.

Odoc, plugins, JS and more

Teaser... I have a blog post coming soon with more on this. It's been a lot of fun, and should provide a decent inspiration for a roadmap for Odoc and online notebooks!

Weeknotes for week 6

2026-02-09T00:00:00Z

Highlights:

Oxmono

I spent some time on Anil's oxmono repo getting odoc to work correctly. It turned out that the bug I was working on last week was critically important for this - and that the bugfix was incomplete. One of the issues was to do with identifiers needing to be unique. For example, consider the following code:

module type S = sig type t

include sig type t

val f : t -&gt; t

end with type t := t end The problem here is that both definitions of `type t` have the same identifier, which causes problems when we move to and from the 'Component' types. The solution was to introduce a 'dummy' parent for the type defined within the include. This works because we never actually render the body of the include into HTML - we render the expansion, which doesn't have type t in it, as it has been substituted out.

The fix I made last week fixed the loader, which reads in the cmt/cmti files produced by the compiler. There's one more place where we create these in the code - when we translate from the Component types back into Lang types. I was a little curious about whether it was possible to make this happen, so I thought I'd ask Claude to see if it could come up with a scenario where we'd end up in this situation. This was a complete failure, which was a real disappointment to me, as doing this sort of thing is a quite tedious and annoying part of working on odoc.

Meanwhile, I was running odoc on Anil's oxmono repo, which was using art-w's PR to upstream oxcaml support. It was failing with an exception that was very familiar, so I pulled in the fix I'd been working on, and that enabled it to get much further. However, it did subsequently fail with another slightly different exception. I had my suspicions at this point that it might be due to the other place, but I thought this again was a good opportunity to test Claude's debugging skills. However, this again was a complete failure. I spend quite a long time prodding it - at least 4 separate sessions - and it really didn't get anywhere close to a solution, despite knowing precisely that the commit we'd made that had fixed the first problem. Two of the four times it ended up telling me that the oxcaml compiler was broken and suggesting that we create an issue!

I'm only very mildly disappointed in this - it's all quite subtle, and something I still end up scratching my head over sometimes, but it would have been wonderful to be able to offload this sort of work!

In any case, the docs now all build on my fork of oxmono.

Docs CI

The fix I deployed last week for ocaml-docs-ci was taking forever to complete, so I ended up spending some time investigating this. The problem was happening during the 'prep' phase, which is the first part of the pipeline where we simply build the package to be documented. This is supposed to work by building a graph of all inter-package dependencies across all of the solved packages, so we maximise sharing of built artefacts. Each 'prep' job builds precisely one package by coping in the dependencies from previous prep jobs, then running opamh to fix up the metadata so that opam believes it has installed everything itself, then running opam to build the one package required. It was this last step that was going wrong, where it would decide that there had been upstream changes to the compiler itself, and rebuild everything, so rather than a prep job taking a few seconds, it would take a few minutes.

I was totally unable to repro this locally - everything build very quickly and just how it should have done. After much head-scratching I finally realised that the problem was somewhere in the caching. I think what's going on is that we dynamically build an opam repository to make the `opam install` command faster, and that repo contains only the packages that are required to build whatever it is we're building. Those opam files are cached by the docs CI server and passed to the build script as a base64-encoded gzipped tarball inline in the obuilder file (!). This should all be totally consistent as we're also caching all the builds - except for the compiler itself, which comes from the base docker image. This, of course, is the problem. The ocaml compiler opam files had been updated, and then when we reconstructed the opam repo with our cached opam files, opam noticed they had changed (gone backwards in time!) and decided it needed to rebuild the compiler, and therefore everything else. Clearing out the opam-files cache and restarting the builds fixed this entirely, and the full rebuild job completed after about 2 days. I flipped the switch on Saturday night and the docs are now fully up to date again. Phew!

day10 work

This was a fun week of large-scale building! I integrated day10 and odoc_driver and js_top_worker and x-ocaml and have now successfully got a docs-ci-like system that's able to build docs and toplevels that can coexist in the one HTML tree. I've not got a full integrated demo yet, but you can see the test cases for this here. Be sure to take a look at the 'network' tab in the browser dev tools to see what it's doing!

Scrollycode experiments

I've long been a fan of Rodrigo Pombo's work on "building tools for better code reading comprehension", ever since first seeing his post "Build your own React". Claude is fantastically good at doing this sort of thing, so I asked it to go and build me some simple OCaml-focused versions. We came up with 5 variations in the end - and they're all pretty neat! take a look!. The best part of this was that it took me less than half-an-hour to get Claude to do all this.

Dune PR

I attended the bi-weekly dune dev meeting to talk about the first part of the dune PR - the bit that Paul Elliot did almost a year ago.

Coming week

So the clock is ticking on writing the exam questions for FoCS, so I'll need to be spending time this week on that.

Weeknotes for weeks 4-5

2026-01-30T00:00:00Z

I've been battling the seasonal illnesses this week, so I've combined two weeknotes into one. Fortunately the 'flu doesn't hold Claude back!

Probably the most interesting part of this is the Retrospective, so make sure to read that bit.

The Last Two Weeks

As is becoming more and more apparent, the breadth of what I'm working on is ever expanding, powered by agentic AI. It's become so much more (cognitively) cheaper to have an idea and set an agent off investigating it that I've been finding that I'm working in parallel on far more things in a single week than I would have even six months ago. Here are some of the bigger headings though.

Monorepo excitement

We're currently experimenting with a new tool - monopam to help develop across multiple OCaml libraries by using git subtrees to create a monorepo with all of the packages in. We then extract patches to the individual repos to push upstream. I've been moving my development workflow from in-vscode-claude with careful permissions checking to running claude with `--dangerously-skip-permissions` in a container with the monorepo checked out. This has been a bit of a bumpy ride, with the tool evolving daily, but I'm very much seeing the benefits of letting Claude just get on with things, given a strict enough early design and testing strategy, and using Anil's method of creating the interfaces first.

Odoc

I also did quite a bit related to odoc these 2 weeks, split over improving functionality and bugfixing.

Plugins

Getting Claude to run with all of the monorepo libraries implicitly requires that they're well documented, as looking at the source to figure out how to use them exhausts the context window pretty rapidly. Odoc's main focus has been on getting the expansions and referencing correct, and while we've made progress on the actual content markup, introducing media tags for example, there's still a good distance to go.

Using the plugins mechanism I wrote about last week, I've made a plugin interface for odoc and implemented a few plugins. Initially I was just going to support 'custom tags' but it occurred to me that rendering code blocks could also be done in this way. So I've made a few. Two custom tag plugins:

odoc-admonition-extension - styled callout blocks for notes, warnings, tips. Note that we are intending to make this more first-class - there's a design out there. This was just a convenient way to test the feature!
odoc-rfc-extension - links to IETF RFC documents and 3 code block plugins:
odoc-msc-extension - Message Sequence Charts
odoc-mermaid-extension - Mermaid diagrams (flowcharts, sequence diagrams, etc.)
odoc-dot-extension - Graphviz/DOT diagrams The module signatures relevant to the plugins are documented in Odoc_extension_api and the plugins each have to implement an interface described in Odoc_extension_api.Code_Block_Extension or Odoc_extension_api.Extension for custom tags.

Bugfixing

Luke Maurer at Jane Street pointed out that they're still suffering from yet another repro of issue 930 at Jane Street. I'd worked on this back in September but turns out I hadn't actually made a PR, so I tidied up the branch and made a PR.

Docs CI

Docs CI has been fixed and is even now rebuilding all of the docs for ocaml.org. I've added in the handling of `post & with-doc` in place of x-extra-doc-deps, so we should be able to use either mechanism now. The idea is to deprecate x-extra-doc-deps soon though. Somehow despite an explicit button to press to update the epoch symlinks, it got updated anyway and broke most of the docs on ocaml.org. Fortunately someone noticed and posted on discuss and so I switched it back.

Unfortunately, it seemed to be taking a long time to build the docs - at time of writing it's now Friday, and the CI jobs have been running since Tuesday. In that time, it's only managed to build about 6500 packages, a long way short of the 16,000 or so that I expect a full build will produce. Looking through the logs, it seems that some change to opam is causing it to sometime rebuild the entire opam universe when it should only be building 1 package. For example, in a job that should be building just `tezos-protocol-004-Pt24m4xi`, it installs all of the prebuilt dependencies, then runs `opamh` to try to convince opam that everything is all set up to just run the build step for the package we want. Unfortunately the logs show the following:

The following actions will be performed:
=== recompile 178 packages
  - recompile aches                            1.1.0              [uses ocaml]
  - recompile aches-lwt                        1.1.0              [uses ocaml]
...
  - recompile mtime                            2.1.0              [uses ocaml]
  - recompile ocaml                            4.14.2             [upstream or system changes]
  - recompile ocaml-compiler-libs              v0.12.4            [uses ocaml]
...

where it seems opam has decided that something has changed enough for it to want to recompile the `ocaml` package, and therefore everything in the entire opam switch! So this job took 12 minutes instead of 21 seconds, which was the time required to finally build the `tezos-protocol` package.

Day10 and docs

In closely related news, mtelver's day10 project looked precisely the right shape for building docs - in fact it shares its architecture and some components with the docs CI. So I asked Claude to take a look and see what it would take, and discovered that it doesn't take very much! We have a Really Big Machine here at the CL that was temporarily underused; and by Really Big I mean 768 cores and 3TB of RAM. So, how long could building all of the docs for all of the packages possibly take? Well, it takes 5 hours 40 mins. And I was only using roughly a third of the machine. Nice!

So should I push on with fixing ocaml-docs-ci and figure out why it's rebuilding everything all the time? Or should I forge ahead with day10 and turn it into a proper CI system as opposed to a slightly flakey bespoke thing I have to handhold through a build? This is next week's problem.

JS toplevels

Something I keep coming back to is javascript toplevels. I'd really like to be able to be able to host JS toplevels on ocaml.org for each different version of each different package. This is something I've worked on on-and-off for a long time now, and several fixes to help have been merged to various projects along the way. The tricky thing is to not put a massive load onto ocaml.org with this, so we need to be efficient. That means firstly having a single toplevel js file with all of the logic in but none of the libraries, and then dynamically loading libraries as we need them. Also we can save some bandwidth by not immediately sending all of the cmi files, as these can be faulted in as necessary too. So once again I've got Claude on the task, and things are honestly looking pretty hopeful now. I've got 2 demos:

Dynamic library loading
Multi-version support In both cases, make sure you take a look at the network tab to see it dynamically loading only what it needs.

Retrospective

Autonomous Claude

The power of sending Claude off to do some work can be immense. However, it does mean investing time up front telling it precisely what problem you're trying to solve, what approach to take, finer details on how you want it done, and how you can tell if it's working when it finishes. A 'failure mode' I've been experiencing is when I end up in a long, drawn out real time interaction, especially if that's happening with 2 projects simultaneously - and by 'failure' I really mean just 'slow'. Ideally what would be going on is for all of my agents to be getting on with whatever task they've been allocated without bothering me for more details. For Claude to have to ask me a question has much more latency involved than it just getting on with things, especially if I don't notice it immediately.

When to Stop

The 'finishing criteria' are important - many times this week I've had Claude tell me it's finished something, having verified that it's passing all the tests, only for me to take a look to find that it's very obviously broken. As quite a few things recently have involved the web, I've put Playwright into all of my devcontainers, and told Claude to use it to verify things are working. This has been working pretty well, so I'll be adding it to my prompts. It's not too dissimilar to what we used to call 'pre-flight checks' back in the Citrix days.

Containers vs accounts

I've been running everything with `--dangerously-ignore-permissions` in containers, and while the outcome is amazing, the containers bit has been a bit of a headache. Next week I'll be trialling the idea of just giving the agents their own account (non-admin!) on my servers, their own github account, tangled account and so on, and just treating them more like I would if I had a real colleague. It's always slightly alarming to see my own name on the output of the bots, assigning me (or sometimes someone else (!!)) copyright over code I've never seen. This is, of course, a whole other pandora's box that I really don't want to open right now - but I think the point is that I'll feel a lot more comfortable if the commits are all by `Jon's Agent <jon+claude@recoil.org>` rather than by me!

Deciding next steps

The question of whether I should fix up ocaml-docs-ci or improve the day10 solution requires a bit of thought. In fact, it requires a bit of a gap analysis between the two. This isn't something I've asked Claude to do before, so I'll try that and see how it turns out. I'll be asking it to be "scientific" in its approach, coming up with hypotheses and verifying them - for which I think I'll need to give it a platform on which it can perform experiments. This is a bit trickier with ocaml-docs-ci than day10 as day10 runs entirely on any given linux computer, whereas ocaml-docs-ci needs ocurrent workers and a routable ssh server. I'll report on the outcome of this next week!

Weeknotes for week 3

2026-01-19T00:00:00Z

First week back of 2026! Let's write some terse weeknotes.

Projects

Dune odoc rules

Last thing I did last year was to push the new rules for odoc 3. This week, Anil handed me an excellent opportunity to test the rules on the monorepo containing his AOAH projects. Claude tends to actually write ocamldoc-formatted comments, so this is really useful to test the rules. I've rebased the commits on the just-released Dune 3.21 and we've been trying them out. There were a few things to fix:

More careful dependency tracking during the compile phase - this particularly affected the @doc target, which was pulling in unnecessary dependencies. Most of these dependencies were compiling just fine, but one - Anstrom - is slightly odd in that the opam install of Angstrom installs a META file that references libraries that aren't in the dependencies of its opam package. This is a backward-compatibility hack that was implemented when the Anstrom package was split into several in order to manage the dependencies better.
A similar issue happens with eio, where the documentation of the package depends upon bigstring, which isn't in eio's dependencies. This is entirely intentional - the extra doc dependencies is stated in the opam file with a x-extra-doc-deps field. However, opam install totally ignores this field (quite reasonably), and so a simple install gives you an opam repo whose docs can't be built. Once again, this broke dune build @doc unnecessarily, but the fix was relatively simple. The real fix here is to not use x-extra-doc-deps, but switch to using a real dependency, but marked with with-doc and post if it would otherwise introduce a circular dependency. That way, an opam install --with-doc would install the extra dependency.
Over the Christmas break, tbrk posted on discuss a question about building docs, for which my dune branch was a partial answer. One feature he was requesting though was the ability to use a custom top-level index. It's a useful feature that's implemented in odoc_driver so I've added it.
More sensible default link scope. By default, documentation references in the mli files of a library can link to any other library in the package. However, by default it wasn't possible to link to the dependencies of another library, unless it happened to be a dependency of your own library. Similarly, the package-wide mld files could only reference the modules in the package's libraries, not to the dependencies. This seems overly cautious, as we can be sure that if we've managed to build the libraries then their dependencies are installed, and if there are any module name conflicts, we can resolve them via the /<lib>/Module syntax.
Lastly, implementations of virtual libraries need to be skipped as they've all got the same docs (as they share mli files), and the rules as they were causing Dune to crash with a "Conflicting implementations" error. I've also rebased the PR onto latest main, but I've not yet put these patches there, which I'll need to do for the PR to be mergable. For now, the 3.21 branch is successfully building the docs for the monorepo.

OCaml Docs CI

Jan Midtgaard noticed over xmas that the Docs CI was broken and submitted a fix. I've therefore been poking ocaml-docs-ci to get the fix incorporated and into production. I almost immediately hit the issue that odoc_driver now breaks for the exact same reason. I couldn't quite understand how opam-format had been merged to opam-repository without someone noticing that it had broken odoc_driver, but it turned out that it had been noticed, but on a beta release. The fix to docs ci was to install odoc_driver from opam rather than pinning directly to a github hash, especially if that hash happens to be the hash of the released version!

While I'm working on docs CI, I thought it's probably also a good idea to move over to the with-doc & post suggestion from above, so we're ready for when packages start to use that. This is now being tested, and hopefully we'll have the CI back up and running early next week.

Better styling for odoc

I've done very little to the styling of odoc since I took maintainership way back in 2019 or so. It's a bit dated, and there are some annoying usability issues, so I thought it's a good opportunity to vibe-code a nice new frontend for it. Rather than hack directly on the HTML generator of odoc, this seemed to be a good opportunity to test the JSON output from the new Dune rules, so I asked Claude to make me a static site generator that read in the JSON files and spat out some nicely styled HTML. This worked like a charm, and the results are here. Next steps are to see what it would take to get the native odoc output looking more like that.

Custom tags in odoc

One of the themes of Anil's AOAH coding spree was that many libraries were implementations of RFCs. In many places in the docs, there are links to relevant sections of the RFCs. It'd be nice in future to be able to validate that we've covered all of the parts of the RFCs, so making the links a little more parsable seemed like a good idea. In fact, it seemed that this might be a perfect use for custom tags - a feature that was present in ocamldoc that odoc has yet to implement.

Arthur Wendling then pointed me at dune's plugin system, which seemed just the ticket as a way to implement this. It's really nice, taking all of the hard work out of creating OCaml plugins, so I've now got an extension-plugins branch that implements this. It allows you to add support to odoc for tags like @rfc which generate custom HTML, markdown or any other backend, can include links in their bodies, and can add custom headers to the web page, and custom files to be output by odoc support-files. It looks like this should "just work" and no further changes to the dune rules are needed - though I need to actually test this out.

Day10 and docs

I've written about Mark's day10 project before. It's a tool to very rapidly build odoc packages mainly in order to test that they build correctly. An obvious extension would be to use this to then build the docs for those packages, as the way we do this requires the packages to be built first. This would be a replacement for the Docs CI that I talked about above, though there's considerable work to do before it's fully-featured enough to be a viable alternative. It seemed like a good time to experiment with this though, so I set up one of Anil's devcontainers, gave Claude some instructions on what to do, took the safety belt off, and let him hack away! Previously most of my interactions with Claude had been via the vscode plugin, so using the terminal interface was a bit of a different experience. I'm fairly certain though that I'm going to switch everything over to working this way, as letting Claude just get on with things without having to OK every step is a far more efficient way to work - especially when you're not that concerned with the actual code being produced. This has been mostly a good experience, though Claude does sometimes go off in rather odd directions. At one point there was a network error with a dependency while trying to build odoc_driver, so it decided that it should have a fallback mechanism that executed odoc directly. I told it NEVER to replace functionality in odoc_driver, so it rolled this back, but a few hours later in then did exactly the same thing again.

Misc other stuff

A few other things too - improving the --warn-error logic in odoc, and one of its error messages, improving the build of this website so I can iterate on it more quickly, fixing up some of my self-hosted services like my tangled knot, and other bits and bobs.

Reflections

I think the most important thing this week has been the slightly eye-opening benefits of using Claude outside of the context of VSCode. I suspect I'll be doing much more of my work this way in future. There's also a good chance I'll have to upgrade my subscription from the $100-per-month to the $200 one...

Next week

Start of term tutorial meetings
Sherldoc in monopam-myspace
Get ocaml-docs-ci deployed and working
Update the Dune PR
Integrate the custom-tags and website generator into monopam-myspace
Unleash Claude on my js-top-worker repo

Claude and Dune

2025-12-18T00:00:00Z

Back in March of this year we released odoc 3.0.0, a major new version of the OCaml documentation generator. It had a whole load of new features, many of which came with new demands on the build system driving it. We decided when working on it to build a new driver for odoc so that we could adjust it as we were building the new features, and this driver is now used to build the documentation that appears on ocaml.org. However, it was always the plan to integrate the new features into Dune so that everyone could just run dune build @doc and be able to use all of the new odoc 3 features.

So over the last few weeks I have been wrestling with getting Claude to update the odoc rules in Dune to support some of the new features of odoc v3. What began as a background experiment during a lecture series has turned into a multi-week effort to turn mostly-working code into a clean, reviewable patch. AI-developed software is clearly going to be a big part of our future, and Anil is showing us all the way with his Advent of Agentic Humps by building new software, but upstreaming AI-generated changes to an existing, well established code base hasn't got off to a good start in the OCaml community, so I wanted to be extra careful to get this right.

Claude as a protyping tool

The initial progress was pretty amazing, despite my initial worries that the dune code-base would be too large and subtle for an LLM to be able to make workable changes. In order to get going, first I had it look at several bits of example code:

1. dune_rules/odoc.ml - this is the current home of the odoc rules in dune. It's local-only, meaning it only builds the docs for the current package in isolation, so no resolution of links to stdlib, other packages or libraries.

2. dune_rules/odoc_new.ml - these are the rules for odoc v2, which allow you to build the docs for your package plus all of the dependencies. I wrote this mostly myself some time ago. It does a pretty poor job of caching, error reporting, and has none of the odoc v3 features like assets, source rendering, hierarchical docs, better errors and so on.

3. odoc_driver - this is the driver we wrote when building odoc v3. It's fully featured, but not at all incremental, and actually external to the dune codebase. It's the reference implementation that's used to build the docs that appear on ocaml.org.

Armed with these three code-bases, I asked Claude to synthesise a new incremental version of the odoc rules for dune that has some of the features of odoc_driver.

The working prototype

Claude quickly produced a prototype that actually compiled and generated documentation. At that stage I was not interested in the quality of the generated source; I only needed to know whether Claude could navigate Dune's codebase and produce something that works. I let the prototype evolve incrementally, adding in new features one at a time, for example, fixing the error reporting so that you only get warned about documentation errors that you can actually fix.

When the lectures finished, it turned out I had something that was pretty useful to me, and had a good chance to be useful to others too. So I opened up my editor and had a look through what had been produced, at this point hoping that a little bit of polishing should be enough - after all, it was working!

It was dreadful.

There were long, rambling functions, code duplication, bad comments, it was unstructured, with repeated-but-slightly-different chunks all over the place. It wasn't just bad on one length scale - it was bad from the large-scale organisation of the code down to small scale baffling weirdnesses on one line. The more I looked, the more bonkers it appeared. But it did work! So I thought I'd get Claude to clean up its own messes.

The clean-up

I resolved that I would continue to let Claude do all of the editing, and not do any myself, and so thus began the more frustrating part of this adventure! I ended up giving a mix of very specific instructions: "move this code here", "factorize out this functionality", "rename this function", and sometimes more general ones: "Remove any comments that don't add anything of value", or "Think of a better way to do this". The constant was that I needed to be looking over each change that it did, because while most of them were pretty good, there were still a few, even with the very explicit instructions, where it messed up. From the very broad, where at one point it told me "I'll remove this code to create odoc files for external dependencies, as they're installed by opam", which isn't true, down to the very small - for example, it produced the following:

let lib_names = deps.Odoc_config.libraries in
if List.is_empty lib_names
then Memo.return []
else Memo.List.filter_map lib_names ~f:(fun lib_name -> Lib.DB.find lib_db lib_name)

where it has come up with a totally redundant check for the empty list.

It was at this point where it became frustrating, because although it's almost magical that Claude can do what it does in the time it does, this fact of having to keep a constant eye on it meant the the tens-of-seconds to minutes delay in between it doing something meant I ended up either twiddling my thumbs for long periods of time, or getting started on some other task and forgetting to come back to Claude, sometimes for hours!

OCaml is not the problem

One part that particularly impressed, and also quite surprised me, was with its knowledge of OCaml. In particular, I had at one point two different types representing the 'target' - either a library or a package - and a 'kind' - either a module or a page. Now pages can only be associated with package targets, and modules can only be associated with libraries, but these two values were distinct, so there was a fair bit of code pattern matching invalid combinations and either throwing exceptions or picking some random value, depending on the whims of Claude's context. I bravely suggested it think of a better way to represent this, maybe using GADTs, and it did indeed come up with a pretty nice refactoring of the types:

Before:

type target =
  | Lib of Package.Name.t * Lib.t
  | Pkg of Package.Name.t

type artifact_kind =
  | Module of
      { visible : bool
      ; module_name : Module_name.t
      ; archive : string (* Which archive the module belongs to *)
      }
  | Page of
      { name : string
      ; pkg_libs : Lib.t list
      }

After:

(* Artifact data types *)
type page = { name : string; pkg_libs : Lib.t list }

type mod_ =
  { visible : bool
  ; module_name : Module_name.t
  ; archive : string (* Which archive the module belongs to *)
  }

type _ target =
  | Lib : Package.Name.t * Lib.t -> mod_ target
  | Pkg : Package.Name.t -> page target

type artifact_kind =
  | Module : mod_ * mod_ target -> artifact_kind
  | Page : page * page target -> artifact_kind

This refactoring immediately removed a whole swathe of invalid combinations, making the code both safer and clearer. It's quite clear that Claude had no trouble understanding how GADTs work in OCaml, quite happily also using some existentials to pack them into lists and so on.

Odd behaviours

Sometimes Claude just went a little bit bananas. One annoyance that repeatedly occurred was that it would forget how to build and test the dune executable, despite clear instructions in Claude.md. Most of the time when it went wrong it would build dune, execute dune clean, then try to run the dune binary that it had just removed with the clean. Sometimes it would decide to use the bootstrap binary instead, which isn't rebuilt on every change, sometimes it would run the switch-installed dune binary, and on one occasion it tried to run ./configure && make!

It would usually figure out eventually what the right thing to do was, but when you're waiting for it to complete so you can check what it's done these sorts of delays got a bit frustrating.

Reflections

At one point, I ran out of Claude credits (despite paying $100 a month or so), at about 6:20pm one evening, and it told me that I needed to wait until 7pm to carry on. I'd just got to the point when I needed to write a short bit of code rather than refactoring what was already there, and I realised that while it would take me maybe 10 mins, it would take Claude maybe 10 seconds. Now, it could just be that it was the end of a long day and I was running out of steam, but I was content to switch focus elsewhere for a bit to wait for my credits to reset before carrying on! The point being that for the small implementation that I was after, it would be possible for me to get Claude to do it, and to eyeball the result to make sure it was OK in less time than I would have been able to do it myself. But I absolutely wouldn't have trusted Claude to do it in an upstreamable way without looking at the result.

Overall, It's clear that Claude will be an incredibly useful tool for working with software. It's unbelievably good at jumping into a new code-base and figuring things out quickly, but less good at producing high-quality code that can be directly submitted upstream (yet?) - at least, not that I would be comfortable submitting anyway. However, I think it's still a bit of an open question as to what the quality bar should be. If it builds correctly, passes the tests, looks broadly sensible and isn't on the critical path for performance, how much should we care about the line-to-line quality? I certainly care, but am I being old fashioned?

I've submitted a PR with these changes for review, and we'll see what happens there. I ended up squashing all of the commits into one, as the intermediate steps are very likely not useful. However, for historical interest, the branch on which I did most of the work is here.

An SVG is all you need

2025-12-09T00:00:00Z

SVGs are pretty cool - vector graphics in a simple XML format. They are supported on just about every device and platform, are crisp on every display, and can have embedded scripts in to make them interactive. They're way more capable than many people realise, and I think we can capitalise on some of that unrealised potential.

Anil's recent post Four Ps for Building Massive Collective Knowledge Systems got me thinking about the permanence of the experimentation that underlies our scientific papers. In my idealistic vision of how scientific publishing should work, each paper would be accompanied by a fully interactive environment where the reader could explore the data, rerun the experiments, tweak the parameters, and see how the results changed. Obviously we can't do this in the general case - some experiments are just too expensive or time-consuming to rerun on demand. But for many papers, especially in computer science, this is entirely feasible.

That line of thought reminded me of a project I tackled about 20 years ago as a post-doc in the Department of Plant Sciences here in Cambridge. I was writing a paper on synergy in fungal networks and built a tiny SVG visualisation tool that let readers wander through the raw data captured from a real fungal network growing in a petri dish. I dug it up recently and was surprised (and delighted) to see that it still works perfectly in modern browsers - even though the original “cover page” suggested Firefox 1.5 or the Adobe SVG plug-in (!). Give it a spin; click the 'forward', 'back' and other buttons below the petri dish!

And that, dear reader, is literally all you need. A completely self-contained SVG file can either fetch data from a versioned repository or embed the data directly, as the example does. It can process that data, generate visualisations, and render knobs and sliders for interactive exploration. No server-side magic required - everything runs client-side in the browser, served by a plain static web server, and very easily to share.

How does it fit in with Anil's four Ps?

Permanence: SVGs can be assigned DOIs just like papers, blog posts, or datasets. The fact that the above SVG still works after two decades is a testament to the durability of the format.
Provenance: Because SVG is plain text, it plays nicely with version control systems such as Git. When an SVG pulls in external data, the same provenance-tracking strategies Anil describes for datasets apply here as well.
Permission: Once again, with the separation between the processing in the SVG and that data that it works on, the same permissioning models apply as for data in general.
Placement: SVGs are inherently spatial; it's very easy, for example, to make beautiful world maps with SVG. The SVG above is only a visualisation tool for data; it doesn't really do any processing, but it certainly could. The biggest change that's happened over the 20 years since I wrote this is the massive increase in the computation power available in the browser. If would be entirely feasible to implement the entire data analysis pipeline for that paper in an SVG today, probably without even spinning up the fans on my laptop!

So this is yet another tool in our ongoing effort to be able to effortlessly share and remix our work - added to the pile of Jupyter notebooks, Marimo botebooks, the slipshow/x-ocaml combination, Patrick's take on Jon Sterling's Forester, my own notebooks, and many others - and this is a subset of what we're using just in our own group!

Foundations of Computer Science

2025-11-14T00:00:00Z

I recently completed lecturing the course "Foundations of Computer Science" to our newly arrived first-year computer scientists here at Cambridge. This is the first time I've lectured this course, taking over from Anil while he's on sabbatical. Although I was very nervous indeed about it, I ended up really enjoying the experience - and I hope the students did too! This post is a little brain dump of my thoughts on how it went and how we might improve it for next year.

Course Overview

The course is 12 lectures long and has been lectured in a similar way since I myself was an undergraduate here, way back in 1996. There have been a few changes, not least of which is that back then it was in Standard ML rather than OCaml, but the core material has remained largely the same: lists, recursive functions, trees, higher-order functions, search and finally mutability. There are no prerequisites for the course, although all students have at least a maths A-level (or equivalent), and almost all of them have done some programming before, though the experience varies widely. Very few have done any functional programming, and even fewer have written any OCaml before.

The notes for the course are distributed both in hard copy and also as an interactive Jupyter Notebook, which we host on our JupyterHub server that I maintain. The idea is that the students can read through the notes and then play around with the code examples directly in the notebook. I don't encourage them or give them time to do much during the lectures - not that I think this is a terrible idea, but it's a struggle to fit all the material in otherwise! The notes are pretty closely coupled to the lectures, organised into 11 chapters that correspond to the first 11 lectures, with exercises at the end of each chapter that are intended to be covered in the supervisions. We also have some assessed exercises - "Ticks" - that the students complete in their own time using the JupyterHub server using nbgrader. They are automatically assessed in a very transparent way; each "tick" is a Jupyter notebook with editable answer cells and read-only test cells. Overall we're aiming for the students not to have to install OCaml locally at all, though I hope many of them will choose to do so anyway.

While I didn't want them playing around with the notebook during the lectures, I do, however, try to get them to interact by getting them to answer questions. It's pretty intimidating to stick your head above the parapet like this, so as an incentive I rewarded those that answered (rightly or wrongly) with some of the excellent stickers that Tarides has printed over the years. Everybody loves stickers!

The questions I asked varied quite a lot in their difficulty, and many were in the first few minutes of each lecture, where I had a short 'warm-up' where we recapped the contents of the previous lecture. These warm-ups were strongly suggested by Anil, and as well as reminding everyone of where we left off, they also gave me a bit of feedback on the things that the students found challenging.

One entertaining aspect is that during the first lecture I do actually encourage them to at least log on to the JupyterHub server, mostly to get them used to the idea of trying it. The entertaining part is that our server isn't particularly big and beefy, and so with 130 students all trying to log on at once, it invariably caves in under the load. At this point in the lecture I ssh to the server and run btop/htop and we watch it die in real time!

What changed this year

During the lectures themselves, rather than use Keynote or PowerPoint for the slides, I decided to try using Slipshow, augmented with x-ocaml to embed executable OCaml code snippets. I'm very happy with how this worked out. I was able to prepare both working and broken snippets, modify them live during the lecture, and things like type-on-hover was very useful. In a few lectures where we were discussing big-O notation, I was able to run code on different input sizes and really demonstrate the big difference in run-time of certain algorithms. After the lectures, I posted the slides onto the course website so that students can refer back to them, and they can also try out the live code snippets directly in the slides.

Both Slipshow and x-ocaml are still quite young projects, so it was inevitable that there were a few rough edges, and in fact the interaction of the two revealed the biggest problem: that when you use the 'speaker-view' mode of Slipshow, where you have a separate window with notes and the current slide, the x-ocaml widgets are effectively independent in the two windows, so updating in one doesn't update in the other. Paul-Elliot, the author of Slipshow, had already got a potential fix for this in the works when I spoke to him about it, so hopefully next time I use this I'll be able to have speaker notes on screen, instead of hand-written index cards! The x-ocaml project is a lot smaller than Slipshow, so I was able to use Claude to help me add functionality I needed, such as being able to programmatically highlight sections of the code.

Another new thing I tried this year was to go over 'tracing' of execution to help the students understand how programs run. We've always taught reduction steps in the course, which works well as it's only the last lecture where we introduce mutability, but it can quickly become unwieldy, and it can be challenging to do this all by hand. Tracing a function tells the runtime to log when function calls and returns happen, so you just need to call the function on your desired input, and you get a fully automatic trace of the execution. As it's only function calls and returns, it doesn't tell the full story, but alongside the handwritten reduction, it can help reassure students that they're on the right track. I ended up writing up a trace of a particularly complicated lazy-list evaluation using Slipshow and x-ocaml, which I posted here.

Thoughts for next year

Overall I'm very happy with how the course went this year, though in some ways it did feel a little bit like the course finished just when it had started to get to the good stuff! There's a Tripos review process going on at the moment, so maybe we'll get to expand this course a bit in future years.

While the Slipshow+x-ocaml combination worked well, the fact that we ended up with two separate systems for executing OCaml wasn't ideal. I think it'd be a really nice project to investigate just how far we can push x-ocaml / Slipshow / some other web technology to have a true "serverless" experience so we can ditch the JupyterHub server entirely. By caching the x-ocaml 'execution' web worker in the browser, we could have a system that works fully offline, removing an annoyingly failure-prone single point of failure. Of course, we'd still need some way to do the assessed exercises, but that's a small point in a much larger problem: we really can't continue to ignore how LLMs are impacting the way that students are approaching these exercises in both positive and negative ways. To answer this properly, we need to think hard about what the purpose of these exercises is and look around to see what our colleagues are doing in this space.

The slide decks themselves are fully open and available on the course website:

Caching opam solutions - part 2

2025-09-23T00:00:00Z

Some results from the previous post. This time I've run day10 on 144 or so commits from opam-repository to see how well the cache performs. The results are quite interesting.

First let's talk about the "examination map". This is a map from package name to a list of other packages whose solutions should be recalculated if the package in question is altered. It's built by first looking at the packages that the solver asks about during the solution for a package, and then taking all of the solutions, and 'inverting' the map, so for example, if both packages 'a' and 'b' ask about package 'c' during their solutions, then altering 'c' means that the solutions for both 'a' and 'b' need to be recalculated. The examination map entry for 'c' would then be 'a'; 'b'. We can plot the histogram of the sizes of each entry in the examination map:

Some interesting features from these data:

The most common number of observers is 1, meaning that the package is not involved in the solution of any other package. There are approximately 2000 such packages.
Most (~80%) of packages have fewer than 100 observers. This means that if we alter one of these packages, we only need to recalculate the solutions for fewer than 100 other packages.
A very small number of packages are observed in all 4,400 solutions. This is actually a bit artificial, as the solver adds the ocaml-compiler package as an input to all solves to ensure we get the correct compiler version. There's another way to do this which would avoid this particular problem.
A small number of packages have a very large number of observers, around 3800. This mostly corresponds with dune and its dependencies and associated packages. There are around 350 such packages, and any change to these means we need to recalcuate most of the solutions. This last point doesn't mean that we actually recompile 3,800 packages, just that we need to recalcualte the solution, which might then lead to a cache hit of the layer and no actual compilation. However, recalculating the solutions of all of the packages takes (on my computer) around 10,000 seconds, or roughly 5 minutes of wall-clock time as I've got 32 threads.

However, if the package that's changes isn't one of those 350 packages, then the number of solutions that need to be recalculated is dramatically reduced. I ran the logic over the last few weeks of commits to opam-repository, from commit 109398e2fd61803126becd398df0f1eabc9f3ca2 of the 10th September up until commit 3f21ebe342ce440d9c9142ffe1185d8e5a326085 from the 22nd. In this time there were 144 commits (counting only those from git log --first-parent). Of these, only 4 resulted in a full resolve - the first commit, since obviously we have no cache at that point, the release of OCaml 5.4.0 beta2 by Florian Angeletti, a fix of ocaml-base-compiler for MSVC by David and a fix for BER-OCaml by Jeremy Yallop. Then 25 commits resulted in recalculating solutions for 3800 packages as they hit dune-adjacent packages, 5 commits resulted in recalculating between 100 and 300 packages and the remaining 110 commits resulted in recalculating fewer than 100 packages, the majority of which resulted in recalculating fewer than 5 packages.

Overall, at a rough estimate, this means that over this period, using this caching strategy gave us a 5x speedup in the solver!

Odoc bugs

2025-09-22T00:00:00Z

This post is a brief write-up of a couple of bugs in odoc that I've been working on over the past 2 weeks. I was convinced at the start of this that I was actually fixing one bug, but although they both had the same backtrace and similar immediate causes, they're actually quite different. They both involve expansion, which is the process that odoc uses to work out the contents of a module from its expression - what allows you to see the contents of a module such as module M = Map.Make(String).

Bug 930: inline destructive substitutions

Bug #930 in odoc is about a substitution problem:

module type S1 = sig
  type t0
  type 'a t := unit

  val x : t0 t
end

module type S2 = sig
  type t (* must be the same name as [S1.t] *)

  include S1 with type t0 := t
end

module type S3 = sig
  type t1

  include S2 with type t := t1
end

which when processed by odoc 2.4 throws an exception:

odoc: internal error, uncaught exception:
      Invalid_argument("List.fold_left2")
      Raised at Stdlib.invalid_arg in file "stdlib.ml", line 33, characters 20-45
      Called from Odoc_xref2__Subst.type_expr in file "subst.ml", line 598, characters 21-59
      Called from Odoc_xref2__Subst.value in file "subst.ml" (inlined), line 842, characters 19-38
      Called from Odoc_xref2__Subst.apply_sig_map.inner.(fun) in file "subst.ml", line 1089, characters 19-52
      Called from Odoc_xref2__Component.Delayed.get in file "component.ml" (inlined), line 55, characters 16-22
      Called from Odoc_xref2__Lang_of.signature_items.inner in file "lang_of.ml", line 438, characters 16-39
      Called from Odoc_xref2__Lang_of.signature in file "lang_of.ml" (inlined), line 466, characters 12-43
      Called from Odoc_xref2__Lang_of.include_ in file "lang_of.ml", line 641, characters 18-69

The key thing here is that definition of 'a t in S1 - a destructive substituion. If you type this code into an OCaml toplevel, you will see that the signature of S1 is:

module type S1 = sig type t0 type 'a t := unit

val x : t0 t end where the substitution has clearly taken place. In contrast, odoc takes the position that the use of these inline destructive substitutions is to make the code easier to understand, and so it tries to keep them in the signature rather than simply apply them and present the resulting signature. So when rendering S1 we end up with:

Module type `S1`

type t0

type 'a t := unit

val x : t0 t

The reported problem is a failure with a stack trace while processing S3, but upon looking closely the real problem has happened when expanding S2. What happens is that we have a type t defined in S2 and a type t that will later be substituted away that comes from the inclusion of S1. The rendered signature of S2 is:

Module type `S2`

type t

include S1 with type t0 := t

type 'a t := unit

val x : t t

where the type of x is now t t, which is clearly incorrect. The problem is that odoc assumes that type names are unique within a signature (modulo shadowing, which isn't quite what's going on here), but in this signature there are two definitions of type t, one of which is parameterised and one is not. At this point nothing fatal has happened, but when we try to process S3 the substitution code gets very confused by these different arities and List.fold_left2 throws the above exception.

The fix I'm trialling for this is that when we're including a signature that contains an inline destructive substitution, we will perform that substitution when the expansion of the include is done. This means that the rendered signature of S1 will be just the same as before, but the rendered signature of S2 will now be:

Module type `S2`

type t

include S1 with type t0 := t

val x : unit

where the type of x is now simply unit, which is what OCaml itself thinks, happily! I think this strikes the balance between keeping the substitutions visible for clarity where they are originally defined, but when including them elsewhere we simply see the resulting signature.

Bug #1385: Exception raised during compilation

The second bug has the identical backtrace, indicating a problem with arities. However, the repro case for this one does not involve any inline destructive substitution, though it does involve destructive substitution at the module expression level:

module type Creators_base = sig
  type ('a, _, _) t
  type (_, _, _) concat

  include sig
      type ('a, 'b, 'c) t

      val concat : (('a, 'p1, 'p2) t, 'p1, 'p2) concat -> ('a, 'p1, 'p2) t
    end
    with type ('a, 'b, 'c) t := ('a, 'b, 'c) t
end

module type S0_with_creators_base = sig
  type t

  include Creators_base with type ('a, _, _) t := t and type ('a, _, _) concat := t
end

There's quite a lot of type parameters flying around here, so the first step was to try to simplify this as much as possible while still getting the exception. I got it down to:

module type Creators_base = sig
  type 'a t
  type _ concat

  include sig
      type 'a t

      val concat : 'a concat -> 'a t
    end
    with type 'a t := 'a t
end

module type S0_with_creators_base = sig
  type t

  include Creators_base with type _ t := t with type _ concat := t
end

which still throws the same exception. So, what's going on here? Fundamentally, it's a similar issue to the first bug, just caused in a different way, in that once again we'll end up with a signature that has two definitions of type t with different arities. In this case, the problem occurs during the expansion of S0_with_creators_base.

This is the intermediate expansion of Creators_base that odoc calculates:

module type S0_with_creators_base = sig
  type t

  include Creators_base with type _ t := t with type _ concat := t (*
    
    The expansion as calculated by odoc is:

      include sig
        type 'a t
        val concat : t -> 'a t
      end
  *)
end

What's happened here is during the calculation of the body of the include, odoc has taken the signature of Creators_base and has its two type definitions both replaced with type t (with no parameters). However, since the type t in the body of the include is defined in that signature, that one wasn't replaced. So we end up with the type of concat being t -> 'a t, which looks very odd! At this point though, odoc knows very well that they're different types. However, when odoc converts this signature back into the datatype that represents the expansions, it loses that information and we end up with the two types mixed up. We then go on to process this signature, the mixup of the arities causes the failure.

There are several independent fixes that we can make here. Firstly we can make sure that we don't mix up the types. This we can do because we can distinguish between items that are declared within the signature of the include's declaration and those that come from the outer context. We don't have to do this for the expansion of the include as OCaml's type system means that there can't be two types of the same name in the resulting signature. We never actually render any signature that occurs within the body of an include, so this doesn't actually make any difference to the output.

The second fix is to make sure that we only calculate the expansion of the include once. Currently the bug happens because we try to re-calculate the expansion of the include sig ... end expression, even though we calculated it during the processing of S0_with_creators_base. What we should do instead is apply the substitutions to the expansion of that calculated include, which would end up with the same result. This isn't a perfect solution though, as there are occasions when we have to recalculate the signature anyway.

The third fix is - and this takes a little care to parse - to ensure that we never actually try to process the items within a signature within a "with" expression within a module-type expression. Before diving into the 'why' of this, let's first explain how Odoc represents module-type expressions.

Internally, we have a datatype that represents module expressions, which looks like this:

type expr =
    | Path of path_t
    | Signature of Signature.t
    | Functor of FunctorParameter.t * expr
    | With of with_t
    | TypeOf of typeof_t

Now, each of the arguments to these constructors might contain an expansion of the expression that Odoc will calculate. For example, the definition of path_t is:

type path_t = {
    p_expansion : simple_expansion option;
    p_path : Paths.Path.ModuleType.t;
}

and this expansion is initially None and then filled in by Odoc in order to render the expansion in the HTML. In the case of a With expression, the with_t type is:

type with_t = {
    w_substitutions : substitution list;
    w_expansion : simple_expansion option;
    w_expr : U.expr;
}

here you can see that the With expression contains another module expression, as a with expression operates on another module type. Early during Odoc's development, this simply was another `ModuleType.expr`, but we had a couple of bugs where we ended up calculating expansions for these inner expressions, which was all very wasteful as we only ever rendered the "outer" expansion. So we changed this to be a U.expr, which is an "unexpanded" module type expression, and is very similar to the main expression above, but without the expansions and also with the functor case, as we can't have functors inside a "with" expression.

These "unexpanded" expressions still contain signatures though, so aren't completely unexpanded, and it's these signatures that we should avoid processing.

So, what I expected to be just one bug when I started looking at this turned out to be two related issues, and a total of four different fixes!

Caching opam solutions

2025-09-09T00:00:00Z

The ocaml-docs-ci system works by watching opam-repository for changes, and then when it notices a new package it performs an opam solve and builds the package, a prerequisite for building the documentation. In order to give the docs some stability, as the docs may well depend upon your dependencies, we currently cache the solve results so that a package will always be built with the same set of dependencies, even if a new version of one of those dependencies has been released.

The downside to this is that as time goes on, the number of distinct universes that we build increases, and docs get more and more out of date. So it's not necessarily the best thing to do, though it does mean we minimise the amount of time spent solving.

The alternative approach is that on every commit to opam-repository we could resolve for all packages and use the latest, greatest solution to build the docs. Using this approach we would maximise the sharing of builds and keep the total amount of required storage steadier. Of course, this would mean solving for every package on every commit to opam-repository, even if we didn't end up rebuilding all of them due to the way that the cache works.

One possibility that might be worth investigating is to cache the solutions - but then Leon Bambrick advises us:

There are 2 hard problems in computer science: cache invalidation,
naming things, and off-by-1 errors.

and indeed it's not obvious what the best approach to cache invalidation is here. A sledgehammer approach would be to hook into the solver and note what questions it asks of opam-repository and record the responses. If any of these change, then it's safe to say that we need to recalculate. I had a quick look at this and checked what packages were involved in the solution of ocaml as this would represent a minimum set of packages that would affect virtually all packages. The list was big, but not too big:

winpthreads, system-msvc, system-mingw, ocaml-variants, ocaml-system,
ocaml-options-vanilla, ocaml-option-tsan, ocaml-option-static,
ocaml-option-spacetime, ocaml-option-no-flat-float-array,
ocaml-option-no-compression, ocaml-option-nnpchecker,
ocaml-option-nnp, ocaml-option-musl, ocaml-option-mingw,
ocaml-option-leak-sanitizer, ocaml-option-fp, ocaml-option-flambda,
ocaml-option-default-unsafe-string, ocaml-option-bytecode-only,
ocaml-option-afl, ocaml-option-address-sanitizer,ocaml-option-32bit,
ocaml-config, ocaml-compiler, ocaml-beta, ocaml-base-compiler, ocaml,
dkml-base-compiler, conf-unwind, conf-pkg-config, base-unix,
base-threads, base-ocamlbuild, base-nnp, base-metaocaml-ocamlfind,
base-implicits, base-effects, base-domains, base-bigarray

I tried the same thing whilst using the oxcaml opam-repository, and this time, the list became much much larger:

zed, zarith-xen, zarith-freestanding, zarith, yojson, xenstore, xdg,
x509, webbrowser, wasm_of_ocaml-compiler, variantslib, uutf, uuseg,
uunf, uucp, uTop, uri-sexp, uri, uopt, univ_map, uchar, tyxml,
typerex, typerep, trie, topkg, tls-lwt, tls, timezone, time_now,
textutils_kernel, textutils, tcpip, system-msvc, system-mingw,
swhid_core, stringext, string_dict, stdune, stdlib-shims, stdio, ssl,
splittable_random, spdx_licenses, spawn, shell,
shared-memory-ring-lwt, shared-memory-ring, sha, sexplib0, sexplib,
sexp_pretty, seq, sedlex, rresult, result, regex_parser_intf,
record_builder, react, re2, re, randomconv, publish, ptime, psq,
protocol_version_header, ppxlib_jane, ppxlib_ast, ppxlib, ppxfind,
ppx_yojson_conv_lib, ppx_yojson_conv, ppx_variants_conv, ppx_var_name,
ppx_typerep_conv, ppx_typed_fields, ppx_tydi, ppx_tools_versioned,
ppx_tools, ppx_template, ppx_string_conv, ppx_string,
ppx_stable_witness, ppx_stable, ppx_shorthand, ppx_sexp_value,
ppx_sexp_message, ppx_sexp_conv, ppx_pipebang, ppx_optional,
ppx_optcomp, ppx_module_timer, ppx_log, ppx_let, ppx_js_style,
ppx_jane, ppx_inline_test, ppx_ignore_instrumentation, ppx_here,
ppx_helpers, ppx_hash, ppx_globalize, ppx_fixed_literal,
ppx_fields_conv, ppx_fail, ppx_expect, ppx_enumerate,
ppx_disable_unused_warnings, ppx_diff, ppx_deriving, ppx_derivers,
ppx_custom_printf, ppx_cstruct, ppx_compare, ppx_cold, ppx_bin_prot,
ppx_bench, ppx_base, ppx_assert, pp, portable, pipe_with_writer_error,
pcre, pbkdf, patch, parsexp, ounit2, ordering, optint, opam-state,
opam-repository, opam-publish, opam-lib, opam-format,
opam-file-format, opam-core, ojs, ohex, odoc-parser, odoc, octavius,
ocplib-endian, ocp-indent, ocp-build, ocb-stubblr, ocamlnet,
ocamlgraph, ocamlformat-rpc-lib, ocamlformat-lib, ocamlformat,
ocamlfind-secondary, ocamlfind, ocamlc-loc, ocamlbuild,
ocaml_intrinsics_kernel, ocaml_intrinsics, ocaml-version,
ocaml-variants, ocaml-system, ocaml-syntax-shims,
ocaml-secondary-compiler, ocaml-options-vanilla, ocaml-option-tsan,
ocaml-option-static, ocaml-option-spacetime,
ocaml-option-no-flat-float-array, ocaml-option-no-compression,
ocaml-option-nnpchecker, ocaml-option-nnp, ocaml-option-musl,
ocaml-option-mingw, ocaml-option-leak-sanitizer, ocaml-option-fp,
ocaml-option-flambda, ocaml-option-default-unsafe-string,
ocaml-option-bytecode-only, ocaml-option-afl,
ocaml-option-address-sanitizer, ocaml-option-32bit,
ocaml-migrate-parsetree, ocaml-lsp-server, ocaml-index,
ocaml-freestanding, ocaml-config, ocaml-compiler-libs,
ocaml-base-compiler, ocaml, obuild, num, nocrypto, mtime, mmap,
mirage-xen-posix, mirage-xen, mirage-types, mirage-time, mirage-stack,
mirage-solo5, mirage-sleep, mirage-runtime, mirage-random,
mirage-ptime, mirage-protocols, mirage-profile, mirage-no-xen,
mirage-no-solo5, mirage-net-xen, mirage-net, mirage-mtime,
mirage-kv-mem, mirage-kv-lwt, mirage-kv, mirage-flow, mirage-entropy,
mirage-device, mirage-crypto-rng-mirage, mirage-crypto-rng-lwt,
mirage-crypto-rng, mirage-crypto-pk, mirage-crypto-ec, mirage-crypto,
mirage-clock-unix, mirage-clock-lwt, mirage-clock, mew_vi, mew,
metrics-lwt, metrics, merlin-lib, merlin, menhirSdk, menhirLib,
menhirCST, menhir, mdx, magic-mime, macaddr-cstruct, macaddr, lwt_ssl,
lwt_react, lwt_ppx, lwt_log, lwt-dllist, lwt, lsp, lru, logs,
lambda-term, kdf, jst-config, jsonrpc, jsonm, js_of_ocaml-toplevel,
js_of_ocaml-ppx, js_of_ocaml-lwt, js_of_ocaml-compiler, js_of_ocaml,
jbuilder, jane_rope, jane-street-headers, ipaddr-sexp, ipaddr-cstruct,
ipaddr, io-page, int_repr, http, hkdf, hex, hacl_x25519, gmap,
github-unix, github-data, github, gen_js_api, gen, gel,
functoria-runtime, fpath, fmt, fix, fieldslib, fiber, fiat-p256,
ezjsonm, extlib-compat, extlib, expectree, expect_test_helpers_core,
ethernet, eqaf, either, easy-format, dyn, duration, dune-site,
dune-rpc, dune-release, dune-private-libs, dune-configurator,
dune-compiledb, dune-build-info, dune, dot-merlin-reader, domain-name,
dkml-base-compiler, digestif, curly, cstruct-sexp, cstruct-lwt,
cstruct, csexp, crunch, cpuid, cppo, core_unix, core_kernel,
core_extended, core, configurator, conf-which, conf-unwind,
conf-pkg-config, conf-ninja, conf-m4, conf-libssl, conf-libpcre,
conf-gmp-powm-sec, conf-gmp, conf-g++, conf-cmake, conf-c++,
conf-bash, conf-autoconf, conduit-lwt-unix, conduit-lwt, conduit,
cohttp-lwt-unix, cohttp-lwt-jsoo, cohttp-lwt, cohttp, cmdliner,
cmarkit, chrome-trace, charInfo_width, capitalization, camomile,
camlp4, camlp-streams, ca-certs, bos, biniou, binaryen-bin, bin_prot,
bigstringaf, bigarray-compat, bheap, basement, base_quickcheck,
base_bigstring, base64, base-unix, base-threads, base-ocamlbuild,
base-num, base-nnp, base-effects, base-domains, base-bytes,
base-bigarray, base, backoff, atdgen-runtime, atdgen, atd, async_unix,
async_rpc_kernel, async_log, async_kernel, async_extra, async,
astring, asn1-combinators, arp, angstrom, alcotest

This enormous list is because the opam file for oxcaml - ocaml-variants.5.2.0+ox - lists a bunch of conflicts to ensure that various incompatible packages are never selected:

conflicts: [
  "base" {< "v0.18~"}
  "alcotest" {!= "1.9.0+ox"}
  "backoff" {!= "0.1.1+ox"}
  "dot-merlin-reader" {!= "5.2.1-502+ox"}
  "gen_js_api" {!= "1.1.2+ox"}
  "js_of_ocaml" {!= "6.0.1+ox"}
  "js_of_ocaml-compiler" {!= "6.0.1+ox"}
  "js_of_ocaml-ppx" {!= "6.0.1+ox"}
  "js_of_ocaml-toplevel" {!= "6.0.1+ox"}
  "jsonrpc" {!= "1.19.0+ox"}
  "lsp" {!= "1.19.0+ox"}
  "lwt_ppx" {!= "5.9.1+ox"}
  "mdx" {!= "2.5.0+ox"}
  "merlin" {!= "5.2.1-502+ox"}
  "merlin-lib" {!= "5.2.1-502+ox"}
  "ocaml-compiler-libs" {!= "v0.17.0+ox"}
  "ocaml-index" {!= "1.1+ox"}
  "ocaml-lsp-server" {!= "1.19.0+ox"}
  "ocamlbuild" {!= "0.15.0+ox"}
  "ocamlformat" {!= "0.26.2+ox"}
  "ocamlformat-lib" {!= "0.26.2+ox"}
  "ojs" {!= "1.1.2+ox"}
  "ppxlib" {!= "0.33.0+ox"}
  "ppxlib_ast" {!= "0.33.0+ox"}
  "sedlex" {!= "3.3+ox"}
  "topkg" {!= "1.0.8+ox"}
  "uTop" {!= "2.15.0+ox"}
  "uutf" {!= "1.0.3+ox"}
  "wasm_of_ocaml-compiler" {!= "6.0.1+ox"}
  "zarith" {!= "1.12+ox"}
]

and it seems that the solver is looking not just at these packages, but also at all of their dependencies too. So this is a much larger set of packages that we need to track changes for, probably making the caching an awful lot less effective. It's not clear to me that this is the best way for the solver to handle conflicts, but I don't know enough about how it works yet to say for sure.

Build IDs for Day10

2025-09-08T00:00:00Z

mtelvers, dra27 and I have been working on a system to build opam packages similar to the way that the docs-ci system does - effectively building a per-package binary cache to do very fast builds of the entire opam repository. It supports building even mutually-incompatible packages by dynamically creating the build environment for each package, and thus allows us to generate something akin to opam health check but much faster.

Currently the cache of a package is a key-value store where the key is a hash of the package name and version and all of its dependencies and their name and version, alongside some information about the OS. This is great when this info can uniquely identify the output, but this isn't always the case. In particular, the oxcaml opam-repository has several packages where the version number is the upstream version number with `-ox` appended, as they have patches to make them compatible with oxcaml. If these patches change without bumping the suffix the currently caching mechanism would lead to trouble. When we discussed this David pointed out the idea of the build-id in opam, which would perfectly satisfy our needs. Unfortunately this code is quite deep within the opam codebase and at the point we need it we don't have an installed opam switch, so we need to pull the code out and insert it into our project.

One of the first challenges was that day10 currently includes the OS details in the hash so that we can test across different distros. This is at odds with the opam build-id which doesn't include that, so in order to try to get as close as possible to the opam hash I split the cache into 2 layers - a per-OS cache directory containing hashes based on pure opam metadata. The idea is that these should be identical to the build-ids of opam. With that fixed, the new cache layout looks like:

debian-12-x86_64/123...abc/{build.log,config,...}

where the 123...abc should be the same as the build-id you would get with all the packages contained installed.

Now my actual use case for this is to track the state of the oxcaml world day by day, so for this I need to track both the opam-repository for OCaml and also the opam repository for OxCaml. The project currently uses a Makefile for coordinating the builds, but I thought it was time we moved on to a dedicated batch execution process. So I asked Claude to knock me up one of those, using odoc_driver for inspiration. It's very basic right now, simply iterating through the latest versions of every package, but I have got it to check on cache hits and misses, so I should be able to run it tomorrow to see how quickly we can test PRs to oxcaml/opam-repository

Giving hub.cl an upgrade

2025-09-07T00:00:00Z

For a few years now we've been running hub.cl.cam.ac.uk, a Jupyterhub instance, for the first year course "Foundations of Computer Science". It serves as a hosting site for the lecture notes, which come in the form of Jupyter notebooks, and as a playground where students can try OCaml, and it also is used to run the assessed exercises that are a mandatory part of the course.

Since I spent some time setting it up back in 2018 or so, its aggregated some cruft over the years, and has also fallen somewhat behind the bleeding edge of the Jupyter software stack. So I thought this year, as I'm actually lecturing the course, I'd give it a bit of loving care and attention.

We were still on Jupyterhub 1.5.3 whereas the current release is 5.3.0 - so there was quite a bit of work to do. I brief play with putting things on the latest version seemed to break quite a lot of things, so I thought it might be better to go back to the drawing board and start the config again from scratch. So with some help from Claude, I've now managed to hugely simplify the whole config of Jupyterhub, and even given it a makeover to try to match the style of www.cst.cam.ac.uk as well. The improvements include:

Using caddy as a reverse proxy for TLS termination, meaning I don't have to manually renew the letsencrypt cert every 3 months
Unifying the configuration of the two container images used for students and instructors
Upgrading to much newer jupyterhub, notebook and nbgrader images
Simplifying the configuration required to make it work on a new server - persistent user directories are now docker volumes rather than bindmounts on the local filesystem
Updating the authentication method to use Raven via OAuth2 rather than the unmaintained jupyterhub-raven-auth which I'd had to maintain a patch.
Rebasing my patch to nbgrader to verify all of the output of the cells when grading answers As ever, this took longer than I'd anticipated, but I'm mostly there now. There are a few more steps to try:
trial the new patch for using ocaml-jupyter with OCaml 5.x
see how to upgrade to notebook v7, as I've stuck with v6 in order to keep the extensions we're using going.

Using ocaml-lsp-server via an MCP server

2025-08-27T00:00:00Z

Here's a quick post on how to get the OCaml Language Server (ocaml-lsp-server) working with an MCP server.

We're going to use issacphi's adapter for LSP servers, which is written in go. So install go, and then:

go install github.com/isaacphi/mcp-language-server@latest

Once that's done, make sure you've got `ocaml-lsp-server` installed in your switch:

opam install ocaml-lsp-server

Then add the MCP config for claude where you want to run it:

claude mcp add ocamllsp -s local -t stdio -- /Users/jon/go/bin/mcp-language-server -workspace . -lsp ocamllsp

It'd be nice to get this working `globally` - that is, with `-s user` - but I haven't been able to get that to work yet.

An OCaml MCP server

2025-08-20T00:00:00Z

LLMs are proving themselves superbly capable of a variety of coding tasks, having been trained against the enormous amount of code, tutorials and manuals available online. However, with smaller languages like OCaml there simply isn't enough training material out there, particularly when it comes to new language features like effects or new packages that haven't had time to be widely used. With my colleagues Anil, Ryan and Sadiq we've been exploring ways to improve this situation. One way we can mitigate these challenges is to provide a Model Context Protocol (MCP) server that's capable of providing up-to-date info on the current state of the OCaml world.

The MCP specification was released by Anthropic at the end of last year. Since then it has become an astonishingly popular mechanism for extending the capabilities of LLMs, allowing them to become incredibly powerful agents capable of much more than simply chatting. There are now a huge variety of MCP servers, from one that provides professional cycling data to one that can do your email. The awesome mcp server list already lists hundreds, and these are just the awesome ones!

I've been working with Sadiq to make an MCP server for OCaml, with an initial focus on building it such that it can be hosted for everyone rather than something that is run locally. Our plan is to start with a service that can help with choosing OCaml libraries, by taking advantage of the work done by ocaml-docs-ci which is the tool used to generate the documentation for all packages in opam-repository and is served by ocaml.org. As well as producing HTML docs, we can also extract a number of other formats from the pipeline, including a newly created markdown backend. Using this, we can get markdown-formatted documentation for the every version of every package in the OCaml ecosystem.

Semantic searching

The first thing we focused on was being able to do a semantic search over the whole OCaml ecosystem. To do this, we're using LLM embeddings, for which we need some natural-language description to seach through.

The documentation produced by ocaml-docs-ci is generated per library module using odoc, relying on the package author to provide documentation comments for each element in the signature. However, even if the package authors hasn't provided any documentation, we can still see the types, values, modules and so on that the library exposes, and this is often enough to get a good idea of what the module does. We then take these documentation pages, which are formatted in markdown, and summarise them via an LLM at the module level. This is done hierarchically, so we start with the 'deepest' modules, and then insert their summaries into the text of their parent module, then summarise those and so on. We found it useful to include the names and preambles of the ancestor modules when doing the summarisation to give additional context to the LLM. For example, here is the prompt generated for a submodule of the astring library:

Module: Astring.String.Ascii

Ancestor Module Context:
- Astring: Alternative `Char` and `String` modules. Open the module to
use it. This defines one value in your scope, redefines the `(^)`
operator, the `Char` module and the `String` module. Consult the
differences with the OCaml `String` module, the porting guide and a
few examples.
- Astring.String: Strings, `substrings`, string sets and maps. A
string `s` of length `l` is a zero-based indexed sequence of `l`
bytes. An index `i` of `s` is an integer in the range [`0`;`l-1`], it
represents the `i`th byte of `s` which can be accessed using the
string indexing operator `s.[i]`.
Important. OCaml's `string`s became immutable since 4.02. Whenever
possible compile your code with the `-safe-string` option. This module
does not expose any mutable operation on strings and assumes strings
are immutable. See the porting guide.

Module Documentation: US-ASCII string support.
References.

## Predicates
- val is_valid : string -> bool (* `is_valid s` is `true` iff only for
  all indices `i` of `s`, `s.[i]` is an US-ASCII character, i.e. a
  byte in the range [`0x00`;`0x7F`]. *)

## Casing transforms
The following functions act only on US-ASCII code points that is on
bytes in range [`0x00`;`0x7F`], leaving any other byte intact. The
functions can be safely used on UTF-8 encoded strings; they will of
course only deal with US-ASCII casings.

- val uppercase : string -> string (* `uppercase s` is `s` with
  US-ASCII characters `'a'` to `'z'` mapped to `'A'` to `'Z'`. *)
- val lowercase : string -> string (* `lowercase s` is `s` with
  US-ASCII characters `'A'` to `'Z'` mapped to `'a'` to `'z'`. *)
- val capitalize : string -> string (* `capitalize s` is like
  `uppercase` but performs the map only on `s.[0]`. *)
- val uncapitalize : string -> string (* `uncapitalize s` is like
  `lowercase` but performs the map only on `s.[0]`. *)

## Escaping to printable US-ASCII
- val escape : string -> string (* `escape s` is `s` with: *)
- val unescape : string -> string option (* `unescape s` unescapes
  what `escape` did. The letters of hex escapes can be upper, lower or
  mixed case, and any two letter hex escape is decoded to its
  corresponding byte. Any other escape not defined by `escape` or
  truncated escape makes the function return `None`. *)
- val escape_string : string -> string (* `escape_string s` is like
  `escape` except it escapes `s` according to OCaml's lexical
  conventions for strings with: *)
- val unescape_string : string -> string option (* `unescape_string`
  is to `escape_string` what `unescape` is to `escape` and also
  additionally unescapes the sequence `"\\'"` (`0x5C,0x27`) to `"'"`
  (`0x27`). *)

where clearly the package author has provided excellent documentation comments. This is then passed to an LLM which generated the following description:

This module provides functions to check if a string contains only
US-ASCII characters, convert case for ASCII letters, and escape or
unescape strings using ASCII conventions. It operates on standard
OCaml strings, treating them as sequences of bytes, and ensures
compatibility with UTF-8 encoded strings when transforming case. Use
cases include sanitizing input for ASCII-only protocols, preparing
strings for environments requiring strict ASCII formatting, and
handling escaped string representations in configuration or
serialization contexts.

Once we have these natural language descriptions, we can generate embeddings for them to allow for semantic search amongst all modules in opam.

In addition to the module descriptions, we also generate similar natural-language descriptions of the package as a whole, by taking the README from the package and summarising it similarly. Where there is no README, we summarise the summaries of the modules of the libraries, so we're always able to generate some text description of the entire package.

To help with the ranking, we're also using a measure of popularity for both modules and packages. For packages, we're using the number of reverse dependencies in opam as a proxy for popularity, and for modules, we're using the "occurrences" generated as part of the docs build. These [occurrences] are a count of how often modules are used in other modules, and are calculated by looking at the compiled [cmt] files and resolving references to external modules using odoc's internal logic and counting them.

Once we have both the module and package summaries, we generate an embedding of the descriptions to allow for a semantic search to be performed efficiently. We're using this in two ways - to search for packages for broad queries of functionality, which just uses the package summaries, and for more specific queries to search for modules within packages.

For the module search, if the packages to search in haven't been specified, we search for both modules and packages and then combine the results. This is particularly helpful when the search is for generic functionality that might be found in more specific packages. For example, a module-only search for the term "time and date manipulation functions" returns the strongest match with a module from caqti, which, as caqti is a library for talking to relational databases, might not be what the user is looking for.

We then put these search tools into an MCP server, along with a little more functionality. The server currently provides these five functions:

Search for OCaml packages
Search for OCaml modules (optionally within packages)
Get the summary description of a package
Get the raw Markdown docs for a module (optionally within a package)
Search using sherldoc The first 2 use the LLM-generated summaries as described above, and the last is using Arthur's sherlodoc tool which can do various searches, including type-based search, across the output of the ocaml-docs-ci.

Example searches

The following are the results from some example package searches:

"HTTP client"

#1 - http (v6.1.1)
  Similarity: 0.7593
  Reverse Dependencies: 407
  Combined Score: 0.6588
  Description: This package provides a comprehensive OCaml library for
building HTTP clients and servers with support for multiple
asynchronous programming model s. It enables developers to implement
efficient, portable HTTP services using different backends such as
Lwt, Async, Eio, and JavaScript, making it suitable for both Unix and
browser environments. The library emphasizes performance, modularity,
and interoperability, allowing custom backend implementations and
seamless in tegration with other OCaml libraries. It is commonly used
in web services, API clients, standalone microkernels, and
OCaml-to-JavaScript compilations for web app lications.

#2 - cohttp (v6.1.1)
  Similarity: 0.7377
  Reverse Dependencies: 403
  Combined Score: 0.6435
  Description: This package provides a comprehensive library for
 building HTTP clients and servers in OCaml. It supports multiple
asynchronous programming models and backends, enabling flexible
development across different runtime environments. The library offers
efficient handling of HTTP/1.1 and HTTPS, with portable pa rsing and
modular architecture. It is widely used for web services, API clients,
and standalone network applications.

#3 - cohttp-lwt-unix (v6.1.1)
  Similarity: 0.7089
  Reverse Dependencies: 338
  Combined Score: 0.6212
  Description: This package provides an implementation of the Cohttp
library using the Lwt asynchronous programming framework with Unix
bindings. It enables buil ding efficient HTTP clients and servers in
OCaml, supporting both synchronous and asynchronous network
operations. The package handles core HTTP functionality, i ncluding
request and response parsing, connection management, and HTTPS support
via OCaml-TLS. It is suitable for applications requiring
high-performance web ser vices, microservices, or networked
applications in the OCaml ecosystem.

#4 - cohttp-lwt (v6.1.1)
  Similarity: 0.7067
  Reverse Dependencies: 367
  Combined Score: 0.6207
  Description: This package provides a comprehensive library for
 building HTTP clients and servers in OCaml, supporting multiple
asynchronous programming models. It enables developers to implement
 efficient, portable HTTP services with support for both synchronous
 and asynchronous I/O, including secure HTTPS communicatio n. The
 package includes backends for Lwt, Async, Mirage, JavaScript, and
 Eio, making it versatile for use in different runtime environments,
 from Unix servers to web browsers. It is well-suited for applications
 requiring high-performance networking, such as web services, API
 clients, and embedded networked systems.

#5 - quests (v0.1.3)
  Similarity: 0.7960
  Reverse Dependencies: 1
  Combined Score: 0.6180
  Description: This package provides a high-level HTTP client library
for making web requests in OCaml. It simplifies interacting with HTTP
 servers by offering a n intuitive API for common methods like GET and
 POST, supporting features such as query parameters, form and JSON
 data submission, and automatic handling of gzip compression and
 redirects. It also includes authentication mechanisms like basic and
 bearer tokens, with partial support for sessions. Typical use cases
 include consuming REST APIs, scraping web content, or integrating
 with web services securely and efficiently.

#6 - ezcurl (v0.2.4)
  Similarity: 0.7395
  Reverse Dependencies: 6
  Combined Score: 0.5979
  Description: This package provides a simplified interface for making
HTTP requests in OCaml, built on top of the OCurl library. It
addresses the need for an ea sy-to-use, reliable, and stable API for
handling common web interaction tasks, such as fetching URLs and
processing responses. The package supports both synchron ous and
asynchronous operations, enabling efficient handling of parallel
requests and non-blocking I/O. Practical use cases include web
scraping, API client deve lopment, and integrating HTTP-based services
into OCaml applications.


{2 "Cryptographic hash"}

{@nolang[
#1 - digestif (v1.3.0)
  Similarity: 0.8165
  Reverse Dependencies: 621
  Combined Score: 0.7041
  Description: This package provides a comprehensive implementation of
  cryptographic hash functions, supporting algorithms such as MD5,
  SHA1, SHA2, SHA3, WHIRLPOOL, BLAKE2, and RIPEMD160. It allows users
  to choose between C and OCaml backends at link time, offering
  flexibility in performance and deployment scenarios. The library is
  designed for applications requiring secure hashing, such as data
  integrity verification, digital signatures, and cryptographic
  protocols. It is well-suited for systems programming and
  security-related applications in the OCaml ecosystem.

#2 - ppx_hash (vv0.17.0)
  Similarity: 0.7284
  Reverse Dependencies: 3337
  Combined Score: 0.6833
  Description: This package generates efficient hash functions for
  OCaml types based on their structure, enabling precise control over
  hashing behavior. It addresses the limitations of OCaml's built-in
  polymorphic hashing by allowing users to define custom hash
  functions during type derivation. Key features include selective
  field ignoring, support for folding-style hash accumulation, and
  compatibility with comparison and serialization systems. It is
  suitable for use with hash tables, persistent data structures, and
  any application requiring deterministic, type-driven hashing.

#3 - ez_hash (v0.5.3)
  Similarity: 0.8366
  Reverse Dependencies: 3
  Combined Score: 0.6583
  Description: This package provides a straightforward interface to
  common cryptographic hash functions, simplifying their use in OCaml
  applications. It wraps secure, widely-used algorithms like SHA-256
  and Blake2b, offering consistent and safe APIs for hashing data. The
  library is designed for clarity and ease of integration, making it
  ideal for developers needing reliable cryptographic operations
  without deep expertise in security. Practical uses include data
  integrity verification, digital signatures, and secure data storage.

#4 - murmur3 (v0.3)
  Similarity: 0.7805
  Reverse Dependencies: 1
  Combined Score: 0.6072
  Description: This package provides OCaml bindings for MurmurHash, a
fast and widely used non-cryptographic hash function. It enables
 efficient hash value compu tation for arbitrary data, making it
suitable for applications like hash tables, checksums, and data
fingerprinting. The bindings offer consistent hashing across platforms
and integrate seamlessly into OCaml projects requiring
high-performance hashing. Use cases include caching, distributed
systems, and data integrity ve rification where cryptographic security
is not required.

#5 - kdf (v1.0.0)
  Similarity: 0.6775
  Reverse Dependencies: 473
  Combined Score: 0.6033
  Description: This package implements standard key derivation
functions (KDFs) for cryptographic applications in OCaml. It supports
scrypt, PBKDF1, PBKDF2, and HKDF, enabling secure generation of
cryptographic keys from passwords or shared secrets. These functions
help mitigate brute-force attacks and ensure keys are de rived in a
reproducible, secure manner. Use cases include password-based
encryption, secure token generation, and key material expansion in
cryptographic protocols.

Module-level search : "time and date manipulation functions"

#1 - timmy-jsoo: Timmy_jsoo
  Similarity: 0.5460
  Original Similarity: 0.7800
  Popularity Score: 0.0000
  Description: This module provides precise date and time arithmetic,
conversion, and comparison operations across multiple representations,
including OCaml-nati ve, JavaScript, and string formats. It works with
structured types like `Date.t`, `Time.t`, and ISO weeks, supporting
timezone-aware transformations and RFC3339 formatting. Concrete use
cases include cross-runtime timestamp synchronization, calendar-aware
scheduling, and robust temporal data validation in distributed
systems.

#2 - calendar: CalendarLib
  Similarity: 0.5331
  Original Similarity: 0.7616
  Popularity Score: 0.3448
  Description: This module provides precise date and time manipulation
  with support for calendar operations, time zones, periods, and
  formatted input/output. It works with types like `Calendar.t`,
  `Date.t`, `Time.t`, and `Period.t` to handle tasks such as event
  scheduling, timestamp conversion, and historical date calculations.
  Concrete use cases include scheduling systems, log timestamping,
  holiday calculations, and cross-timezone time normalization.

#3 - calendar: CalendarLib.Fcalendar
  Similarity: 0.5191
  Original Similarity: 0.6820
  Popularity Score: 0.1390
  Description: This module provides float-based calendar operations
  for date creation, conversion, and manipulation, including time zone
  adjustments, component extraction (year/month/day/hour/second), and
  arithmetic with periods. It works with a `t` type representing time
  as float seconds, alongside `day`, `month`, `year`, and Unix time
  structures, prioritizing Unix time precision over sub-second
  accuracy. It suits applications tolerating minor imprecision in date
  comparisons or arithmetic, such as logging systems or coarse-grained
  scheduling, where exact floating-point equality isn't critical.

#4 - calendar: CalendarLib.Calendar_builder.Make
  Similarity: 0.5112
  Original Similarity: 0.7302
  Popularity Score: 0.0785
  Description: This module combines date and time functionality to
  construct and manipulate calendar values with float-based precision,
  offering operations like timezone conversion, component extraction
  (day, month, year, etc.), and arithmetic using `Period.t`. It works
  with a calendar type `t` that integrates date and time components,
  alongside conversions to Unix timestamps, Julian day numbers, and
  structured representations like `Unix.tm`. Designed for scenarios
  requiring precise temporal calculations (e.g., calendar arithmetic,
  Gregorian date validation, or leap day checks), it balances
  flexibility with known precision limitations inherent to float-based
  time representations.

#5 - timmy-unix: Clock
  Similarity: 0.5080
  Original Similarity: 0.7257
  Popularity Score: 0.0000
  Description: This module provides functions to retrieve the current
  POSIX time, the local timezone, and the current date in the local
  timezone. It works with time and date types from the Timmy library,
  specifically `Timmy.Time.t` and `Timmy.Date.t`. Use this module to
  obtain precise time and date information for logging, scheduling, or
  time-based computations.

Module-level search: "Balanced Tree"

#1 - grenier: Mbt
  Similarity: 0.5274
  Original Similarity: 0.7534
  Popularity Score: 0.0495
  Description: This module implements a balanced binary tree structure
  with efficient concatenation and size-based operations. It supports
  tree construction through leaf and node functions, automatically
  balancing nodes and annotating them with values from a provided
  measure module. It is useful for applications requiring fast access,
  dynamic sequence management, and efficient merging of tree-based
  data structures.

#2 - camomile: CamomileLib.AvlTree
  Similarity: 0.5008
  Original Similarity: 0.7155
  Popularity Score: 0.0495
  Description: This module implements balanced binary trees (AVL
  trees) with operations for constructing, deconstructing, and
  traversing trees. It supports key operations like inserting nodes,
  extracting leftmost/rightmost elements, concatenating trees, and
  folding or iterating over elements. It is useful for maintaining
  ordered data with efficient lookup, insertion, and deletion, such as
  in symbol tables or priority queues.

#3 - batteries: BatAvlTree
  Similarity: 0.5003
  Original Similarity: 0.7147
  Popularity Score: 0.1485
  Description: This module implements balanced binary trees (AVL
  trees) with operations for creating, modifying, and traversing
  trees. It supports tree construction with optional rebalancing,
  splitting, and concatenation, and provides root, left, and right
  accessors with failure handling. Concrete use cases include
  efficient ordered key-value storage, set-like structures, and
  maintaining sorted data with logarithmic-time insertions and
  lookups.

#4 - grenier: Bt2
  Similarity: 0.4927
  Original Similarity: 0.7039
  Popularity Score: 0.2634
  Description: This module implements a balanced binary tree structure
  with efficient concatenation and rank-based access. It supports
  creating empty trees, constructing balanced nodes, and joining two
  trees with logarithmic cost relative to the smaller tree's size. Use
  cases include maintaining ordered collections with frequent splits
  and joins, and efficiently accessing elements by position.

#5 - grenier: Mbt.Make
  Similarity: 0.4913
  Original Similarity: 0.7019
  Popularity Score: 0.0495
  Description: This module implements a balanced tree structure with
  efficient concatenation and size-based operations. It supports
  construction of trees using leaf and node functions, where nodes are
  automatically balanced and annotated with measurable values from
  module M. The module enables efficient rank queries and joining of
  trees, with applications in managing dynamic sequences where fast
  access and concatenation are critical.

Limitations and future work

We're aware that there are currently a number of limitations with what's been done so far, and there's a lot of exciting things that could quite easily be added!

We haven't done much prompt optimisation either for the tools themselves, nor their descriptions in the MCP server. We also haven't done much optimisation of the information retrieval - and it's clear from some of the results shown above that there are improvements to be made in the ranking algorithms. Some obvious next steps would be to do some re-ranking or some form of hybrid search.

A particular challenge is that since this is based entirely off of the ocaml-docs-ci build, it won't necessarily reflect the actual API your local build, as for OCaml, this can't be done. Thibaut Mattio is working on a local MCP server that would be perfectly positioned to do some of what we're doing, although we'd need to have a good local docs build implemented in dune for this to work well.

Also, there's plenty more data that we've collected during the docs builds! We can show the implementations of functions, we can expose code samples, select different versions of packages and much more. While we've concentrated on the search aspects, there's still a lot of low-hanging fruit that can be worked on.

If you're interested in helping us out on this, the project lives on github - come along and join us!

Using the server

If you'd like to try it, we've got a demo server running right now. It's hosted on dill.caelum.ci.dev here at the Computer Laboratory in the University of Cambridge. To enable it with Claude, try this:

claude mcp add -t sse ocaml http://dill.caelum.ci.dev:8000/sse

Obviously this is pre-alpha quality software, and we might take it down with no notice, and it might not work as expected, and all of the other usual caveats. Let us know if it works, or doesn't, or if you've got some suggestions for improvements!

Week 33

2025-08-19T00:00:00Z

More work this week on the OCaml MCP server. Sadiq and I met before I went away on holiday and discussed the next steps to 'park' the work on the MCP server. The final steps are:

Write a README
Write and run a small script to fix a problem with module-type names
Write up and publish a blog post Not much, right? As always though, writing things up lead to a whole load more work.

The first problem occurred when writing up how it parsed the input docs. It turned out that when converting the repo so that it took markdown formatted files (using a slightly tweaked version of davesnx's PR), Claude had decided that the way to do this was to first convert the markdown into HTML, and then use the HTML parser it had already built. Whilst tidying this up, Claude was remarkably keen to just use regexps to parse the markdown rather than using a pre-existing markdown library, so it took a little persuasion to get it into a state I was happy with.

The second issue was that the script that form the bulk of the repo had been written at different times, and therefore Claude didn't really take into account any of the decisions it had made in one script when building the next. So most of the command-line arguments were slightly different, which made writing up a mini 'howto' in the README quite a jarring experience.

Thirdly, and most importantly, we had decided that we needed a few example searches to show how the system worked. We'd already had a useful experience with this when Anil had tried to search for a 'time and date parsing and formatting' library, so it shouldn't really have been a surprise that trying a few more examples showed some more interesting behaviour. Specifically, the searches I wanted to do were for an "HTTP client", "JSON parser", "Cryptographic Hash" and Anil's time-and-date query, and in actually trying these searches and critically examining the results, I had to go back and figure out why they weren't giving me the results I had expected.

The first of these searches I had anticipated would be quite interesting, as this is a query that should show the OCaml ecosystem missing an obvious HTTP client. However, even with this in mind one of the top results was one of Cohttp's module types, Cohttp.Generic.Client.S. This, of course, isn't much use if you're looking for an HTTP client, as module-types aren't going to give you an implementation to actually use. So I decided that we'd exclude module-types from the results. This turned out to be slightly more tricky than I anticipated as we'd lost the distinction between modules and module types further back in the pipeline, so Claude had to do some plumbing to ensure we had this information at the point we were doing the search.

The cryptographic hash search gave some plausible looking results, so I moved on to the JSON search. I was expecting to see Yojson somewhere near the top of the list as that's a very popular library. I was also expecting to see Jsonm somewhere near the top - or at least I'd like to be able to find it by searching for a 'streaming parser' as that's one of its key strengths. However, searching for "JSON parser" yielded some less than brilliant answers. The top 5 results were for modules in the packages yojson-five, decoders-yojson, decoders-jsonaf, ocplib-json-typed-browser and ppx_protocol_conv_jsonm. While all of these are clearly in the same realm as I was after, having jsonm show up literally 99th in the list, and yojson itself not in the top 100 wasn't a great result.

Some investigation showed that yojson had a particularly bad showing because the description of the module Yojson.Basic was the empty string! This turned out to be because of some bad error-handling logic in the summariser script, which ended up turning some errors into a blank description. Since running the summariser costs actual money, I didn't want to just rerun the whole thing, so I asked Claude for a script to find these problems and rerun them. The problem is not totally trivial as the summaries of child modules are used when generating the summary for parents, so when one is regenerated we should regenerate the summaries of all ancestors too. Given my recent experiences with Claude I'd like to look this over quite carefully before letting it loose on my data, so I've run it on yojson, which seemed to do the right thing, but not yet on the rest of the packages.

Having fixed this, I still found that jsonm was making a very poor showing. This turned out to be because the description it gives itself is a "Non-blocking streaming JSON codec for OCaml" which had a fairly low similarity with "JSON parser". I was using a fairly small embedding model for the queries - Qwen/Qwen3-Embedding-0.6B, so I thought I might address this by using a larger one, and opted for Qwen/Qwen3-Embedding-8B. The machine I had been using for the MCP server has no GPU and had taken a while to do the embeddings using the 0.6B model, so I switched to generating them on my M4 macbook. This went much faster, though since I have about 70Mb of module summaries it still took quite a while. This improved the situation somewhat, but it was still not high in the list.

So I took a step back and had a think about the problem some more. Searching for a JSON parser is really quite a high-level search, and when evaluating the results I realised I was really thinking in terms of packages rather than modules. So I thought we could split the search in two - a package search and a module search. The package search would be used for the broad queries where you're interested in pulling in whole chunks of functionality, and the module search is for more low-level queries. In fact, the 'time and dating formatting' query is somewhere in between, so I might need to have some more example queries for the module search functions. In addition, the module search could be restricted to the set of packages you're using, which might make it even more useful.

Part of the split meant that I needed a different source of 'popularity' for the packages than the occurrences data that came out of docs ci, as that was per-module and I needed something per-package. The obvious thing is to look at reverse dependencies in opam. I have this kind-of working, but it's currently not particularly smart, so this will need a little more attention. For example, it currently thinks that melange has over 3000 reverse dependencies.

With these changes in place, a package search for 'JSON parser' now returns yojson as number one, followed by ppx_deriving_yojson, ezjsonm, ocplib-json-typed and jsonaf. Unfortunately jsonm is still languishing in 27th place, so there's still some tweaking to do.

4 months in, a retrospective

2025-07-18T00:00:00Z

Astonishingly, it's already been four whole months since starting back at the university, which I find incredibly hard to believe. I'm utterly convinced that it was only a couple of weeks ago that I walked back into the Computer Laboratory as an SRA for the first time since 2021, but here we are, at the end of term already. Time to do a bit of a retrospective and forward-looking plan for the next 3-4 months!

What's happened?

On wednesday this week, I had a chance to sit down with Anil, supposedly to talk about the upcoming lecturing of 1A Foundations of Computer Science, but we ended up talking about what I've been doing for the past few months, and where it fits into the broader picture of the group as a whole. It was a really useful conversation, and I thought it would be good to outline it here while it's fresh in my mind.

So then, to start, what have I been doing? What have I achieved? What have I learnt? It's been a bit of a daunting experience, landing in a team that are already working one hundred miles an hour on things well out of my comfort zone. I've been going to group meetings and having lots of interesting conversations, but I've found it difficult to make the next steps happen. One area where I've had some success is in working with Sadiq on LLMs - in particular, getting local LLMs to solve programming exercises that we both wrote up. I've also been working with him on taking the output from the docs CI and summarising it with LLMs in order to create an MCP server that would help tools like Claude Code to choose OCaml packages to solve users' problems.

It's been somewhat easier, partly due to inertia, to carry on with projects that had been in flight at the time I started. Things like getting the Odoc 3 generated docs onto ocaml.org, which is finally complete only as of this week!. This has taken a whole lot of time, but I'm really pleased with the end results. There's still an awful lot of improvements that I'd like to see made, which, after drawing breath for a couple of weeks, I'll be writing down.

An itch I'd been wanting to scratch for a long time has been to look at client-side ocaml notebooks. I decided to make this an integral feature of this blog, and I've learnt an awful lot doing it. An important feature of this that I've been keeping in mind is the idea that we could use the ocaml-docs-ci tool to build the libraries, which would allow us to host a toplevel for every single package in opam-repository - allowing at best interactive examples, and at bare minimum merlin for live type-checking and autocompletion. The important principles to keep in mind for this are that:

We have one 'toplevel' javascript file, and libraries and cmis are dynamically loaded
The interface between the frontend and the worker must not rely on a matched pair, e.g. an OCaml-5.3-compiled frontend might be talking to an OCaml-4.08-compiled worker thread - or even an oxcaml one! I have this all working on my blog, where I have both an oxcaml worker and a standard ocaml worker and they both dynamically load in libraries and cmis as specified on the page.

I've also supervised a 1A course for the first time - Introduction to Probability, and I've done some marking for the 1A Foundations of Computer Science.

Something that I'd been expecting to do a lot on was work with oxcaml, but as the release happened later than anticipated and it coinciding with the marking and supervising, I've not done quite as much of this as I had thought I would. In addition, I had anticipated working on Odoc to start implementing the new features of oxcaml, but to avoid duplicating effort I've been waiting for the patches that have already been written at Jane Street to at least get odoc to compile, which have taken longer than I had hoped to get to me.

What's next?

With that in mind, Anil and I then talked about the bigger picture, as those of you who know Anil will be entirely unsurprised to hear! In particular, how will we be weaving the various threads of these activites - the teaching of OCaml, the large-scale (for OCaml) CI work, the LLMs and Oxcaml work together to form a coherent whole? How do I find a balance between them and ensure that we find synergies as opposed to pulling in different directions? How do make sure what we're doing helps us navigate the upending of the nature of development that agentic coding is bringing?

Efficient and reusable CI

A clear and obvious area where we'll be able to see real progress is to extract from docs CI the logic that I've been using to do efficient builds of packages. As I previously wrote about, the new CI system is far more efficient than some of the other ocurrent-based pipelines, and it would save a huge amount of compute time if we were to take this tech and apply it elsewhere.

So, how might we take what we've got and produce something useful to everyone? We need to take a hammer to the fracture points of the docs CI service and split it into individually useful parts. Here are some next steps as I see them now. Let's take the solver out of docs CI, and have a service whose sole job is to create a repository of up-to-date solutions for all versions of all packages in opam-repository. These are the data that allow us to build the tree of package builds.

Next, turn these solutions into one giant build. Perhaps a script? Maybe a giant buildkit dockerfile? This is very similar to Mark Elvers' day10 project. We can get this running on a big machine and just see how fast we can build everything. The key thing here is that it should be trivial to run this on a linux box. A raspberry pi or a 768-core behemoth with 3TiB of ram. Just how fast can we get it going? It's already building in a couple of days using sage, but that's using ocurrent/obuilder, which isn't quite the right tool for the job, and on a relatively puny machine. Can we do it in an hour? 10 minutes? Certainly the incrememntal builds ought to be done in seconds. What's the limit?

These tools can then be used as the foundation for other CI systems. For opam-repo-ci, where we should be able to do the builds for a new package incredibly quickly. For opam-health-check, where we currently build foundational packages like dune and findlib thousands of times per run.

Once we've got the packages built, docs CI is simply a pass over the top of the built artifacts. ocaml-docs-ci already demonstrates this - it only takes a few hours to rebuild all the docs when a new version of odoc is released, but in a way that only benefits docs! All the CI systems should be able to use this.

We should also then be able to run js_of_ocaml on the libraries to build to infrastructure needed for the per-package toplevels for ocaml.org that I mentioned above. Each of these steps should be separate stages in a pipeline - one where each step produces artifacts for the next to consume.

When we mix in some of the projects that other people in the team are working on, like David's work on relocatable OCaml, we've got something that might be able to form a basis for a binary cache for Dune Package Management, particularly when we involve Ryan's Hyperres paper so we might check that dependencies from outside of the OCaml universe are correct. Can we use Patrick and Michael's shark to do the build steps? Can we use these images to serve up toplevels for ocaml.org that are real toplevels rather than javascript toplevels? Can we use these build environments to do help with reinforcement learning to train LLMs on OCaml code? There are a lot of interesting directions to take this work.

Other projects

There are, of course, other responsibilities that I have. Some of these I'll be able to fit in with the theme above, and some - well - maybe I'll have to figure out how to delegate them, a skill that I am not particularly good at, but one that I feel I should learn!

Teaching

A looming, terrifying, but tremendously exciting opportunity is teaching of 1A Foundations of Computer Science. This is amongst the first courses we teach our incoming undergraduates, currently lectured by Anil. As he's on sabbatical this year, he has asked me to step up and lecture it. This is definitely not one for delegation!

The immediate question, partly raised by my work with Sadiq, is: what do we do about LLMs? How should we adjust our teaching to take into account the existence of these tools? We had a very interesting chat earlier in the term with Professor Viraj Kumar from IISc who was visiting Cambridge earlier this year. He's been working on this question for a while now, and I hope to have some more conversations with him over the summer.

Odoc paper

An area where I've really made a shockingly small amount of progress is to write up all the work that's gone into Odoc over the past 6 (!!!) years.

Odoc notebooks

This needs to be tidied up and a v0.1 released. In particular, the work on js_top_worker might well be shared with Arthur's x-ocaml for a unified toplevel experience.

AI work

I'd like to carry on the work I've started with Sadiq on the interaction of LLMs with OCaml. Getting the package search to work sensibly for an MCP server is first on the list, but also doing some reinforcement learning to improve specifically the perfomance on OCaml is very interesting, but not something I've managed to carve out the time for yet. Something along the lines of swesmith but adapted for OCaml.

Oxcaml Odoc

Odoc needs to have some work done on it to support the new work that's gone into oxcaml, for example documenting of the modes. This is something I do expect to be working on soon.

Dune and odoc

Work needs to be done on the dune rules for odoc, which currently only support the feature-set in odoc 2.x. Paul-Elliot has done some work on this, but much more needs to be done.

Further general odoc work

Better source rendering
Syntax for linking to source
Custom tags (used in odoc_notebook)
Web-native rendering, for embedding odoc in a website
Unifying paths and cpaths (https://github.com/jonludlam/odoc/tree/parameterised-paths)

What to actually do?

There are a lot of things in the above list. I'm not sure yet how I manage to figure out what I actually end up doing, and how that helps me to help Tarides, to fit in as a useful member of the EEG group, and to make sure I'm doing what's right for my own future. I feel the core project of the CI work will help everyone, but slotting the other work into the bigger picture will require some careful thought.

Odoc 3 is live on OCaml.org!

2025-07-14T00:00:00Z

As of today, Odoc 3 is now live on OCaml.org! This is a major update to odoc, and has brought a whole host of new features and improvements to the documentation pages.

Some of the highlights include:

Source code rendering
Hierarchical manual pages
Image, video and audio support
Separation of API docs by library A huge amount of work went into the Odoc 3.0 release, and I'd like to thank my colleagues at Tarides, in particular Paul-Elliot and Jules for the work they put into this.

But the odoc release happened months ago, so why is it only going live now? So, the doc tool itself is only one small part of getting the docs onto ocaml.org. Odoc works on the cmt and cmti files that are produced during the build process, and so part of the process of building docs is to build the packages, so we have to, at minimum, attempt to build all 17,000 or so distinct versions of the packages in opam-repository. The ocurrent tool ocaml-docs-ci, which I've previously written about, is responsible for these builds and in this new release has demonstrated a new approach to this task, where we attempt to do the build in as efficient a way as possible by effectively building binary packages once for each required package in a specific 'universe' of dependencies. For example, many packages require e.g. cmdliner.1.3.0 to build, and some require a specific version of OCaml too. So we'll build cmdliner.1.3.0 once against each version of OCaml required -- but only once, which is in contrast to how some of the other tools in the ocurrent suite work, e.g. opam-repo-ci. Once the packages are built, we then run the new tool odoc_driver to actually build the HTML docs. In addition to this, a new feature of Odoc 3 is to be able to link to packages that are your direct dependencies - so for example, the docs of odoc contain links to the docs of odoc_driver, even though odoc_driver depends upon odoc. This, whilst sounding easy enough, required some radical changes in the docs ci, which I promise I will write about later!

The builds and the generation of the docs is all done on a single blade server, called sage with 40 threads, 2 8TiB spinning drives and a 1.8TiB SSD cache, and it produces about 1 TiB of data over the course of a couple of days. The changes required to this part of the process since odoc 2.x were primarily myself and Mark Elvers

Once the docs are built, how do they get onto ocaml.org? Odoc itself knows nothing about the layout and styling of ocaml.org, so the HTML it produces isn't suitable to be just rendered when a user requests particular docs. What happens is that odoc produces, as well as a self-contained HTML file, a json file with the body of the page, the sidebars, the breadcrumbs and so on as structured data, one per HTML page, which are then served from sage over HTTP. When a user requests a particular docs page, the ocaml.org server will request that json file from sage, then render this with the ocaml.org styling, then send it back to the user.

As odoc 3 moved a fair bit of logic from ocaml.org into odoc itself, there were quite a few changes that needed to be made to the ocaml.org server to integrate this into the site. This work was mostly done by Paul-Elliot and myself, with a lot of help from the ocaml.org team, in particular Sabine Schmaltz and Cuihtlauac Alvarado.

So, quite a lot of integration and infrastructure work was required to get the new docs site up and running, and I'm very happy to see this particular task concluded!

Week 28

2025-07-14T00:00:00Z

OCaml MCP server

Last week I got the summarisation to the point where it felt useful to run it across all the modules in opam. With this completed we then got to try out the MCP server to see how useful it would be in practice.

One of the first queries Anil tried was to ask it which libraries would be most useful for "date time parsing and formatting". We were surprised to see that the first two libraries it returned were caqti and mariadb, specifically mentioning the module Caqti_platform.Conv and Mariadb.S.Time. While these do indeed provide the required functionality, they're probably not the right libraries to provide this. It's going to be tricky to decide this in the MCP server, so we should probably be leaving it up to the LLM to decide amongst them on the client. However, for very general queries we might end up with a large number of matching libraries, so we'll need to have a limit on the number of packages returned, which implies some form of ranking.

One way we can do this is by using the occurrences code in odoc. The idea is that we examine module implementation files (ie, ml rather than mli files), and counts the number of times the code uses values, types and other identifiers from other libraries. We can then aggregate these counts over all packages in opam repository and use it as an effective marker of popularity, which allows us to rank the results by popularity and only return the top N results.

We're not currently using the occurrences for anything, so I wasn't especially surprised to find that it's not working as intended. There were a number of issues:

The occurrences output file was being written at a path not within the package dir, so it wasn't being persisted.
The CLI interface for generating occurrences works by providing a directory containing the odocl files, but we were only providing the top-level directory and it wasn't recursively searching.
Once the occurrences were captured, the aggregation step used the full identifier of the value being aggregated, meaning that, for example, List.length in OCaml 5.3 was counted separately from List.length in OCaml 4.14. All of these issues are with code in the odoc repository, which, as it happens, also needs a release soon to ensure that it works with the imminent launch of OCaml 5.4. During the week, before I discovered the problems above, I had attempted to make a release of Odoc 3.1, but there was a license kerfuffle that, when combined with the issues in the occurrences code, gave me enough cause to pull the release.

Before I try to make the release again, this time I'll be running the release candidate with docs-ci, and checking that the occurrences make sense. I set this running on Friday afternoon, and it had completed by Friday evening, so it's actually pretty quick to rerun odoc on the 15,000 or so packages required for ocaml.org.

Trouble with this blog

In other news, in trying to post my blog at the beginning of the week, I was stymied a little by the changes in oxcaml. I had been using a custom opam-repository forked from the official oxcaml one, because I needed a patched js_of_ocaml in order to fix the toplevel code. I had hoped this would mean that I could update it on my schedule, rather than being at the mercy of upstream changes. Unfortunately though, the download URL for ocaml-flambda wasn't pointing at an immutable commit, so when I tried it I got a checksum error. So I ended up trying to rebase the changes onto the latest oxcaml opam-repository, which didn't go well at all. The version numbers had all changed, which in opam means that files are in different directories, so git got thoroughly confused. On top of that, because the js_of_ocaml repository has multiple packages in it, whereas opam repository has a directory per-package, we end up having multiple copies of the patches. So in the end I've just committed all the patches to a git repo on github, and pinned it in the Dockerfile that builds this site.

What would be handy is a way to apply the patches in a package in opam repository to and from a git repository, similar to quilt/guilt. We don't quite have all of the pieces to do this, as although we have a download URL and often a dev-repo, I don't believe we currently have a way to get the base commit of that repository.

Oxcaml continues

We had a meeting on Thursday with Jane Street on the next steps for oxcaml. There are a number of areas in which JS are keen for us to help out with.

Playgrounds - both javascript and docker-based. The playground on the oxcaml website right now uses github codespaces, which works nicely but currently takes an absolute age to start up. We can almost certainly improve this by building docker images and pushing them to the docker hub, rather than building oxcaml from scratch when starting the codespace. There's also interest in the javascript playgrounds, which can serve a slightly different purpose than the docker-based one, more limited in how it can be used, but without requiring someone to spin up a full docker container.
Documentation - Odoc has had some patches to run on oxcaml, but there's no support for documenting many of the new features yet, including modes. We've got to do some experiments here to see what the best way is to show the new type-system features in the generated docs. There were some suggestions of using javascript to show/hide the modes, for example.
Improvements in Merlin - again this is an area ripe for investigation. In particular, how do we best expose the new features of the type system for users? What's needed here is user feedback from people who are actually using oxcaml to build real projects.
Better error messages - OCaml has been getting improved error messages with each release, but there's still room for improvement, and the new features of the type system in particular have many different failure modes. Again, we need user feedback to understand the pain points and improve the error messages accordingly.

Next week

Next week, the plan is to:

Check the occurrences from docs-ci, and integrate into the MCP server
Talk to Mark about building the docker image for the oxcaml playground
Tidy up the Js_top_worker code so it can be used in the javascript oxcaml playground
Release Odoc 3.1

Weeks 24-27

2025-07-07T00:00:00Z

It's been a busy few weeks. There's been exam marking for the 1A Foundations of Computer Science course, an Odoc release to plan, and some really interesting new work on using LLMs to summarise OCaml documentation. This post is about anaspect of that last one that I found particularly interesting.

odoc-llm

Sadiq and I have been looking at using LLMs to summarise the documentation produced by Odoc. The idea is to get a concise summary of the purpose of each module, so that we can quickly identify which modules are relevant to a particular task.

For testing this, we need to see how it works on different types of libraries. The first axis I wanted to test on goes between 'well documented' and 'poorly documented', and so I need at least two libraries on opposite ends of the spectrum.

For the 'well documented' case, I chose cmdliner. It's a library that I almost always have to look at the docs for when I'm using it, as, despite using it many many times, the interface doesn't seem to stick in my head.

For the 'poorly documented' case, I chose odoc itself, somewhat ironically. In defence of the odoc authors (me included!), the libraries it provides are simply there for code organisation and aren't meant to be consumed outside of the tool itself!

The approach

The output from Odoc is a set of HTML files, one per module/module type/class/etc., containing the documentation for that item. Our first take on this was to parse the HTML files and extract the text content, which we then fed to an LLM to summarise. However, this was pretty awkward, so we decided to try a PR that davesnx recently made to Odoc to output markdown instead of HTML.

We look for leaf modules that don't contain any submodules, and start by summarising those, then move onto the parent modules, splicing in the summaries of the children, and so on, up to the top-level modules. We then move on to summarising the whole library, which usually is just a single namespace module, but occasionally is a group of top-level modules.

One of the early prompts for the module Cmdliner.Term.Syntax looked roughly as follows:

You are an expert OCaml developer. Write a 2-3 sentence description focusing on:
- The specific operations and functions this module provides
- What data types or structures it works with
- Concrete use cases (avoid generic terms like "utility functions" or "common operations")

Do NOT:
- Repeat the module name in the description
- Mention "functional programming patterns" or "code clarity"
- Use filler phrases like "provides functionality for" or "collection of functions"
- Describe how it works with other modules

Module: Syntax
Module Documentation: let operators.
( let+ ) is map.
( and* ) is product.
- val (let+) : 'a t -> ('a -> 'b) -> 'b t (* ( let+ ) is map. *)
- val (and+) : 'a t ->
  'b t ->
  ('a * 'b) t (* ( and* ) is product. *)

and the output using a small model (qwen3-30b-a3b) was:

"The module provides (let+) for applying functions to values within a context and (and+) for combining two contexts into a product. It operates on applicative
structures like option, list, or custom types that support these operations. For example, it enables sequential transformation of values in a context or
pairing elements from two separate contexts."

There are quite a few issues with the input here. Firstly, we've only given the module name, not the full path. Secondly, there's nothing to let the model know what t might be, so it has decided it's a completely generic type. It also has no idea about the context in which this module was found, so it has no idea that it's part of a command-line processing library. By fixing these issues, we end up with the prompt:

You are an expert OCaml developer. Write a 2-3 sentence description focusing on:
- The specific operations and functions this module provides
- What data types or structures it works with
- Concrete use cases (avoid generic terms like "utility functions" or "common operations")

Do NOT:
- Repeat the module name in the description
- Mention "functional programming patterns" or "code clarity"
- Use filler phrases like "provides functionality for" or "collection of functions"
- Describe how it works with other modules

Module: Cmdliner.Term.Syntax

Ancestor Module Context:
- Cmdliner: Declarative definition of command line interfaces.
Consult the tutorial, details about the supported command line syntax and examples of use.
Open the module to use it, it defines only three modules in your scope.
- Cmdliner.Term: Terms.
A term is evaluated by a program to produce a result, which can be turned into an exit status. A term made of terms referring to command line arguments implicitly defines a command line syntax.

Module Documentation: let operators.
- val (let+) : 'a Cmdliner.Term.t -> ('a -> 'b) -> 'b Cmdliner.Term.t (* ( let+ ) is map. *)
- val (and+) : 'a Cmdliner.Term.t ->
  'b Cmdliner.Term.t ->
  ('a * 'b) Cmdliner.Term.t (* ( and* ) is product. *)

The output of this improved prompt is much better:

The module provides operators to map and combine terms, which represent command line argument parsers and their results. `let+` transforms a parsed argument
into a new value, while `and+` merges two independent arguments into a tuple. These enable building structured command line interfaces, such as parsing a
filename and a flag simultaneously, then combining them into a configuration record.

It still occasionally incorrectly decides that this module provides monadic combinators rather than applicative, but this is where we get better results from using a larger model.

There are quite a few other issues that we've fixed - for example, treating module types differently than modules, and a bug where infix operators were being omitted from the documentation. In one case, it uncovered a bug in the markdown generator where includes weren't getting expanded, which I got Claude to fix. My modus operandi has essentially been to look at the output for the test packages, find a summary that looks bonkers, and then look back at the prompt to find that, indeed, the input was missing some crucial information.

One thing I'd quite like to try is to re-open a PR that Drup made as an April Fool's joke back in 2001, which ended up outputting OCaml formatted code. This is actually pretty close to what we might want to give to the LLM - though we'd probably format the comments as markdown, and we'd be replacing types with fully-qualified types as above. Funny how things turn out!

Week 23

2025-06-09T00:00:00Z

merlinonly Some brief notes on last week.

Docs CI and Sherlodoc

Anil has been working on an MCP server that searches through the output of the docs CI to find relevant packages and API information for opam packages. For expediency, this works by scraping the HTML output, but a potentially better solution would be to integrate properly with Sherlodoc, Arthur's code search engine.

Building the index

To make this work with the new docs CI, first we need to build a sherlodoc search database. This involves grabbing all of the .odocl files that odoc produces for the latest version of each library, copying them locally and running sherlodoc index on the output. Getting all of the odocl files is simple, but filtering so we only have the latest version is slightly more complex, as we need to use opam's library to make sure we're looking at the latest versions.

The simple way to get the odocl files ends up unpacking them into the filesystem in a directory hierarchy that matches the URL on ocaml.org, so we see files like:

p/odoc/3.0.0/doc/odoc.document/odoc_document.odocl

So finding the version number is a matter of listing the directories, for which I took some code from docs CI:

type p = { opam : OpamPackage.t; path : Fpath.t; }

let rec take n l = match n, l with | n, x::xs when n > 0 -> x :: take (n - 1) xs | _, _ -> []

let get_versions ~limit path = let open Rresult in let package = Fpath.basename path in let mk_pkg v = Printf.sprintf "%s.%s" package v in Bos.OS.Dir.contents path >>| (fun versions -> versions |> List.map (fun path -> { opam = Fpath.basename path |> mk_pkg |> OpamPackage.of_string; path = path }) ) |> Result.get_ok |> (fun v -> v |> List.sort (fun a b -> -OpamPackage.compare a.opam b.opam) |> take limit) This gives us a sorted list of the versions for the package, and we can pick the first one to get the latest version. With the output from this we can then run sherlodoc index and we get a nice big (1.7 gig!) index file.

Serving the index

The next step is to serve this index file so that the MCP server can access it. The file format is a marshalled OCaml value, so we need to have an OCaml program to read it in and perform the search, and it'll have to be a server since the whole index needs to be unmarshalled into memory before any search can be performed, and it would be dumb to do this for every query.

Sherlodoc got partially integrated into odoc's code base before the 3.0 release with the exception of the server, which was left out to avoid pulling a load of new dependencies to odoc. Unfortunately, we didn't expose the sherlodoc libraries publicly, so we'll need to do that in order to make anything useful with sherlodoc. In addition, odoc embeds the version of odoc used into the odocl files, and since right now the docs CI is building with a version of odoc that doesn't expose the libraries, we might have to hack around that in order to use those odocl files. Obviously the longer term solution is just to make a new release of odoc with this change and update the docs CI to use that.

Package to Library map

A related quest was to assemble a map of opam package to ocamlfind library names. It's a quirk of history that the library names that an opam package provides are not necessarily related to the name of the package. That means that tools like dune have a hard time linting projects to check that the libraries they're using are mentioned in the opam files. Dune, of course, has resolved this be ensuring that it's an error to build a package using dune where the library names don't start with the package name, but as dune is just one of many OCaml build systems, the problem remains.

Since docs CI has built every version of every package, and because the Odoc 3 package layout includes the library names in the paths to the documentation, we should be able to produce a fairly definitive list of the libraries that each package provides, which tools like dune can then use for this sort of lint check. We can just tweak the code above slightly to get the library names and output a big JSON file with the mapping - or perhaps with the exceptions to dune's rule.

I thought this would be a neat first project to try Claude Code on - a 'starter for ten' - as it were, so I signed up to use Claude code and gave it a shot.

It handily produced a working program that did exactly what I wanted, including creating a test directory that it used to verify the code worked. One fascinating thing I noted as it scrolled past was that it tried to use yojson to write the output, but failed to get it to work and reverted back to printf output. I suspect this will be due to it finding it troublesome to figure out the various steps that need to be taken to use a new library in a dune project, so this is something to have a play with later.

After a couple of iterations with different heuristics to disambiguate between library names and other directories, I got a working program producing a JSON file with only the exceptions to dune's rule. I took a look through and almost immediately found camlidl suggesting it produces a library called com. This didn't look right at all so I installed it and found that the library is actually named camlidl. The cma file, though, is named com.cma, so it looks like odoc_driver has a bug. Interestingly, running odoc_driver locally gets the library name correct, so it's only an issue when running it in the docs CI. Issue filed.

Further claude code experiments

To see how well Claude Code could handle more complex tasks, I thought I'd give it a whirl on something more like its home territory, and somewhere where I was less familiar. I decided to ask it to write some code to make a nicer editor experience for the notebooks project. Since the bindings to codemirror I'm using are very minimal, any new features I want to use end up with needing to write a bunch of bindings first, and only then seeing if the feature works as I'd like. So instead I thought I'd get claude to write the editor code for me in javascript, and then I could make sure it works as I want and only then convert it to OCaml. This worked pretty nicely, and I've now got a neat demonstration editor that I can use to guide the OCaml implementation.

More notebook work

The oxcaml project will be launching this week hopefully. I've been looking at Luke's Parallelism tutorial and have been thinking about how this will work with the online notebooks. The parallel library works via effects, and the oxcaml branch of js_of_ocaml doesn't support effects yet, and it might be a while before it does. However, the blog post is mainly talking about the intricacies of the type system work that's been done to ensure the parallel library is safe, and as such perhaps we can get a lot out of doing this online with just Merlin.

Some early experimentation showed that the parallel library breaks the worker on load, so we need to do something a bit more sophisticated than just 'not call exec', so I did some work to have a mode of worker that doesn't load the cmas, just the cmis for Merlin. This is almost there.

Odoc work

Ocaml 5.4 is just around the corner, and there's some odoc work to be done before the release. One of the main new features that will impact odoc is the new labelled tuples feature. Fortunately Luke Maurer has already done a lot of work to plumb this into odoc, so this will save us a lot of work - thanks, Luke! There's likely to be a few other bits and pieces to do, but hopefully not too much.

Progress in OCaml docs

2025-05-29T00:00:00Z

The docs build is progress well, and we've just about hit 20,000 packages (20,038 to be precise). So at this point I thought it'd be useful to take a look through the various failures to see if there are any insights to be gained.

Odoc requires a built package in order to generate the docs, there are two steps that have to be done before we can begin building the docs. Step one is to figure out the exact set of packages to build - ie, doing an opam solve, and step two is to actually build the packages. These two steps are, to some extent, out of docs-ci's control, and rely on the state of opam repository. While there are efforts to keep this in as good a state as possible, it's still the case that these steps fail much more often than the actual docs build itself. Let's take a look at some of the failures we see in each of these steps.

Step 1: opam solve

There are 2,074 solver failures. A good chunk of these are due to the way docs ci works itself, that it starts with a specific version of OCaml. In order to do this, the solution must have a specific version of OCaml in it, and this is not always the case, for example, all of the conf-* packages fail in this way. This particular class of "failures" is not at all important, as mostly they don't contain useful documentation, but even if they do, if they're actually being used then they will be built as part of another solution. For example, while conf-faad fails with this error, the solution of the faad package pulls it in anyway, so we can build any docs that it includes. Roughly two thirds (685) of the reported failures are due to this, and by checking the resulting HTML docs we can see that we do get docs for 278 of these, so they must be pulled in by other solutions.

The remaining failures are "real" in the sense that we never currently get docs for these packages. In turn, these can be subcategorised. One class of failures happen with platform-specific packages, for example camlkit which provides bindings to Cocoa frameworks, and is only available on macOS, or eio_windows which clearly requires Windows. The current docs-ci setup only builds on Linux, and extending this to other platforms will require a little more work, and is not currently scheduled. These are "fixable" failures.

The third class of failures are those that will "just never work". For example, some early versions of domainslib were released before the OCaml 5.0 APIs were finalised, and so they can only work with alpha versions of OCaml 5.0. We won't be documenting these.

Finally there are some more 'unexplained' failures, such as docteur.0.0.2. This one's particularly interesting as the solve actually succeeds when using the stand-alone tool opam-0install, whereas it's failing in docs-ci, which uses opam-0install as a library! I'm currently suspicious about the 'deprecated' flag, as the failure log contains:

- git-cohttp-unix -> (problem)
    No usable implementations:
      git-cohttp-unix.3.6.0: Availability condition not satisfied
      git-cohttp-unix.3.5.0: Availability condition not satisfied
      git-cohttp-unix.3.4.0: Availability condition not satisfied
      git-cohttp-unix.3.3.3: Availability condition not satisfied
      git-cohttp-unix.3.3.2: Availability condition not satisfied
      ...

and that flag is the only thing I can immediately see that stands out in git-cohttp-unix. In contrast, the solution given by opam-0install contains git-cohttp-unix.3.6.0 as a dependency. I suspect fixing this will cause quite a few more packages to succeed.

Step 2: building packages

The next step, once we've got the solutions, is to build the packages. This is using the new method I previously wrote about. There are about 1,000 packages that fail to build, and once again we can take a look and categorise some of these failures. There are a wider variety of failures here, and it's quite useful to cross-check with opam health check to see if it's known to be broken. Unfortunately OHC only builds the latest versions of everything, so we can't check in some cases. The interesting issues are where we're failing to build something that seems to work in OHC.

llvm.18

This is an interesting type of error, where the build fails because of a missing external dependency. The llvm package depends upon conf-llvm-static.18, which should be able to install the depext. Looking at the package, it does indeed have a depext for Debian:

depexts: [
  ["llvm@18" "zstd"] {os-distribution = "homebrew" & os = "macos"}
  ["llvm-18"] {os-distribution = "macports" & os = "macos"}
  ["llvm-18-dev" "zlib1g-dev" "libzstd-dev"] {os-family = "debian"}
  ["llvm18-dev"] {os-distribution = "alpine"}
  ["llvm18"] {os-family = "arch"}
  ["llvm18-devel"] {os-family = "suse" | os-family = "opensuse"}
  ["llvm18-devel"] {os-distribution = "fedora" & os-version >= "41"}
  ["llvm-devel"] {os-distribution = "fedora" & os-version = "40"}
  ["llvm18-devel" "epel-release"] {os-distribution = "centos"}
  ["devel/llvm18"] {os = "freebsd"}
]

However, in Debian 12, they've already updated to llvm-19, so the depext is not available.

camlimages.5.0.5

This one fails due to a linking error. Oddly enough it does seem to work in OHC.

(cd _build/default && /home/opam/.opam/4.14/bin/ocamlmklib.opt -g -o freetype/camlimages_freetype_stubs freetype/ftintf.o -ldopt -lfreetype)
# /usr/bin/ld: freetype/ftintf.o: warning: relocation against `Caml_state' in read-only section `.text'
# /usr/bin/ld: freetype/ftintf.o: relocation R_X86_64_PC32 against undefined symbol `Caml_state' can not be used when making a shared object; recompile with -fPIC
# /usr/bin/ld: final link failed: bad value

ahrocksdb.0.2.2

This one fails in OHC too, but it looks like it's a build failure with more recent gccs, fixed upstream: https://github.com/ahrefs/ocaml-ahrocksdb/commit/e52316b3d30fededac023141bf8b47da79cabfed

# run: gcc -O2 -fno-strict-aliasing -fwrapv -fPIC -pthread  -I/usr/include/rocksdb -I /home/opam/.opam/5.3/lib/ocaml -o /tmp/build_02b340_dune/ocaml-configuratordc5e55/c-test-2/test.exe /tmp/build_02b340_dune/ocaml-configuratordc5e55/c-test-2/test.c -lm -lpthread -lrocksdb
# -> process exited with code 1
# -> stdout:
# -> stderr:
#  | In file included from /tmp/build_02b340_dune/ocaml-configuratordc5e55/c-test-2/test.c:4:
#  | /usr/include/rocksdb/version.h:7:10: fatal error: string: No such file or directory
#  |     7 | #include <string>
#  |       |          ^~~~~~~~
#  | compilation terminated.
# Error: discover error

alt-ergo.2.2.0

Looks like it's trying to write outside the sandbox. The failure only occurs on alt-ergo 1.3.0 - 2.2.0.

# mkdir -p /home/opam/.opam/4.14/man/man1
# cp -f doc/alt-ergo.1 /home/opam/.opam/4.14/man/man1
# mkdir -p /usr/local/lib/alt-ergo/preludes
# mkdir: cannot create directory '/usr/local/lib/alt-ergo': Permission denied
# make: *** [Makefile.users:243: install-preludes] Error 1

ctypes-foreign.0.18.0

This one is a much more interesting failure. The logs show:

[ERROR] No solution for ctypes-foreign.0.18.0:   * Missing dependency:
            - ctypes-foreign -> ctypes
            unknown package

which is happening because of the optimisation I mentioned before where we build a new opam-repository with only the packages we're going to need. In this case, we've somehow missed out the ctypes package. Looking at the opam file for ctypes-foreign, it has a post dependency on ctypes. The post keyword indicates that ctypes should be installed with ctypes-foreign, but that having it as a "normal" dependency would introduce a dependency cycle. Since we require a DAG of dependencies, we explicitly remove any post dependencies from the set of packages to build, but it seems that opam would like to know about it anyway!

others

There are many more. An automatic cross-check with OHC would be really useful, mainly to distinguish between the packages that are broken due to ocaml-docs-ci issues (like ctypes-foreign) and those that are broken for other reasons (like ahrocksdb).

Step 3: building docs

Finally, we have the actual docs build. This is where we run odoc and odoc_driver to produce the HTML docs. All the errors here are ones that we should be able to fix!

Firstly, there are the internal errors:

Uncaught exception: Failure("\"rm\" \"-rf\" \"/var/cache/obuilder/merged/582e973685d380d4c91eadc2611eee02c82c5fe4f8bd732e0080fb22bc4404cd\" \"/var/cache/obuilder/work/582e973685d380d4c91eadc2611eee02c82c5fe4f8bd732e0080fb22bc4404cd\" failed with exit status 1")
2025-05-22 09:30.18: Job failed: Failed: Internal error

These are some obuilder error that needs fixing. Currently we're just rerunning the job to fix these.

odoc.2.0.0

Oops, we can't build our own docs! At least it's an old version :-)

odoc: internal error, uncaught exception:
      File "src/html/link.ml", line 101, characters 16-22: Assertion failed
      Raised at Odoc_html__Link.href in file "src/html/link.ml", line 101, characters 16-57
      Called from Odoc_html__Generator.internallink in file "src/html/generator.ml", line 108, characters 19-49
...

The failure points here, an assertion about the common ancestor of two paths. Issue filed.

ocaml-base-compiler.4.07.0

This one happens because of our "optimisation" to use a base image with OCaml pre-installed. What we actually do is find the major/minor version of OCaml and use the corresponding docker image - so in this case we'll use ocaml/opam:debian-12-ocaml-4.07. Now this image actually contains OCaml 4.07.1, and the format of cmt and cmti files changed between these releases, so we get a failure.

We'll fix this by getting rid of the optimisation and building from an empty switch.

lascar.0.7.0

This one is quite interesting. It's another assertion failure in odoc:

odoc: internal error, uncaught exception:
      File "src/xref2/cpath.ml", line 364, characters 37-43: Assertion failed
      Raised at Odoc_xref2__Cpath.unresolve_resolved_parent_path in file "src/xref2/cpath.ml", line 364, characters 37-49
      Called from Odoc_xref2__Cpath.unresolve_module_path in file "src/xref2/cpath.ml", line 349, characters 28-60
      Called from Odoc_xref2__Tools.fragmap.map_module_decl in file "src/xref2/tools.ml", line 1792, characters 48-80

It's happening when we 'unresolve' a previously resolved path. We end up having to do this when something about the path has changed, in this case while we're handling a S with module Foo = Bar or similar. Issue filed.

camlp5

This one actually occurs in odoc_driver rather than in odoc itself.

odoc_driver_voodoo: [DEBUG] Found cmi_only_lib in dir: /home/opam/.opam/4.08/lib/camlp5
odoc_driver_voodoo: internal error, uncaught exception:
                    Invalid_argument("\"/home/opam/.opam/4.08/lib/camlp5\": invalid segment")

Here we're trying to add a segment to a path, but rather than a single path segment we've got an entire fully qualified path. Issue filed.

Conclusion

It's pretty good that we've only got 4 types of error happening at the doc-generation phase. However, as a whole, any error that occurs earlier in the pipeline ends up with a missing documentation tab on the website, and we need to do a bit more so that the actual problem can be tracked down and fixed. This is obviously a more general problem than just the docs, and one that opam health check seeks to highlight. However, the current incarnation of OHC is significantly less efficient than docs-ci, so generalising the approach we've taken with opamh should really help with making this more responsive.

In addition, a number of the issues seen here could be addressed with a tool my colleague Ryan is working on: Enki. This tool would allow us to run a solve that actually determines not only the set of packages we wish to install, but the platform to install onto - e.g. for eio_windows the solution would be to install on Windows, and for llvm.18-static the solution might be Fedora 40.

Lots of things have been happening

2025-05-20T00:00:00Z

I've been working on a whole lot of thing recently in many different areas, making what's felt like only a bit of progress in each. Consequently I've not felt like I had anything substantial to say, so I haven't written up anything for a while.

Time for a little summary of things then!

Ocaml-docs-ci

I've been working with Mark Elvers on getting the docs CI running using Odoc 3.0. There are quite a few changes involved, both in how we're building the packages but also how we're running odoc - it's building using odoc_driver rather than voodoo now, and while it's looking promising now we had hit a few hurdles along the way.

We set the CI going last weekend but discovered that it was having some issues building packages using OCaml 5.3.0. The way the builds work is that we first do a "solve" step for each version of every package so we've got exact versions of all of the packages required to build them. We then look through that solution to figure out the version of OCaml required, and the (to avoid a little bit of work) we start from one of the opam docker images for that version of OCaml.

When installing a package using opam it does a few operations that scale with the size of the opam repository, which ends up adding around ten of seconds to the build time. When we're building 50,000 packages, this adds up to quite a lot of time, so we short-cut this process with the simple expedient of creating an opam-repository that only contains the packages we need for the build. However, since we've already got a few packages installed in the image, we need to make sure our repository contains these packages too, otherwise opam gets thoroughly confused. My mistake was that we were missing out the `ocaml-compiler` package, which is new in OCaml 5.3.0, which led to the builds failing. Adding this in and kicking off the build again it's now got a lot further - at time of writing it has built 14,000 packages, there are 6,000 still building, and 1000 that have failed. If it continues in a similar fashion, this will compare quite favourably with the docs CI that's currently powering ocaml.org, where it has successfully built 17,000 packages, and 4,500 have failed.

Mark has been working on a different approach to the build process, which is to come up with a new binary that doesn't do any of the O(n) operations and just builds the package! This is definitely a promising direction, and I'm hoping to take a look at his prototype soon.

Meanwhile, panglesd is working on integrating this into the ocaml.org site, and is making good progress. He spotted last week that we were overwriting the `status.json` file that comes out of `odoc_driver` which we will use to power the redirections on ocaml.org. One of the changes of odoc 3.0 is that we carefully put modules into a directory structure that represents the library in which they are found. It's long been a pain that OCaml libraries (what Ocamlfind unhelpfully calls 'packages') are not always the same name as the opam package in which they're found. For example, the package ocamlfind contains the library findlib. So to help the user figure out where to find the module, we're putting it into the URL of the docs, and therefore into the breadcrumbs. The downside is that the modules are now in a different place on the website to where they were before, so the status.json file is there to help with the redirections.

Notebooks

I've been working on Merlin integration with the notebooks, which has been a fun little project. The bits that needed improving most were that merlin didn't work with toplevel-style code, and that each cell was a separate typing context, so while you could define a function in one cell and execute it in another, Merlin would tell you the function was undefined.

For the toplevel-style code, what I've ended up doing is to essentially strip out all of the toplevel bits and pieces, and replace them with whitespace. So where I have a cell that looks like:

# let x = 1 + 2;;
  - val x : int = 3
# let y = x + 1;;
  - val y : int = 4

I tell Merlin that the contents are:

  let x = 1 + 2;;

  let y = x + 1;;

where I'm careful to maintain the position of the original code. This bit is working quite nicely, but only when the code is syntactically correct, as I'm using the standard toplevel parser to figure out where the expression ends. I think I'm going to end up needing to write a custom parser for this, so something that will end on a ;; but ignore them in string constants, comments and so on.

The approach I've taken for the second problem is to treat each cell as a separate module. I then write out a cmi file into the virtual filesystem as cell__id_0.cmi and open all the previous modules in 'line 0' of every cell. I then remap all of the reported locations by removing 'line 0'.

There are a number of issues with the current approaches: 1. The stripping of the toplevel bits is a little fragile, and currently only works when the toplevel is syntactically correct. This is fairly fixable. 2. When the contents of the cells change we need to flush any caches merlin and the compiler have. 3. An open statement in once cell does _not_ cause the module to be available in the next cell. 4. A lot of cells leads to a lot of opens!

I suspect that this the 'cells as modules' approach might end up being a bit of a dead-end, so I'll have a chat with Ulysse to figure out the next experiment.

Oxcaml

I've been working on trying out oxcaml too, which has been a bit challenging. Firstly, although Jane Street provide a version of js_of_ocaml, the toplevel didn't work. Fortunately, my amazing colleagues Patrick O'Ferris and Arthur Wendling spent a good chunk of time fixing this and provided an opam repository with the relevant changes, without which I would have not been able to make any progress. Thanks, guys! So my goal of making my notebooks work with it looked doable, but I almost immediately hit more dependency issues that make it problematic to port the whole site over - including odoc and various PPXes that I use.

I've therefore decided that I would bring forward a feature that I'd had in mind for a while - that we could have different "backends" for the notebooks. So I'd still build the frontend using "normal" OCaml, but the web-worker serving as the toplevel would be an oxcaml one.

Of course, it didn't work first time! After a bit of head-scratching, it turned out that the interface between the worker and the main thread, although I'd almost got it ocaml-agnostic, wasn't quite right. The way it works is that it uses the jsonrpc protocol to communicate, and while it had marshalled the requests into a string, it hadn't turned that final OCaml string into a Javascript string, so it was sending the js_of_ocaml representation of a string as an object, rather than a simple string. When the frontend and workers were built with different compilers, this ended up just failing with an obscure error, which took a good deal of time to track down. Once that was fixed, it was just a case of making sure I could have 2 independent 'switches' on my site - one for oxcaml and one for standard OCaml.

The upshot of all this is that I now have a semi-working version of the notebooks using oxcaml. As an initial demonstration I ported one of my colleague Cuihtlauac's oxcaml tutorial docs to the notebook format, and it works quite nicely.

Solving First-year OCaml exercises with AI

2025-05-07T00:00:00Z

My colleague Sadiq Jaffer and I have been working on a little project to see how well small AI models can solve the OCaml exercises we give to our first-year students at the University of Cambridge. Sadiq has done an excellent write up of our initial results, which you should all go and read! The tl;dr though, as Sadiq writes, is that even some of the smaller models would score top marks on these exercises!

One interesting aspect we discovered quite quickly is that we had to make the testing feedback a little more generous than just "exception raised"! The problems are presented as a Jupyter notebook using akabe's excellent OCaml kernel, with nbgrader to do the assessment. Our students can see the tests that are run, and if they fail they're able to copy the test cell out and play with their code to figure out exactly what went wrong. The AI models, however, have a far less interactive experience, and get just 3 chances to write code that passes the tests. We found that the performance of the models increased hugely when we adjusted the test cells such that they clearly indicated which test failed, the results that were expected, and the results the code actually produced.

Of course, we already knew that AI models can code OCaml very well, and we (along with the rest of the teaching world) are still ruminating on the implications of this from a pedagogical perspective. Our plan, though, is to try and make the 'problem' worse by training these models on more OCaml code, and see just how well we can get them to perform! It's pretty amazing, and a little startling to know that a model that'll run pretty comfortably on my laptop can solve these problems so well even without extra training, though given how hot it gets, I'd rather not have the laptop on my actual lap while it's doing so!

OxCaml is getting closer...

2025-05-02T00:00:00Z

I joined the OxCaml weekly meeting representing Tarides for the first time this week, as Jane Street gear up to an official release of their OxCaml compiler.

It seems that mainly what needs to be done before the release can be made is to ensure there is some reasonable documentation for the new features, and that a reasonable number of packages are working, so people are furiously writing and bugfixing to try and get this ready.

As well as this though, there are some challenges of a more organisational level that will need to be addressed to ensure the success of the project. Jane Street have long had a public branch of their compiler, but while they've had patches internally to ensure the tooling and other libraries work, these patches haven't previously been made public in a usable way. In order for OxCaml to be useful, it will clearly need these patches not only to be available, but also to be maintained and to easily allow contributions from the community -- in short, they need to be properly Open Source!

Personally, I'm looking forward to seeing their branch of odoc and having a look to see how the modes will fit into the documentation. I'm also keen to see whether the notebook features I've been working on can be ported over to run on OxCaml!

AI for Climate & Nature Community Day

2025-05-01T00:00:00Z

Melissa Leach introducing the day Today was the "AI for Climate & Nature Community Day" at the David Attenborough Building. A whole bunch of the EEG were either presenting or contributing in some way so I thought I'd come along to see what's going on.

Keynote and main talks

Following the intro talks from Professors Melissa Leach and Bill Sutherland, the day started with the keynote talk from Amy Hinsley, who, using the specific case of animial trafficking, talked about the need to make AI in conservation equitable, explainable and useful.

Amy Hinsley delivering the keynote talk

We then moved into the first session with Emily Lines from the Geography Department who talked about the challenges processing sensor data in the context of forests. Her group has a variety of data collected from forests across Europe, collected from using many different methods, from drones taking pictures of the canopies to ground-based laser scanners producing 3d point clouds. The challenge is then not only to identify individual trees, which is pretty tricky, but also to then distinguish between the leaves of the trees and the wood.

After Emily came Robert Rouse from the ICCS, who's using a small neural net and genetic algorithms to extend a study from the RSPB on figuring out an optimal way to do some land use adjustments to cut carbon and improve outcomes for birds, whilst not significantly impacting the ability to produce food.

We then had Sam Reynolds and Sadiq Jaffer who talked about their project; using AI to sift through millions of papers looking for those relevant to a specified conservation topic. They're able to directly compare their results with results obtained by manually doing this process, a project that's been going on over the last 20 or so years summing to something like 75 man years of effort. In the end they only missed a few papers that the manual process had found, but actually found many relevant papers that had been missed - and all in only a few days of compute.

Sam Reynolds and Sadiq Jaffer sorting millions of papers

Lightning talks

We then had a number of 'lightning talks', with each presenter having only three minutes to talk about their work.

Sebastian Schemm presented his work on creating a foundational model for the climate
Alice Cicirello talked about the prospects of applying machine learning to Marine Cloud Brightening
Simon Thomas has been looking at analysing the heights of tropical cyclone storm surges
Niccolò Zanotti gave us an introduction to FTorch, a library to integrate the worlds of PyTorch and Fortran
Simon Driscoll then talked about melt ponds on arctic sea ice, a poorly understood but important component of the climate in the Arctic.
Emilio Luz-Ricca talked about his project to apply machine learning to predict hunting pressure
Orlando Timmerman gave us some insights into how he's been using machine learning to predict the future of coral reefs, and how we might use this to help with their conservation.
Ruari Marshall-Hawkes showed us how to listen very carefully to figure out population numbers,
Hattie Branson from Fauna & Flora talked about habitat detection in South Sudan,
Marta Koch showed us an analysis of how well ChatGPT, Claude and the like would perform at setting the agendas for SDPs,
Frank Feng finished the session with a talk on the Barlow Twins Earth Foundation Model.

Sebastian Schemm

Alice Cicirello

Simon Thomas

Simon Driscoll

Emilio Luz-Ricca

Orlando Timmerman

Ruari Marshall-Hawkes

Hattie Branson

Frank Feng

Discussions

We then split up into three discussion groups; one on the future of this work, one on how to continue building this community of researchers, and the last on applying AI to real-world problems. As a newcomer to the field I was interested in the direction it's heading in, so I joined in Dominic Orchard's led session on the future of AI.

We had a fascinating discussion on both the immediate things we can do and longer term worries. We were imagining a world where AI becomes 'just a tool' that we don't need to be experts in to apply it, but right now we're in a much more tightly coupled collaborative world where we need experts in AI to complement the experts in the application field to make progress. This comes with challenges - applying for funding for multidisciplinary work is not the norm, so we spent some time discussing this too.

One of our group spoke about statistics now being 'just a tool', but it's been one that we've worked with for a long time now and we know where the sharp corners are. We have protocols for applying statistical tools and we have diagnostic plots to tell us whether the results are trustworthy, but not only do we not have these for AI models, but it's not yet clear whether such a thing will be even possible.

Overall it was a fascinating day, and I'm very much looking forward to following the work of these outstanding researchers, and maybe even contributing to their work in some way in the future.

Thanks to Anil Madhavapeddy for the photos of the day.

OCaml-Docs-CI and Odoc 3

2025-04-29T00:00:00Z

The release of Odoc 3 means that we need to update the docs-ci project so that the documentation that appears on ocaml.org is using the latest, greatest Odoc. With this major release of Odoc, it's also time to give the CI pipeline a bit of an overhaul too, and fix some of the irritations that it causes.

The challenge of documenting OCaml

As I wrote about recently, the APIs of OCaml libraries are dependent not only on the version of its package, but possibly also on the versions of any of its dependencies. Due to this fact, to produce the docs for ocaml.org means that sometimes we need to build the docs for a particular version of a particular package multiple times with different versions of its dependencies.

It's clearly impractical to try to build every possible combination, so what we do is to run the opam solver once for each version of each package. This gives us a set of packages at particular versions. We then take that, and for each package in the set, we pluck out its dependencies from the set, producing a "universe" of dependencies for every package in the set. Let's look at a very simple example; the package cry from the LiquidSoap project.

The oldest version of cry from before the Great Purge was 0.2.2, which when solved produced the following dependencies:

cry.0.2.2
ocaml.4.05.0
ocaml-base-compiler.4.05.0
ocaml-config.1
ocamlfind.1.9.6

and the oldest version of cry after the purge is 0.6.0 which produces the following solution:

cry.0.6.0
ocaml.5.2.1
ocaml-base-compiler.5.2.1
ocaml-config.3
ocamlfind.1.9.6

so we we can see from these two solutions that we'll need to build ocamlfind.1.9.6 twice, once with ocaml.4.05.0 and once with ocaml.5.2.1.

Once we've got, for every version of every package, a set of dependency universes, we choose one of these to be the one presented to the user under the ocaml.org/p/ hierarchy. For all of the other universes, we build the package againt them, and put the docs under the ocaml.org/u/ hierarchy.

Performing the builds

Once we've got a complete set of solutions and builds to do, the current CI pipeline batches the builds up to try and build as many packages as possible in as few builds as possible. While this works well enough, it does mean that we build a lot packages more than once - dune, for example, is built thousands of times during this process, producing exactly the same binaries each time.

In the new pipeline, I wrote a little tool that allows opam packages to be archived and restored, which happens to work nicely because we're always building the packages in the same container in the same location. This means there are no worries about relocatability, although that is something that is nearly here!

The downside to this is that our storage requirements are quite a bit larger, as we're storing the entire package rather than just the bits that odoc needs. However, we were always going to use more storage than before simply because the new odoc and odoc_driver pair are more capable, and the new features like source code rendering and classify require more files from the original package.

The upshot is that I'll be working with Mark Elvers to move the docs CI from its current machine to a shiny new blade server.

Odoc 3: So what?

2025-04-25T00:00:00Z

Odoc 3 was released last month and although we did write a list of the new features, I don't think we've made it clear enough why anyone should care.

It's manuals, the theme of Odoc 3 is manuals. It's got a load of features to make it much better for writing mld pages (files written using odoc's markup) to document your packages and their relationship to the surrounding ecosystem. Previous versions of Odoc were very library-centric, in that while we did have mld-file support, most of the effort went into making sure that we were generating correct per-module pages, which show the shape of your API even if you've not put in any doc comments at all. We've still got that, obviously, but we've added many features to make write mld pages far more useful, and we're really hoping that these will draw people in to make documenting packages a much more enjoyable experience.

Odoc's special skill: links!

But why you might want to use Odoc at all for your package's manuals, rather than, say, markdown, asciidoc, rst or any other similar language? The biggest thing that Odoc brings, and has always brought, is reliable linking. Just write {!Module.func} and Odoc will check that the target exists and ensure that the link goes to the correct place, no matter how complex the definition of Module is or what the layout of the docs. We can link to almost all elements of an OCaml library, from modules and types through to fields of records, exceptions and extensions, and we have facilities for disambiguating, so if you happen to have both a module S and a module type S you can easily link to whichever you please.

In Odoc 2 though, these links were pretty limited - the only ones possible were only those to docs and API elements (modules, types, values, etc) in your own package, or to API elements in any libraries that your package depends on. When writing API docs, which tend to be at the level of types and functions, this wasn't a huge problem, but when considering manuals this turned out to be a really limiting constraint. For example, in Odoc's own docs, we really want to have a link to odoc-driver, but since odoc-driver is a separate package and depends upon odoc, the only way to do that in Odoc 2.x would be to use an HTML link. With Odoc 3, this constraint is gone, so you can link to any other package or library. The link to odoc-driver would look like {!/odoc-driver/page-index}, as can be seen in odoc's source. The only requirement is that you must be able to simultaneously install all of the packages you'd like to link to, so you can't easily link to, for example, different versions of the same package.

This will be particularly useful for any projects that's grouped into multiple packages. For example, the Mirage project. The main package there -- mirage -- is actually right at the bottom of the dependency hierarchy, but it's the perfect place to have docs that link to all of the other Mirage packages. On a smaller scale, the Picos project consists of multiple packages all from a single git repository, and this would allow the docs pages from the picos package to link to any of the other packages.

Of course there are also a lot of other new features in this release, which are called out in the annoucement post on discuss, some of which I may post about in the future.

Can I use it now?

Of course! These new features can be used right now, so long as you're happy to self-host the docs. All that's needed is to create a switch containing all the packages you're interested in together, and use odoc_driver to generate the HTML and push them to your web server. At time of writing though, ocaml.org is still using Odoc 2.4, so any packages that are published to opam that choose to use these new features will be missing the new features. Furthermore, it's actually quite a challenge to do this, since we'll have to extend the package-universe solutions to include all relevant packages, for which we need extra fields in the opam metadata.

What's next?

We're actively working on getting Odoc 3 into the pipeline generating the docs found in https://ocaml.org/p/. This will bring with it some of the developments that landed in Odoc 2, but didn't make it onto ocaml.org - for example, the rendering of source pages. Not only are there challenges related to the package-universe solutions as mentioned above, but the storage requirements are considerably larger, so I'll be working with Mark Elvers to complete this project.

We've also got work to do to update the build rules in dune to take advantage of these features. While odoc_driver works very well as part of the process of deploying a docs site, it's quite impractical as a tool to help while you're actually writing the docs. For that, we'll need to make sure dune understands how to use these new features. Fortunately we've had some experience with those rules in the past, and part of the work that's gone into Odoc 3 was to ensure that incremental build rules should be far more straightforward to write than for Odoc 2. In addition, some of the logic that previously only existed in Voodoo - the old driver that builds docs for ocaml.org - has been integrated into odoc itself, meaning one again that getting dune to produce correct docs for non-dune packages (e.g. the standard library!) should again be simpler.

After we've done these, there are plans afoot to make more improvements to the manual writing experience. @panglesd has been investigating how to add admonitions to the language, I've been thinking about custom tag support, we're looking at the modes work coming from Jane Street to see how to support that. There's plenty more to do, so if you'd like to lend a hand, reach out and join in!

Semantic Versioning in OCaml is Hard

2025-04-20T00:00:00Z

Semantic versioning is a lovely and simple idea that, if it were reliably implemented everywhere, would make life a lot simpler. So, is it possible to make our OCaml libraries stick to this scheme? There are some projects that are trying to do this, including a recent Outreachy project by Abdulaziz Alkurd mentored by panglesd and Nathan Reb. While this is a great start, there are some subtleties of the OCaml module system that make it a good deal more complex than in other languages.

opam-format.2.3.0 ≠ opam-format.2.3.0?

Let's take the case that hit me this morning. I've been working on ocaml-docs-ci in order to bring the exciting new odoc 3 features to ocaml.org for everyone to enjoy. I have it checked out and building locally, but to deploy it to the infrastructure managed by Mark Elvers it needs to be packaged up into a Docker image. So I issued the usual docker build . and after it churned through the setup stages and got on to building the project, it hit an error:

File "src/solver/solver.ml", line 58, characters 75-98:
     let deps = List.map (fun pkg -> OpamPackage.Map.find pkg simple_deps) (OpamPackage.Set.to_list pkgs) in
Error: Unbound value OpamPackage.Set.to_list
Hint: Did you mean of_list?

Now OpamPackage is a module in the opam-format library, which is easily discovered using the excellent Sherlodoc tool, so I checked what version I had locally, and what version I had in the Docker container, and it turned out I was using exactly the same version -- 2.3.0 -- both locally and in the container. So what's going on?

The problem is that the Dockerfile I was using was using OCaml version 4.14, whereas locally I was using OCaml 5.3. "But how on earth can this cause the API of opam-format to change?" I hear you wail! Well, this is actually one of the simpler outcomes of the way the OCaml module system works. Let's look at the code.

The first thing we note is the absence of any definition of Set or Map here

where do they come from? It turns out they come from this line here:

include OpamStd.ABSTRACT with type t := t

So let's take a look over in opamStd.mli to see what that signature looks like:

(** A signature for handling abstract keys and collections thereof *)
module type ABSTRACT = sig

  type t

  val compare: t -> t -> int
  val equal: t -> t -> bool
  val of_string: string -> t
  val to_string: t -> string
  val to_json: t OpamJson.encoder
  val of_json: t OpamJson.decoder

  module Set: SET with type elt = t
  module Map: MAP with type key = t
end

OK, so we've found the definitions of Set and Map - they refer to signatures SET and MAP which are defined just above in opamStd.mli. Let's just look at Set since that's where the problem was:

module type SET = sig

  include Set.S

  val map: (elt -> elt) -> t -> t

  val is_singleton: t -> bool

  (** Returns one element, assuming the set is a singleton. Raises [Not_found]
      on an empty set, [Failure] on a non-singleton. *)
  val choose_one : t -> elt

  val choose_opt: t -> elt option

  val of_list: elt list -> t
  val to_list_map: (elt -> 'b) -> t -> 'b list
  val to_string: t -> string
  val to_json: t OpamJson.encoder
  val of_json: t OpamJson.decoder
  val find: (elt -> bool) -> t -> elt
  val find_opt: (elt -> bool) -> t -> elt option

  (** Raises Failure in case the element is already present *)
  val safe_add: elt -> t -> t

  (** Accumulates the resulting sets of a function of elements until a fixpoint
      is reached *)
  val fixpoint: (elt -> t) -> t -> t

  (** [map_reduce f op t] applies [f] to every element of [t] and combines the
      results using associative operator [op]. Raises [Invalid_argument] on an
      empty set, or returns [default] if it is defined. *)
  val map_reduce: ?default:'a -> (elt -> 'a) -> ('a -> 'a -> 'a) -> t -> 'a

  module Op : sig
    val (++): t -> t -> t (** Infix set union *)

    val (--): t -> t -> t (** Infix set difference *)

    val (%%): t -> t -> t (** Infix set intersection *)
  end

end

Sure enough, there's no to_list function defined in there. Once again though, there's an include Set.S in there. It turns out that that refers to the Set module in the OCaml standard library. We can again look at the source:

val to_list : t -> elt list
    (** [to_list s] is {!elements}[ s].
        @since 5.1 *)

And there it is. The to_list function has only been in the Set module since version 5.1.

Using ocaml.org docs

It was pretty difficult to figure that out from the source, but happily there's a better way. We can browse the docs on https://ocaml.org/ - We can look at the docs for the OpamPackage.Set module which, as of today, does not contain any to_list function. The include Set.S is there with the expansion showing all of the types and values coming from it, so we can click on the Set.S link on the include line which takes us to the documentation for the stdlib from OCaml 4.11.2. Changing the version from the dropdown at the top to something more recent takes us to a page containing the to_list function with the helpful since 5.1 annotation.

This is, in fact, a relatively simple example of the sorts of issues that can occur that make semantic versioning a headache. In this example, it was a change due to a difference in the compiler version used, but there's nothing particularly special about that - a package may expose signatures derived from any of its dependencies! So is there anything we can do about this? Obviously, yes!

Towards a solution

Step 1 of any approach to solving this is to be able to identify which bits of a libraries API come from which packages, and therefore which versions of those packages. It turns out there may well be a nice way to piggy-back on a recent feature from Odoc, which was originally intended to help with suppressing suprious warnings.

The problem we were tackling was that if your library ends up exporting a module whose signature is defined in someone else's package, then any warnings that come from it are unfixable. To fix this we added a tag to each signature of a module that indicates which package it originally came from. Odoc is then very careful to keep track of this as it performs its signature manipulations, resulting in an accurate way to know which signature elements came from which package. This fixed the problem of the spurious warnings nicely.

Quite separately, we've got the docs CI that is attempting to build docs for every version of every package. Obviously given the above, in order to exhaustively show all the possible APIs of every library, we should build all possible combinations of every version of every package. Clearly we can't possibly do this, so the docs CI focuses on the goal of building at least one solution for every version of every package.

Now if you combine these two ideas, we can use the builds of the packages with the tracking of the package of the originating signatures to be able to precisely track the differences in API between different versions of a package. This would allow us to build a database of those changes, and with this in hand we can look at what APIs are used in any other package and be able to suggest upper and lower bounds on the versions of its dependencies.

Now wouldn't that be cool?

Meeting the Team

2025-04-08T00:00:00Z

It's tremendously exciting to be back in the Computer Laboratory, as the last time I worked here was just before the pandemic. I'm now a member of the Energy and Environment Group whose goal is "to have a measurable impact on tools and techniques for de-risking the future".

What's going on?

With such a broad goal, it's hard to know where to start and how I'll fit in, so my first few weeks have been spent getting to know the other members of the group and what they're up to. It's an incredibly inspiring group of individuals who are all doing amazing work, and it's really humbling and daunting to be a part of it.

There's some really interesting work going on in our group on LLMs, principally led by the fantastic Sadiq Jaffer. We had a chat a few weeks ago and have started to explore some ideas around seeing how well LLMs can program in OCaml already before we start to do some RL training on them. Having not done any LLM stuff before, it's a steep learning curve for me, but we're already seeing some interesting results. We should have some more to say about this in the coming weeks.

Last week I met with Michael Dales, and he talked about the project shark that he and Patrick Ferris have been working on. It's kind of a mix between a shell and a jupyter-style notebook, with a strong focus on reproducibility. The traditional pain of notebooks is, of course, the execution model, whereby cells might be executed in any order you like. This means that the state you find the notebook in might not be even reachable again, let alone consistently reproducible. Shark is trying to address this by using file-system snapshots and clever analysis of the inputs and outputs of each cell to both ensure reproducibility, but also to allow a fast editing cycle, rerunning of only the bits that need to be rerun, even in the presence of slow data processing steps. It's a fascinating project, and I can't wait to see it in action when Michael gives us a demo!

I also met up with Ryan Gibb with David Allsopp and we had a good chat about his project Babel, which is using the PubGrub algorithm to do package resolution for multiple package domains at once. We've got a number of avenues to explore here, from building a PubGrub implementation in OxCaml, to using Babel to construct Docker images for opam packages entirely from scratch, without using a base image.

With my other hat on as a member of the CTO office at Tarides, I'm very much looking forward to using OCaml and OxCaml to solve some real-world problems that are in an entirely different domain than I've been used to over the last few years.

This site

2025-04-07T00:00:00Z

I've spent a lot of time over the past few years working on Odoc, the OCaml documentation generator, so when it came time to (re)start my own website and blog, I found it hard to resist thinking about how I might use odoc as part of it. We've spent a lot of time recently trying to make odoc more able to generate structured documentation sites, so I've gone all in and am trialling using it as a tool to generate my entire site. This is a bit of an experiment, and I don't know how well it will work out, but let's see how it goes.

Additionally, I've recently been working on a project currently called odoc_notebook, which is a set of tools to allow odoc mld files to be used as a sort of Jupyter-style notebook. The idea is that you can write both text and code in the same file, and then run the code in the notebook interactively. Since I've only got a webserver, all the execution of code has to be done client side, so I'm making extensive use of the phenomenal Js_of_ocaml project to get an OCaml engine running in the browser.

My focus has initially been on getting 'toplevel-style' code execution working. As an example, let's write a little demo.

Demo

Let's start with a little demo:

let x = 1 + 2 It's intended to look like an OCaml toplevel session, so each new expression starts with a # and is terminated with a double semicolon. The response from the toplevel is then below that indented with 2 spaces. Right now, there's not much in the way of error checking so you can make it all very confused by deleting the hash, removing the ;; and so on. Avoiding this, however, you can edit the numbers here and hit 'run' (maybe twice!) to see the results being updated.

There is also a little integration to allow the code to produce output more interesting than just text. The following cell creates an SVG image and 'pushes' it to Mime_printer, which receives the mime value and renders it in the browser below the code block.

Mime_printer.push "image/svg" (String.concat "\n" svg)

Things to come

Merlin support

There are a bunch of things I want to add to this, for example, Merlin support. In fact, merlin-js already exists and works, thanks to the fantastic work of Ulysse, but the problem is that it's not really designed for toplevel work, and it doesn't work when the code is broken up into chunks like I do here. So either I need to concatenate all the cells together before I give it to Merlin, or I need to make each cell it's own little module and 'open' every previous cell's module.

Within a single cell, it does already work. You can see that Merlin is correctly underlining the error in the following cell. You should also be able to hover over the variables and see their types.

type t = { foo : int; bar : string };;

let x = { foo = 1; bar = "hello" };;

let this_line_has_an_error = { foo = 1; bar = None };; But across cells, I've broken Merlin, though the code is executes correctly. You can see the problem in the following cell, which re-pushes the SVG image using the variable svg defined in the cell above. Merlin highlights the use of the varible svg is, because it's not aware of the varible, but the code gets executed correctly and the image is rendered below the cell.

Mime_printer.push "image/svg" (String.concat "\n" svg) Edit 2025-05-20: I have now got merlin working across cells, though I'm not convinced the current solution is the right long-term solution. S

Dynamic libraries

Currently the use of libraries it quite limited - they are defined more-or-less statically. I've had dynamic libraries working in the past, but I need to re-implement them. The plan is to have the cma files converted to js files and then load them on-demand when the notebook specifies them. The tricky thing here is that we need to be able to use them both in the browser and in bytecode executables so that the 'test-promote' workflow still works. This will probably require specifying the libraries by name, and having to re-implement the work that findlib does to find the libraries and load them and their dependencies in the right order, though this time entirely over HTTP.

Other things

There are loads of other things I'm interested in doing, including:

Investigating how to do 'exercises' to allow readers to try things out in a guided way
'Test cells' to see if implementations are correct
Persistence of the notebook state - both using local and remote storage
Integration of docs
Exploration of the execution model - how to run the code in the right order and ensure reproducibility
Use of remote execution engines rather than just in the browser
Other languages? Right now though, my focus is on the functionality required for this blog, with a secondary goal of looking at how we might use this sort of technology on the docs site on ocaml.org. Wouldn't it be cool to be able to drop into a live OCaml toplevel for any library in opam?

Example notebooks

As a more extended example of odoc notebooks, I have converted to this format the course that I help teach at the University of Cambridge; Foundations of Computer Science. Try them out for yourself!.

The Road to Odoc 3: Module Type Of

2025-03-08T00:00:00Z

There are many new and improved features that Odoc 3 brings, but there are also a large number of bugfixes. I thought I'd write about one in particular here, an overhaul of "module type of" that landed in May 2024.

Module Type Of

module type of is a language feature of OCaml allowing one to recover the signature of an existing module. For example, if I had a module X:

module X = struct
  type t = Foo | Bar
end

then I can get back the signature of X using module type of:

module type Xsig = module type of X

which can be very useful if you’re trying to extend existing modules amongst other things.

OCaml and Odoc treat module type of in somewhat different ways. OCaml internally expands the expression immediately it sees it, and effectively replaces it with the signature - ie, in the above example Xsig is now a signature, not a module type of expression.

In contrast, Odoc would like to keep track of the fact that this signature came from a module type of expression, as it’s very useful to know. If you’re extending a module, your signature might look like:

module type UnitExtended = sig
  include module type of Unit
  val extra_unit_function : unit -> unit
end

The documentation we produce will expand the contents of the include statement, but keep track of the fact that it came from a module type of expression so the reader can see where these signature items came from. In practice, you'd probably want to use module type of struct include Unit end, which is a bit different from simply module type of Unit, and I'll talk about this at some point in a future post.

The problem

We run into difficulties as soon as we introduce another language feature that operates on signatures: with. Let’s start with a module type S:

module type S = sig
  module X : sig
    type t = int
  end

  module type Y =
    module type of X
end

We’ll now define a new module X2 that we intend to use as a replacement for X:

module X2 = struct
  type t = int
  type u = float
end

Now we’ll define a new module type T which is S but with X replaced:

module type T = S with module X := X2

Here you can see that OCaml has expanded the module type of expressions and told us the computed signature. The interesting thing here is that in module type T, module type Y only has a type t in it, not a type u. As above, Odoc wants to keep the module type of expression so the reader can tell where module type Y came from. However, the substitution would do a different thing in this case - we would have the following:

module type T = sig
  module type Y = module type of X2
end

and the expansion of this would then clearly have both types t and u in it.

So now Odoc has two problems: We need to compute the correct signature, and we need to be able to describe how we computed it.

The solution

The previous solution to this was to have a ‘phase 0’ of odoc which would compute the expansions of all module type of expressions before doing any other work. This was necessary because of a ‘simplfying’ assumption in how we handled the typing environment. The new, simpler approach was to calculate the expansion during the normal flow of work, and never to attempt to recalculate it, but simply operate on the signature. This was a nice big simplification and optimisation that removed a few corner cases in the previous code (including an infinite loop that we hoped always terminated…!)

The second issue was how to describe it. We still want it clear that this signature was derived from another, but it’s clear we can’t honestly say that in the above example that it’s module type of X2. The answer is that we have applied a transparent ascription to the signature. Essentially, the signature is X2 but constrained to only have the fields of X.

This is not a current feature of OCaml, though Jane Street has done some work on this, including declaring the syntax: X2 <: X. However, there’s another interesting wrinkle here. X is a module defined in the module type S, so it’s not possible to write a valid OCaml path that points to it – S.X has no meaning. In addition, the right-hand side of the <: operator should be a module type, so we’d actually need to write X2 <: module type of S.X . We’re still figuring out the right thing to do here, so for now Odoc 3 will still pretend that it’s simply module type of X2.

Code block metadata

2025-03-07T00:00:00Z

Back in 2021 julow introduced some new syntax to odoc’s code blocks to allow us to attach arbitrary metadata to the blocks. We imposed no structure on this; it was simply a block of text in between the language tag and the start of the code block. Now odoc needs to use it itself, we need to be a bit more precise about how it’s defined.

The original concept looked like this:

{@ocaml metadata goes here in an unstructured way[
  ... code ...
]}

where everything in between the language (“ocaml” in this case) and the opening square bracket would be captured and put into the AST verbatim. Odoc itself has had no particular use for this, but it has been used in mdx to control how it handles the code blocks, for example to skip processing of the block, to synchronise the block with another file, to disable testing the block on particular OSs and so on.

As part of the Odoc 3 release we decided to address one of our oldest open issues, that of extracting code blocks from mli/mld files for inclusion into other files. This is similar to the file-sync facility in mdx but it works in the other direction: the canonical source is in the mld/mli file. In order to do this, we now need to use the metadata so we can select which code blocks to extract, and so we needed a more concrete specification of how the metadata should be parsed.

We looked at what mdx does, but the way it works is rather ad-hoc, using very simple String.splits to chop up the metadata. This is OK for mdx as it’s fully in charge of what things the user might want to put into the metadata, but for a general parsing library like odoc.parser we need to be a bit more careful. Daniel Bünzli suggested a simple strategy of atoms and bindings inspired by s-expressions. The idea is that we can have something like this:

{@ocaml atom1 "atom two" key1=value1 "key 2"="value with spaces"[
    ... code content ...
]}

Daniel suggested a very minimal escaping rule, whereby a string could contain a literal " by prefixing with a backslash - something like; "value with a \" and spaces", but we discussed it during the odoc developer meeting and felt that we might want something a little more familiar. So we took a look at the lexer in sexplib and found that it follows the lexical conventions of OCaml’s strings, and decided that would be a reasonable approach for us to follow too.

The resulting code, including the extraction logic, was implemented in PR 1326 mainly by panglesd with a little help from me on the lexer.