MirageOS on OCaml 5!

OCaml 5 brought significant changes to fundamental parts of the language – notably concurrency using effects and multithreaded parallelism. This has caused some features and tools compatible with OCaml 4.14 to be incompatible with the new update, and several projects at Tarides aim to restore compatibility where that is the case. In today’s post, we will focus on the efforts toward creating a MirageOS port for OCaml 5.

The main benefit of making MirageOS compatible with OCaml 5 is to make it possible to explore how to best take advantage of features unique to the latest version of the language. An early proof-of-concept thus experimented with replacing Lwt with the new concurrency library Eio. This is just one example, but it illustrates why bringing OCaml 5 support to MirageOS is a high priority for our team.

To port MirageOS to OCaml 5 we have been contributing to the port using Solo5 backends but we are also exploring the possibility to use Unikraft backends. The Solo5 port has been released recently, with the versions 1.x of the ocaml-solo5 package on opam. As a complementary effort, work has also been ongoing to make cross-compilation easier in general. This will benefit not just the MirageOS project but also any cross-compilation projects for OCaml in the future. Let’s dive into the updates!

The Solo5 Backend

The first goal was to restore support for a backend that was available to OCaml 4.14 MirageOS users: Solo5. Solo5 is popular with developers building MirageOS unikernels, and since it is currently the only fully supported base for building a freestanding Mirage application, getting Solo5 support for OCaml 5 is a big step in the right direction for OCaml users.

The PRs that introduce OCaml 5.2.1 support via the Solo5 API is the fruit of the collective effort of many developers, including, in no particular order: Pierre Alain, Fabrice Buoro, Romain Calascibetta, Christiano Haesbert, Samuel Hym, @kit-ty-kate, Hannes Mehnert, and many more helpful eyes.

So, what is Solo5? Mirage applications can run in a hypervisor, such as KVM or Xen, without a full OS, and Solo5 provides minimal services (such as telling the time, reading or writing a block on the disk or network, etc.) for running an application there. OCaml-Solo5 adds the extra libraries required to build the OCaml runtime on top of Solo5.

What has Changed?

As you can imagine, the significant features introduced in OCaml 5 depend on correspondingly large changes to its underlying design. These include assumptions of how the OS works, how the C compiler works, and how the build system is set up. All of these modifications have a direct impact on what OCaml-Solo5 must provide to build the OCaml runtime for MirageOS unikernels.

If you prefer to dive right into the code changes, I recommend that you visit the PR directly. Otherwise, let’s take a look at what’s new!

Nolibc Extensions The usage of (OS) threads has changed, as well as how memory is managed (relying in particular on mmap/munmap), some C features such as thread-local storage and C11 atomics are now required. Support for all of these must be added in a freestanding setting such as MirageOS, even if Solo5 remains monocore. Therefore, to make OCaml-Solo5 compatible with the latest release, developers have amended the nolibc library and the way the C compiler is invoked. The modifications come in the form of extensions to nolibc, and most of the nolibc extensions included in the PR are inherited from previous PRs by @kit-ty-kate, Romain Calascibetta, and Pierre Alain, including changes to pthread, mmap and TLS.

Build System To address the build system changes, the PR applies version-specific patches to sources when fetched. This replaces the previous method of modifying the OCaml build system with seds and echos. The reasoning behind this change is twofold: Firstly, all bar one of the patches have been designed to improve how the compiler build system supports cross-compilation, simplifying the maintenance of the OCaml and Solo5 compatibility for MirageOS. Secondly, making the modification system into separate patches with full explanation messages makes reviewing them easier and clarifies to the user which modified build system they rely on. A neat bonus of this restructuring is that the .opt versions of the compiler are now also built, which should result in better performance, particularly when building large unikernels.

Toolchain The update also means that the ocaml-solo5 package now installs a new {aarch64,x86_64}-solo5-ocaml-* toolchain. Creating a toolchain avoids baking the build-time directories containing nolibc and openlibm into the generated OCaml compilers. The package generates two versions of the toolchain: one with built-time directories, that is added to PATH only when the compiler builds, and the other with the final destination directories, installed in the bin directory by opam.

Beside adding compatibility with OCaml 5 for Solo5, we are also exploring alternative options. In particular, we are working on adding Unikraft support to test whether it can provide better performance.

The Unikraft Backend

Unikraft is a Unikernel Development Kit that lets users create custom unikernels with a large support for standard APIs to help port applications. It is an open-source project maintained and supported by over fifty active contributors. The main benefit of adding support for a Unikraft backend to MirageOS is to improve I/O performance in comparison to the Solo5 API.

Because of these potential benefits, adding the Unikraft backend is a high priority. Currently, there are several repositories being worked on, the most mature of which is ocaml-unikraft. The project is still in an exploratory phase, and more updates will follow when we have more to share.

Making the Build of OCaml Cross Compilers Easier

In addition to new backends, part of improving the user experience with OCaml 5 has focused on improving the compiler’s build system, in particular regarding cross compilers, which is helpful for MirageOS users since OCaml-Solo5 is really a cross compiler to the Solo5 target.

The first step to streamlining the compiler’s build system involved reducing the number of Makefiles down to one, the root Makefile. By bringing all the build logic into one place and avoiding duplication and stacking dependencies, the compiler’s build system is more consistent and easier to use. The effort is split into many PRs, both big and small, including #11243, #11248, #11268, #11420, #11675.

In addition to reducing the number of Makefiles, the build system improvements also involved improving ocamldep. It needed to be able to distinguish between source vs build trees and have support for lex and yacc input files. The effort also included breaking the dynlink library’s dependency on compilerlibs to make the build system simpler and faster (#11996).

Continuing on this work, several PRs have brought more fixes and improvements to cross-compilation, with more on the way. Currently, the largest upstreamed PRs are #13281, #13282, #13526, and #13312. If you use the new OCaml 5 capabilities in Mirage with either the Solo5 or Unikraft, you can take advantage of the simplified build systems and cross-compilation.

Try it Yourself and Stay in Touch

OCaml-Solo5 is released and you can get started simply by building MirageOS in a 5.2.1 switch, with no pinning involved. Samuel wrote a quick guide on how to get started with ocaml-solo5 in a Discuss post, and we recommend you give it a try. For Unikraft, keep an eye out for updates as work continues behind-the-scenes.

You can connect with us on Bluesky, X, Mastodon, Threads, and LinkedIn or sign up for our mailing list to stay updated on our latest projects. We look forward to hearing from you!