Ocamlformat

Ocamlformat has not officially been adopted by the links project. This is simply a guide to introduce it.

Installation

Install Ocamlformat using opam install ocamlformat

Emacs setup:

Add the opam site-lisp directory to your load path, then load the ocamlformat file.

(push "~/.opam/4.07.0/share/emacs/site-lisp/" load-path)
(require 'ocamlformat)

Usage

Formatting the document

Commandline

Just call ocamlformat <file-name> to format a file.

It is possible to use the script tools/rules/ocamlformat_check.skip fix to apply to all files.

Emacs

Use the ocamlformat command (invoke using Alt-q).

It is also possible to use ocamlformat-write-on-save to have ocamlformat run automatically.

Configuration

Ocamlformat has multiple ways to change settings:

• project wide (.ocamlformat file)
• environmental variable OCAMLFORMAT=option=val
• file wide [@@@ocamlformat "option=val"]
• expression [@@ocamlformat "option=val"]

Disabling

There are several methods of disabling ocamlformat for certain pieces of code.

Formatting can be disabled for whole files by adding them to the .ocamlformat-ignore file in a project. Alternatively, [@@@ocamlformat "disable"] can be put in a file to disable formatting for the whole file.

To disable formatting locally, one can add

[@@ocamlformat "disable"]

to disable formatting for a particular binding/expression/etc.

Recommended links settings

These settings are set by default in the .ocamlformat file.

Make sure that match cases aren't put on the same line:

break-cases=toplevel

Ensure that documentation comments (** ... *) are formatted before the declaration:

doc-comments=before

Further settings

It is worth reading the man page for ocamlformat using man ocamlformat or ocamlformat --help.