A modular OCaml project structure
Tags: ocaml, bucklescript, reason
Published: 2019-01-02 21:32:32

---
title: A modular OCaml project structure
published: true
description: A flexible layout that uses a top-level module to organize the project
tags: ocaml,bucklescript,reasonml
---

THANKS to new efforts in the OCaml ecosystem like ReasonML, BuckleScript, and Dune (formerly JBuilder), there are quite a few new OCaml projects being started nowadays. The BuckleScript and Dune build systems provide automatic project-level namespacing, which is quite convenient. _However,_ they do set some defaults which I feel lose some nicer features in a project, like having a toplevel module that can be documented with OCaml's built-in [documentation comments](https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sec351). [EDIT: after using Dune for a bit–you can definitely have a toplevel module in the project. It's just that each 'index' module (see below) lives at the same level in the filesystem hierarchy as its children modules.]

In this post I describe a project structure that places OCaml's _modules_ at the forefront. It involves a little legwork, but as we'll see, not more than in equivalent OCaml or JavaScript projects, and it pays off in a big way in readability and documentation.

Suppose you have a project `https://github.com/myname/myproject`, with the following main code files: `add.ml`, `subtract.ml`, `multiply.ml`, and `divide.ml` and corresponding interface files (or `.re`/`.rei`). I suggest the following layout for the code files:

```
myproject/
  src/
    Myname__Myproject.ml
    Myname__Myproject/
      Myname__Myproject__Add.ml
      Myname__Myproject__Add.mli
      Myname__Myproject__Subtract.ml
      Myname__Myproject__Subtract.mli
      Myname__Myproject__Multiply.ml
      Myname__Myproject__Multiply.mli
      Myname__Myproject__Divide.ml
      Myname__Myproject__Divide.mli
```

... and so on for other nested modules. The key is to have a _single_ toplevel module `Myname__Myproject.ml` under the `src/` directory, corresponding to the name of the project. It provides the following benefits:

- a namespace for the project (because OCaml doesn't by default)
- a unified toplevel for the project code documentation
- an entry-point and index module for your project as a whole

This toplevel module can be named anything, really; people have (e.g.) used `Myproject.ml` for convenience. I highly recommend `Myname__Myproject`, however, in order to namespace it more strongly with your username and avoid conflicts.

## Why `Myname__Myproject` instead of `Myname.Myproject`

In OCaml, existing modules aren't extensible. This means that you can't release a project containing a `Myname` module and then later release a project containing another `Myname` module and use both the projects together. This is inconvenient but understandable if you look at it from OCaml's point of view (i.e. people shouldn't be able to mess with existing modules).

The workaround, `Myname__Myproject`, is ultimately not too cumbersome–in my opinion.

## The toplevel module should contain...

- toplevel code documentation for the project as a whole
- nested module aliases to the project's exported modules so that users can refer to them with dot-notation
- code documentation for the module aliases so that the docs appear for the corresponding modules

For example:

```ocaml
(** [Myname__Myproject.ml] - this is the toplevel module documentation. *)

(** Module-level documentation for the [Add] module *)
module Add = Myname__Myproject__Add

(** Module-level documentation for the [Subtract] module *)
module Subtract = Myname__Myproject__Subtract

(** Module-level documentation for the [Multiply] module *)
module Multiply = Myname__Myproject__Multiply

(** Module-level documentation for the [Divide] module *)
module Divide = Myname__Myproject__Divide
```

Now, users of your library or app can refer to your modules using convenient dot-notation and auto-complete: `Myname__Myproject.Add`, etc. They can alias the long toplevel module name for ease of use: `module Proj = Myname__Myproject`. And they can access the entire project (code and documentation) through a convenient single point of entry.

## Exported modules vs not

Earlier I mentioned that you can provide aliases in the toplevel module for the modules you want to _export._ This is more of a convention; if you have for example a file `Myname__Myproject__Sqrt.ml` in your source tree, the module `Myname__Myproject__Sqrt` will be visible to users of your library. OCaml doesn't really have a way to hide file modules. [EDIT: this is also not quite true–see my [next post](/yawaramin/bucklescript-best-practice-public-and-private-modules-5ald) about this.] But by not listing it in your toplevel module, you do provide a strong hint that it's project-internal.

This might seem like a limitation but keep in mind that in mainstream languages like Java you can't hide public classes from consuming packages either (at least, not unless you use the new Java modules feature).

## Aliased module cyclic dependencies

Aliased modules in the same path can't refer to each other with dot-notation. For example, in `Myname__Myproject__Multiply.ml`, you can't call `Myname__Myproject.Add.whatever`. The problem is that the `Myname__Myproject` refers to `Myname__Myproject__Multiply` (because it aliases it). So the latter also referring to the former makes a cyclic dependency and OCaml doesn't support cyclic dependencies across separate files.

The solution is to use the full (underscored version) module name from modules in the same directory root.

## Overall

I believe this custom work is worth it overall, because it provides a better experience for users (and readers, including Future You). OCaml projects have historically dumped all the source code into a single directory because OCaml doesn't namespace by directory. The layout I suggest here exposes the complexity of your project in smaller chunks, with a more easily-digestible entry-point.

My hope is that in the future the OCaml ecosystem will organize itself more around modules rather than packages (e.g. https://opam.ocaml.org/packages/ , https://redex.github.io/ ) as the standard searchable units of code reuse. OCaml modules have certain benefits, like automatic compile-time compatibility checking, that make them quite suited to taking the role of 'packages' from other ecosystems.

Searchable module indexes that work by indexing 'exported' modules (i.e. aliased modules reachable from the toplevel module) would do away with the effort of having to search for packages in the ecosystem to find specific modules that we need.

Another benefit I haven't actually mentioned yet is that this structure is very amenable to a documentation toolchain that understands OCaml doc comments. For example, I have an OCaml [project with generated documentation](https://github.com/yawaramin/bs-webapi) that I hope to blog about in the near future.