lev docs

How it works

Lake writes a .trace file next to every module it builds. The trace lists the inputs Lake hashed to decide whether the module was current: the source file, each import, the options, the Lean commit, and the package configuration. lev reads the trace of every module in every package of the workspace (the root package and everything in lake-manifest.json), runs lake --verbose build through elan with Lake's output passing through on stderr, and reads the traces again. A module whose trace changed is reported with the inputs that changed.

Terminal
lev inspect build
lev inspect build -- Mathlib
lev inspect build --why Mathlib.Order.Basic -- Mathlib
lev -q inspect build --json

Arguments after -- go to lake build unchanged. The exit status is Lake's. -q keeps Lake's output off stderr when only the report matters. The run registers the project for cache collection and holds a shared lock on the Lake cache, so a lev cache gc started meanwhile waits.

Reading the report

After adding a definition to Demo/A.lean in a library where Demo.B imports Demo.A and the root Demo imports Demo.B:

lev inspect build --why Demo
build passed in 0.251 s: 3 built, 0 fetched, 0 unpacked, 0 replayed, 0 reused, 6 ran
traces: 3 changed, 0 new, 0 removed
causes: 1 source, 2 import
edited: Demo.A
slowest:
          64 ms  Demo.B
          59 ms  Demo.A
          52 ms  Demo
why:
  Demo: import Demo.B
  Demo.B: import Demo.A
  Demo.A: source .../demo/Demo/A.lean
  • The first line counts Lake's job labels from its verbose output: Built, Fetched, Unpacked, Replayed, Reused and Ran.
  • causes counts modules per kind of changed input: source, import, dependency, libraries, toolchain, options, configuration or other. Lake's own captions decide the kind, so a path that happens to contain "option" is still a source.
  • edited lists the modules whose own source changed. unexplained lists modules whose trace changed with no cause lev could name, and removed the traces the build deleted.
  • slowest lists up to 20 built modules by Lake's reported time. Lean errors, Lake errors and failed targets follow when the build failed.

Following one module

--why MODULE follows the import causes from MODULE through other rebuilt modules until it reaches one that rebuilt for its own reasons: an edited source, new options, another toolchain. That is the edit to look at. If MODULE did not rebuild in this build, the report says so in a warning.

A trace that came from a cache download (lake exe cache get or Lake's own cache) records no inputs. For such a module lev names the imports whose public .olean changed and marks the causes as inferred.

JSON report

--json prints the envelope {"schema": "lev.cli.inspect.build/v2", "data": ...} on stdout. The data holds project, toolchain, command, status, exit_code, elapsed_ms, the job counts in actions, every job line in events, and per changed module modules[] with module, package, status (changed or new), action, elapsed_ms, causes[] (kind, input) and inferred. Then edited, unexplained, removed, traces_read, root_causes, failed_targets, why (with --why) and warnings.

What it cannot say

  • It explains the build it ran. Lake overwrites traces, so a rebuild that already happened cannot be explained afterwards. Run the next build through lev.
  • A trace says which inputs changed, not which declarations changed. lev check works at the declaration level; lev inspect build does not.
  • Only module traces below each package's .lake/build/lib/lean are compared. Facets, executables and custom targets appear in the job counts but are not explained.