simon/jolt
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: document tree-shaking + the runtime-resolution limitation

Browse source 
README + tools-deps.md cover --tree-shake and --direct-link: what tree-shaking does
(whole-program reachability over app + libraries + clojure.core, drop unreachable,
drop the compiler for no-eval apps), and why it bails to keep-all when reachable code
resolves vars by name at runtime (eval/resolve/ns-resolve/...), with the diagnostic
output and how to make an app shakeable. Notes the Stalin soundness model.
This commit is contained in:
Yogthos 2026-06-23 21:30:28 -04:00
parent 51a1a173d5
commit d5fea19a42
2 changed files with 56 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

18
README.md
View file

@ -58,8 +58,22 @@ bin/joltc build -m myapp.core -o myapp # compile myapp.core's -main into ./mya
```
Modes trade dynamism for speed: the default (release) build uses the proven code
generator; `--opt` also runs the inference + scalar-replacement passes over the
closed-world program; `--dev` is unoptimized.
generator; `--opt` also runs the inference + inlining + scalar-replacement passes
over the closed-world program; `--dev` is unoptimized.
Two opt-in closed-world flags cut dispatch cost and binary size:
```bash
bin/joltc build -m myapp.core --direct-link # app->app calls bind directly (no var lookup)
bin/joltc build -m myapp.core --tree-shake # ship only code reachable from -main
```
`--tree-shake` walks the call graph across your app, its libraries, and
`clojure.core`, drops everything unreachable from `-main` (and the compiler itself
when the app never `eval`s), and typically removes 1–2 MB. It stays sound by bailing
out — keeping everything, and reporting which library is responsible — when reachable
code resolves vars by name at runtime (`eval`/`resolve`/`ns-resolve`/…). See
[docs/tools-deps.md](docs/tools-deps.md) and `docs/rfc/0007`.
This needs Chez's kernel development files (`libkernel.a`, `scheme.h`) and a C
compiler. They come with a from-source Chez install; a distro `chezscheme`