Skip to content

Build integration

Findings in your editor through a dune rule, other build systems, the cache and the workers.

How Command Project rules
dune, the default litany check yes
a dune rule litany check as an action no
one unit litany unit no
a unit file litany check --units FILE if the file is complete
a directory of artifacts litany check --cmt-root DIR no

One rule you write yourself runs litany inside the build:

(rule
(alias lint)
(deps (alias_rec check))
(action (run litany check)))

dune build @lint fails on findings, and they are ordinary dune diagnostics. Add it to your watch and they reach your editor as compiler warnings, with no plugin:

Terminal window
dune build @default @lint -w

The rule lints the directory it is in and below, and reads the workspace’s litany file. Run project rules and the rules that need a unit’s kind, which litany names as withheld, from a terminal or CI, since they don’t run here.

With (lang dune 3.23), add --fix and (corrections produce):

(rule
(alias lint)
(deps (alias_rec check))
(corrections produce)
(action (run litany check --fix)))

The build fails showing each fix as a diff, and dune promote applies them. Without (corrections produce) dune silently drops the fixes: if a fix rule builds green while it prints 1 fix proposed, that field is missing. On older dune, run litany check --fix from a terminal.

For build systems that wire one rule per module:

Terminal window
$ litany unit inventory --cmt _build/default/lib/.inventory.objs/byte/inventory.cmt --source lib/inventory.ml

It runs the default rules and ignores the litany file, so a build rule means the same on every checkout. A unit it can’t lint is a refusal, exit 2.

A unit file tells litany about any build system’s output. --units reads the file --save writes, in which every atom is length-prefixed ((4:unit(6:source8:lib/a.ml))); what litany units prints is the same document for a person to read, and is not accepted back:

Terminal window
$ litany units
(litany-units 1)
(cmi-dirs _build/default/lib/.inventory.objs/byte)
(unit (source lib/inventory.ml) (cmt _build/default/lib/.inventory.objs/byte/inventory.cmt) (library inventory) (public false) (kind lib))
$ litany units --save litany.units
$ litany check --no-build --units litany.units

The file is canonical s-expressions, one form per line, in this order:

  1. (litany-units 1), required.
  2. (complete false), when it isn’t your whole project.
  3. (cmi-dirs <dir>...), where to find the .cmi files of dependencies.
  4. One (unit ...) per unit, with fields in the order source cmt cmti pp-source library public kind. source and one of cmt or cmti are required; pp-source is the preprocessed file, where there is one; public is true or false; kind is lib, exe or test.

Anything else is refused. A wrong or stale entry costs a skip, never a finding.

Terminal window
$ litany check --cmt-root _build/default

Pairs the .cmt files under a directory with their sources by digest. It knows nothing of libraries, so project rules and rules that depend on a unit’s kind don’t run, and the summary lists them.

litany check caches results per unit, keyed by everything that can change them, and output is the same warm or cold.

Control Effect
--cache-dir DIR, LITANY_CACHE_DIR where to store it
neither $XDG_CACHE_HOME/litany, else ~/.cache/litany
--no-cache run uncached
--cache-stats print hits and misses

Entries unread for 30 days are evicted, and deleting the directory is always safe.

litany check -j N analyses units in N processes, by default one per core, and the output doesn’t depend on N. --fix runs in one process.