Build integration
GuidesFindings 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 |
In the build
Section titled “In the build”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:
dune build @default @lint -wThe 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.
Fixing in the build
Section titled “Fixing in the build”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.
One unit
Section titled “One unit”For build systems that wire one rule per module:
$ litany unit inventory --cmt _build/default/lib/.inventory.objs/byte/inventory.cmt --source lib/inventory.mlIt 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.
Unit files
Section titled “Unit files”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:
$ 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.unitsThe file is canonical s-expressions, one form per line, in this order:
(litany-units 1), required.(complete false), when it isn’t your whole project.(cmi-dirs <dir>...), where to find the.cmifiles of dependencies.- One
(unit ...)per unit, with fields in the ordersource cmt cmti pp-source library public kind.sourceand one ofcmtorcmtiare required;pp-sourceis the preprocessed file, where there is one;publicistrueorfalse;kindislib,exeortest.
Anything else is refused. A wrong or stale entry costs a skip, never a finding.
A directory of artifacts
Section titled “A directory of artifacts”$ litany check --cmt-root _build/defaultPairs 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.
The cache
Section titled “The cache”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.
Workers
Section titled “Workers”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.

