Guide
Why did that rebuild?
lev inspect build runs one Lake build and explains, from the traces Lake writes, why each module rebuilt.
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.
lev inspect build
lev inspect build -- Mathlib
lev inspect build --why Mathlib.Order.Basic -- Mathlib
lev -q inspect build --jsonArguments 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:
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,ReusedandRan. causescounts modules per kind of changed input:source,import,dependency,libraries,toolchain,options,configurationorother. Lake's own captions decide the kind, so a path that happens to contain "option" is still a source.editedlists the modules whose own source changed.unexplainedlists modules whose trace changed with no cause lev could name, andremovedthe traces the build deleted.slowestlists 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 checkworks at the declaration level;lev inspect builddoes not. - Only module traces below each package's
.lake/build/lib/leanare compared. Facets, executables and custom targets appear in the job counts but are not explained.