ocamlformat Documentation

ocamlformat is an opinionated but fully customizable code formatter for OCaml. Key features include:

• Profiles: Predefined configurations like default, ocamlformat, and janestreet.
• Customization: Every option can be tuned via an .ocamlformat file.
• Comment Formatting: Supports formatting of comments, docstrings, and code blocks within comments.
• RPC Server: Provides an RPC interface that allows other tools to programmatically request code formatting.

Use the tools/test_branch.sh script to verify how different versions of OCamlFormat affect real-world source code. The script builds two versions of the tool and runs them against projects listed in test-extra/Makefile (which are cloned into test-extra/code).

When running the script:

• Staged changes represent the diffs introduced by formatting with the first version.
• Unstaged changes represent the diffs introduced by upgrading to the second version.

To test an extended list of projects during a release review, uncomment the projects in test-extra/Makefile and run:

tools/test_branch.sh -a "previous_release"

To generate and open the OCamlFormat documentation in your browser, run:

dune build @doc && xdg-open _build/default/_doc/_html/ocamlformat/index.html

You can build a native Windows binary using the mingw64 toolchain under Cygwin.

Prerequisites

Ensure your Cygwin installation includes:

• git, curl, unzip
• m4, patchutils, make
• mingw64-x86_64-binutils, mingw64-x86_64-gcc-core, mingw64-x86_64-headers, mingw64-x86_64-runtime

Build Steps

Run the provided build script from the repository root:

bash tools/build-mingw64.sh

Note: The first execution installs opam into the _build-mingw64 directory and installs all dependencies. Subsequent runs will only rebuild the binary. To perform a clean build from scratch, delete the _build-mingw64 directory.

To install ocamlformat, you must have OCaml and opam (the OCaml package manager) installed on your system. Use the following command to install the package:

opam install ocamlformat

printast is a tool that provides an equivalent to ocamlc -dparsetree but specifically for the normalized extended AST used within ocamlformat. It allows you to inspect how OCaml source code is represented in its processed AST form.

You can run it using dune exec by pointing it to a source file.

dune exec -- tools/printast/printast.exe test.ml

Before finalizing a release, verify that the built binary correctly reports the version number. Run the following sequence to build, install to a temporary prefix, check the version, and clean up:

dune build @install && dune install --prefix _install && ./_install/bin/ocamlformat --version && rm -rf _install

The output should be exactly the version number (e.g., a.b.c).

To customize formatting behavior, create an .ocamlformat configuration file in your project root. You can specify a predefined profile and the version of ocamlformat you are using.

Available profiles include:

• default
• ocamlformat
• janestreet

For a full list of configuration options, run ocamlformat --help or consult the official documentation.

profile = default
version = 0.29.0

You can format a specific file by running the ocamlformat command followed by the filename. If you are using the dune build system, you can use the dune fmt command to format your project.

ocamlformat file.ml

# Or using dune
dune fmt