OCaml Weekly News

Until August 2021, we had been working on the foundations for v3: the user flows, sitemap, and the reusable infrastructure for the data used in ocaml.org. With all the infrastructure and data ready, our efforts since have been focused on completing the frontend.

One of the clearest priorities we had from community feedback was to ensure that the unified package documentation gets to the live site as soon as possible. The build process for this is not trivial, as it involves combining the outputs of 20,000+ opam packages with the rest of the website, while maintaining a reasonable developer experience for the main site. We have therefore merged the various frontend and backend codebases into a single OCaml-based one. We've merged the NextJS / ReScript / Tailwind codebase to the backend server that serves the package documentation. This has allowed us to consolidate our technology stack and simplify our continuous deployment story, but also to directly serve the website from a pure OCaml stack (using packages from our own community such as Dream and ocaml-tls). We're deeply grateful to the ReScript team for the technology that let us prototype the new revision of the website so quickly, and to implement the templates we're now using.

Here's an overview of the sitemap and all the pages we've implemented.

• Homepage
  • About
  • Industrial users
  • Academic users
  • Success stories
  • Success story
• Learn
  • Books
  • Releases
  • Release
  • Papers
  • Tutorial
  • Best practices
  • Problems
  • Manual
• Packages
  • Packages search
  • Package
  • Package documentation
• Community
  • Events
  • Workshop
  • Opportunities
  • Opportunity
• Blog
• Legal
  • Carbon footprint

In addition to the frontend work, here are some backend highlights:

• A global navigation bar on the package documentaion. You can now navigate through all package libraries from the navbar (by @TheLortex in #86)
• A toplevel on the homepage (by @tmattio, @patricoferris and @jonludlam in #106, #135 and #159)
• Added redirections from current ocaml.org URLs
• An internationalisation framework that serves pages in different languages. The framework exists, but the page translations will come later (by @tmattio in #84)
• A code-highlighting library that adds code highlighting in the tutorials (by @patricofferis in #108)
• Handled Let's Encrypt certificate renewals and HTTPS redirects (by @tmattio and @patricofferis in #182)

See the full changelog here: https://github.com/ocaml/v3.ocaml.org-server/blob/main/CHANGES.md.

As mentioned above, we are feature complete, so we will be reviewing the site to get final approval from @xavierleroy and the core development team to launch the new site in a few weeks. We still have some work to do until then, but we'll dedicate these next few weeks to receive community feedback and make any appropriate changes.

So now is the time to give us the feedback you have! You can do this by replying to this post or opening GitHub issues on the repository ocaml/v3.ocaml.org-server. Mostly, we're hoping to receive actionable feedback such as:

• Are you able to find all the information you're expecting to find on the website?
• Do you find the documentation (both the learn section and package documentation) usable?
• Do you find some design elements make the website hard to use (e.g., for color blind folks)?

Also, please don't hesitate to open a GitHub Issue if you notice any bugs.

As you know, the release of OCaml 5.00.0, including Multicore support, is coming in 2022, so the timing of the v3 website launch is not coincidental. When OCaml 5.00.0 is released, the website will serve as an entry point for people new to OCaml, so we need to be ready with a usuable website, helpful documentation, clear package sites, etc. All your feedback and insights on how we can do better is greatly appreciated.

Launching the website is the first step on our roadmap to improve OCaml's online presence.

As mentioned above, the immediate goal is to be ready for this OCaml 5.00.0 release. With this in mind, for the next few months, we'll focus on improving the documentation and ensuring it includes good user pathways to learn about Domains, Effects, and generally how to write concurrent programs in OCaml.

In addition to the documentation, some of the other projects on our roadmap are:

• An online editor integrated in ocaml.org (aka a Playground)
• Toplevels for all the packages that compile to JavaScript

This is an exciting time! Stay tuned!

We need your help!

Until now, the development and design of the new site has been driven by a small team of people from Solvuu, OCaml Labs, Tarides, the University of Cambridge and individual contributors from our community. This was useful to get the momentum we needed to deliver on all the feedback from the community (package documentation, job board, new blog, etc.), but OCaml.org is a community project and needs to be driven by all of us.

In particular, we built what we hope is a good framework to represent the community with pages like:

• A job board
• The OCaml blog
• The meetings and workshops
• The industrial users and academic users
• The success stories

Now that the framework is there, we need your help to contribute to these pages, allowing us to serve great content and make the pages useful.

Thank you to everyone who contributed to the development of this new version of the website!

In particular:

• Ashish Agarwal (Solvuu)
• Kanishka Azimi (Solvuu)
• Richard Davison (Solvuu)
• Patrick Ferris (OCaml Labs)
• Gemma Gordon (OCaml Labs)
• Isabella Leandersson (OCaml Labs)
• Thibaut Mattio (Tarides)
• Anil Madhavapeddy (University of Cambridge)

For the groundwork on rethinking the sitemap, user flows, new content, design, and frontend and package docs!

• Jon Ludlam (OCaml Labs)
• Jules Aguillon (Tarides)
• Lucas Pluvinage (Tarides)

For the work on the package site infrastructure and UI!

• Paul-Elliot Anglès d'Auriac (Tarides)

For meticulously going through the website to find issues.

• Isabella Leandersson (OCaml Labs)
• Asaad Mahmood (Tarides)

For the work on the designs and bringing them to life on the frontend!

• Christine Rose (OCaml Labs)
• Isabella Leandersson (OCaml Labs)

For the work on the new content and reviewing the existing one!

We'd also like to thank the major funders who supported work on revamping the website: grants from the Tezos Foundation and Jane Street facilitated the bulk of the work. Thank you, and if anyone else wishes to help support it on an ongoing basis then donations to the OCaml Software Foundation and grants to the maintenance teams mentioned above are always welcomed.

Moving forward, updates on the v3 website will be taken over by @tmattio, who has kindly volunteered to run a community video chat "AMA" about how you can get involved and contribute, and to give your feedback directly. He will post here with more details when timezones are all worked out. We would, of course, be delighted to also use other community channels / podcasts / Twitch / Discords / etc to reach out and get feedback and ideas.

On a personal note, it's incredible to see this stream of hard work combine with the recent multicore OCaml merge to provide a modern, welcoming interface to the new users who will appear. I'm most excited about the future of OCaml we are embarking on with 5.0 – thank you to all who have been involved for being such wonderful collaborators.

Depending on your runtime context, you can get few metrics from the kernel. For instance, Linux comes with the perf tools which is able to record some metrics such as:

• the cpu-clock: this reports the CPU clock, a high-resolution per-CPU timer.
• the page-faults: this reports the number of page faults
• etc.

They are available via the bechamel-perf package which can be linked with your benchmark. You can see a simple example into the distribution: sqrt.ml

The HTML + Javascript is pretty simple to generate. Let's say that you have:

let benchmark () : (Bechamel_js.ols_result * Bechamel_js.raws) =
  let ols = Analyze.ols ~bootstrap:0 ~r_square:true ~predictors:Measure.[| run |] in
  let instances = Instance.[ minor_allocated; major_allocated; monotonic_clock ] in
  let cfg =
    Benchmark.cfg ~limit:2000 ~stabilize:true ~quota:(Time.second 0.5)
      ~kde:(Some 1000) () in
  let raw_results =
    Benchmark.all cfg instances
      (Test.make_grouped ~name:"factorial" ~fmt:"%s %s" [ test0; test1 ]) in
  let results = List.map (fun instance -> Analyze.all ols instance raw_results) instances in
  let results = Analyze.merge ols instances results in
  (results, raw_results)

You just need to "emit" results into the JSON format:

let compare k0 k1 =
  let a = ref 0 and b = ref 0 in
  Scanf.sscanf k0 "%s %s %d" (fun _ _ a' -> a := a');
  Scanf.sscanf k1 "%s %s %d" (fun _ _ b' -> b := b');
  !a - !b

let nothing _ = Ok ()

let () =
  let results = benchmark () in
  let results =
    let open Bechamel_js in
    emit ~dst:(Channel stdout) nothing ~compare ~x_label:Measure.run
      ~y_label:(Measure.label Instance.monotonic_clock)
      results in
  match results with Ok () -> () | Error (`Msg err) -> invalid_arg err

And a simple intrumentation of dune is enough to generate the HTML + Javascript page via bechamel-html:

(executable
 (name fact)
 (modules fact)
 (public_name bechamel-js.examples.fact)
 (package bechamel-js)
 (libraries bechamel bechamel-js))

(rule
 (targets fact.json)
 (action
  (with-stdout-to
   %{targets}
   (run ./fact.exe))))

(rule
 (targets fact.html)
 (mode promote)
 (action
  (system "%{bin:bechamel-html} < %{dep:fact.json} > %{targets}")))

You can see a full example here.

The micro-benchmark can be useful to ensure assumptions about syscalls. But they can require some resources. In that situation, Bechamel allows the user to define an allocation function which is executed before the benchmark.

This resource will be used by your test and will be released then at the end of the benchmark. For instance, Bechamel allows to record metrics for, for instance, io_uring.

We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil – Donald Knuth

Micro-benchmark should not be an argument to micro-optimize some parts of your code. Indeed, Bechamel mostly wants to report some observable values and ensure to avoid the Schrödinger's cat case (where the tool affect results by the observation).

Bechamel wants to help the developper to assert some assumptions but it should not be an argument to say that your implementation is faster than an other one - at least, it helps you on this way.