How to Set up Automatic Formatting

This guide will show you how to configure Dune so that it can check the formatting of your source code.

Formatting is defined per project. This ensures that if a project is reused elsewhere, its formatting configuration will not interfere.

Setting Up the Environment

First, let’s open the dune-project file. Make sure that the version specified in (lang dune X.Y) is at least 2.0. Most formatting configuration happens in that file. If you want to format OCaml sources and dune files, you don’t have anything to add. Otherwise, refer to the (formatting) stanza.

Next we need to install some code formatting tools. For OCaml code, this means installing OCamlFormat with opam install ocamlformat. Formatting dune files is built into Dune and does not require any extra tools. For Reason code, this uses the refmt tool which is already installed if you are using Reason syntax in your project. If your project uses a dialect, a specific tool might be required.

Using OCamlFormat requires some configuration. Take note of the version returned by ocamlformat --version (let’s name that X.Y.Z) and create an .ocamlformat file in the same directory as dune-project with the following contents:

version=X.Y.Z
profile=default

The version line is checked by OCamlFormat and ensures that everybody contributing to the project uses the same version.

Note that you do not have to add ocamlformat to your opam files.

Running the Formatters

Run the dune build @fmt command. It will format the source files in the corresponding project and display the differences:

$ dune build @fmt
--- hello.ml
+++ hello.ml.formatted
@@ -1,3 +1 @@
-let () =
-  print_endline
-    "hello, world"
+let () = print_endline "hello, world"

Then it’s possible to accept the correction by calling dune promote to replace the source files with the corrected versions.

$ dune promote
Promoting _build/default/hello.ml.formatted to hello.ml.

As usual with promotion, it’s possible to combine these two steps by running dune build @fmt --auto-promote. This command can also be shortened to dune fmt. See Diffing and Promotion for more details.

Setting Up Your CI

To check formatting in CI, the precise set up depends on the CI system used, but in general it is easier to set up a dedicated job that just installs dune and the formatting tools, rather than doing that as part of the jobs that run tests.

If you use ocaml-ci, you have nothing to do: a formatting job is set up automatically.

If you use setup-ocaml, you can use the lint-fmt extend listed in the README file.