Add Your Own Recipes to the OCaml Cookbook!

Are you looking to learn something new about OCaml? Or do you want to contribute to the community in a new way? OCaml.org hosts the OCaml Cookbook, a collection of projects that users can try out, as well as contribute new ones for others to enjoy. This post will introduce you to the concept, show you how to add new recipes, and hopefully leave you inspired to check it out for yourself!

Why do We Care About OCaml.org?

Tarides supports the maintenance and development of OCaml.org, OCaml’s home on the web. Our engineers have spent significant time collaborating with all corners of the OCaml community to update the website, including improving the design, accessibility, documentation, and much more. We continue to fund projects that implement new features that the OCaml community wants and maintain others that they have come to rely on.

As an open-source, collaborative, and shared resource for the ecosystem, OCaml.org is truly a public common. The OCaml Cookbooks are just one example of its many features, which also include tutorials, documentation, news, and an OCaml playground. We encourage more contributors, from sponsors to maintainers, to join the many others in supporting this important resource.

What is the OCaml Cookbook?

The OCaml Cookbook is a collection of ‘recipes’, instructions on how to complete tasks as part of projects using open source libraries and tools. The same task can have multiple recipes, each with its unique combination of resources. The result is a varied collection of projects that help users adopt new techniques, try new tools, and gain confidence in OCaml. OCaml’s book currently has recipes on compression, single-threaded concurrency, cryptography, and more!

OCaml is far from the only language to have a cookbook, and the team was inspired to create one by the popular Rust Cookbook, as well as Go’s Go by Example introduction to the language.

How to Contribute

The team behind the cookbook are always looking for new contributions, and creating a new recipe is straightforward if you follow the contributing instructions.

To add a new recipe to the cookbook, you will need to start by finding the OCaml.org repo on GitHub. To add a recipe to an existing task, find the task in the data/cookbook/tasks.yml section, go to the task’s folder inside data/cookbook/ which will have the same name as the task’s slug, and create an .ml file with the recipe and a YAML header with metadata about the recipe.

If the recipe you want to add doesn’t match an existing task, you will need to create a new task first. To add a task you will need to make an entry in the data/cookbook/tasks.yml file. When adding a new task in this file, the title, description, and slug are mandatory fields to fill in, and the task has to be located under a relevant category. You can even create new categories to organise entire groups of new tasks should you wish to do so.

Submitting a recipe will create a pull request, which the group of cookbook moderators will review and, if approved, merge into the website. When picking a recipe to contribute, you should bear the general guidelines in mind: choose a task that you think is relevant to a wide audience; write correct, clear, code that compiles without errors; and check that the packages you’ve chosen and the code are ready for use in production. That’s it, you’re ready to publish!

What Does a Recipe Look Like?

Let’s take a quick look at a recipe in action. The Salt and Hash a Password with Argon2 recipe in the Cryptography section shows you how to use the opam package argon2 to configure password hashing based on OWASP recommendations and Argon2 defaults. Be sure to check out the recipe on OCaml.org for the full context and nice formatting!

The recipe includes the code snippets for the configuration:

let t_cost = 2 and
    m_cost = 65536 and
    parallelism = 1 and
    hash_len = 32 and
    salt_len = 10

The hash output length:

let encoded_len =
  Argon2.encoded_len ~t_cost ~m_cost ~parallelism ~salt_len ~hash_len ~kind:ID

Generating a salt string:

let gen_salt len =
  let rand_char _ = 65 + (Random.int 26) |> char_of_int in
  String.init len rand_char

Returning an encoded hash string for the given password:

let hash_password passwd =
  Result.map Argon2.ID.encoded_to_string
    (Argon2.ID.hash_encoded
        ~t_cost ~m_cost ~parallelism ~hash_len ~encoded_len
        ~pwd:passwd ~salt:(gen_salt salt_len))

And finally, verifying if the encoded hash string matches the given password:

let verify encoded_hash pwd =
  match Argon2.verify ~encoded:encoded_hash ~pwd ~kind:ID with
  | Ok true_or_false -> true_or_false
  | Error VERIFY_MISMATCH -> false
  | Error e -> raise (Failure (Argon2.ErrorCodes.message e))

let () =
  let hashed_pwd = Result.get_ok (hash_password "my insecure password") in
  Printf.printf "Hashed password: %s\n" hashed_pwd;
  let fst_attempt = "my secure password" in
  Printf.printf "'%s' is correct? %B\n" fst_attempt (verify hashed_pwd fst_attempt);
  let snd_attempt = "my insecure password" in
  Printf.printf "'%s' is correct? %B\n" snd_attempt (verify hashed_pwd snd_attempt)

Contribute to the CookBook!

We invite you to take a look at the existing recipes up on the website and bring your own contributions to the book. If you have questions or want input on a recipe, OCaml’s Discuss forum is a great place to post to get tips and feedback.

Stay in touch with Tarides on Bluesky, Mastodon, Threads, and LinkedIn. We look forward to hearing from you!