lev docs

What lev keeps

lev's cache directory is --cache-dir, else LEV_CACHE_DIR, else $XDG_CACHE_HOME/lev, else ~/.cache/lev on Linux, ~/Library/Caches/lev on macOS and %LOCALAPPDATA%\lev\cache on Windows.

Layout
projects-v2/<hash>.json                  one record per project lev built or checked
locks/                                   lock files
check-v1/exporters/<toolchain>-<key>/    lev-export, built with that toolchain
check-v1/references/<toolchain>-<key>/   the export of the toolchain's Init
check-v1/verdicts/                       one small file per kernel and slice
check-v1/scratch/                        exports and slice files of running checks

A project record holds the project's root, its toolchain, the Lake artifact cache its last build used, and when lev last used it. With Lean v4.36.0-rc2 an exporter build takes about 120 MiB and a reference about 355 MiB. A verdict is a few hundred bytes; Mathlib has about 11,000 slices per kernel.

lev cache status

lev cache status
lev cache   .../cache (476.7 MiB)
projects    1 registered, 0 no longer on disk
check cache .../cache/check-v1
  exporters   1 (121.8 MiB)
  references  1 (354.9 MiB)
  verdicts    6 (19.3 KiB)
  scratch     0 (0 B)
Lake cache  .../toolchains/leanprover--lean4---v4.36.0-rc2/lake/cache (1 project)
  artifacts   31426 (947.0 MiB), 0 hard-linked (0 B)
  mappings    65698
  unmapped    0 artifacts (0 B)
  missing     0

For every Lake cache a registered project used, status counts the artifacts (and how many are hard-linked from a build directory, which removing would not free), the mappings from a build's input hash to its outputs, the artifacts no mapping names, and the local mappings whose artifacts are missing. It exits 1 when there is such a missing artifact, since Lake would then fail to restore that build.

lev cache gc

Terminal
lev cache gc
lev cache gc --lake --max-age-days 7 --json
lev cache gc --lake --apply

Without --apply the command only lists. Without --lake it leaves Lake's caches alone and lists only lev's own entries. Each line names the kind of entry, its size and its path:

KindListed when
project-recordThe project's lean-toolchain is gone and lev last used it before the age gate.
staging-fileAn interrupted record write older than the gate.
check-exporter, check-referenceNo check used it within the gate.
check-verdictNo check reused it within the gate. A check touches every verdict it reuses.
check-scratchLeft behind by an interrupted check and older than the gate.
lake-mappingWith --lake: no live registered project's traces have its input hash, and it is older than the gate.
lake-artifactWith --lake: neither those traces nor a kept mapping names it, it is older than the gate, and no build directory hard-links it.

The gate is 30 days unless --max-age-days N says otherwise. A Lake cache with Lake's older inputs/ layout, or with missing artifacts, is reported and left alone. So is a Lake cache whose references lev could not read in full: a registered project that uses it has a trace lev cannot read or parse, a manifest it cannot read, or a lakefile that mentions buildDir, since lev reads traces only below .lake/build. A collected Lake cache that is not a registered project's own .lake/cache, such as the toolchain's default cache, is listed as shared: projects lev has not registered may use it too.

What protects an entry

Lake's entries are protected by the traces of live registered projects: a project registers itself whenever you run lev inspect build or lev check in it, and stays live while its lean-toolchain file exists. A Lake build of a project lev has never seen is not protected, so read the list before you apply it, especially when the cache is the toolchain's default one that every project on the machine shares. The caches of lev check are protected by use alone; a removed exporter, reference or verdict is rebuilt by the next check.

Locks

lev inspect build and lev check hold a shared lock on the Lake cache they build into, and lev check holds a shared lock on its own caches. lev cache gc takes those locks exclusively before it reads the registry and any trace, and reads the registry again when it names a Lake cache it has not locked yet, so it waits for running builds and checks, sees the projects they registered, and they wait for it. Processes that do not take the locks, such as a plain lake build, are not excluded.