
louise
Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.
Contributing
The compiler, the runtime and the language server are written in Rust; the compiler emits C, which a C compiler turns into an executable linked with the runtime library.
You need
- Rust, at the version pinned in
rust-toolchain.toml; - clang 13+ or GCC 15+, for native builds;
- clang, for the sanitizer runs.
Commands
cargo run -p louise -- check # check the package in the current directory
cargo run -p louise -- check file.lse # check a standalone file
cargo run -p louise -- run tests/run/effects.lse # run a program with the interpreter
cargo run -p louise -- run --native file.lse # compile it to C and run it
cargo run -p louise -- test # run the package's @test functions
cargo run -p louise -- fmt # format the package
cargo run -p louise -- core file.lse # print the Core IR
scripts/ci.sh # every check CI runs (LOUISE_CI_FULL=0: a pull request's quick lane)
scripts/ci.sh docs # a profile: docs, compiler, runtime, full (auto picks from the diff)
scripts/spike.sh --asan # the ABI spike under sanitizers
scripts/tsan.sh # ThreadSanitizer (nightly with rust-src, clang)
scripts/bench.sh # the benchmarks (tests/bench/README.md)
scripts/bench-variance.sh # their build-to-build spread (issue #193)
scripts/same-output.sh [BASE] # does a refactor change the compiler's output? (diffs check/core/C against BASE)
Native builds need liblouise_rt.a next to the louise binary: cargo build -p louise_rt (or --release for both). Release builds link liblouise_rt-fast.a instead when it is there (ADR 0031): scripts/runtime.sh [debug|release|dist] builds it (whole-program LTO, one codegen unit, panic = "abort", no leak oracle); without it they fall back to liblouise_rt.a with a warning. Where clang, ld.lld and llvm-ar are installed, scripts/runtime.sh also builds liblouise_rt-lto.a, the same runtime as LLVM bitcode, and release builds link it by cross-language ThinLTO with the program's C when clang and lld read its LLVM version (ADR 0032); otherwise they link fast. LOUISE_RUNTIME=checked, fast or lto forces one: a release build whose leaks you want to count needs checked, and lto says why it can't be used. The dist profile (--profile dist, into target/dist/) is what releases use: whole-program LTO and one codegen unit, about 8% faster and a 40 s build. The benchmark scripts take LOUISE_PROFILE=dist, and scripts/bench-track.sh uses it (issue #120).
Layout
| Path | What |
|---|---|
crates/louise/ | The louise command-line driver. |
crates/louise_syntax/ | Lexer, error-tolerant parser, lossless CST, typed AST. |
crates/louise_hir/ | Name resolution, module graph, desugaring (use, |>). |
crates/louise_types/ | Type inference, traits, exhaustiveness. |
crates/louise_db/ | Analysis database shared by the CLI and the LSP. |
crates/louise_package/ | Packages: manifests, the lockfile, the git cache, dependency resolution. |
crates/louise_lsp/, editors/vscode/ | Language server and VS Code client. |
std/ | The standard library, in Louise (embedded in louise). |
crates/louise_core/ | Core IR, lowering from typed HIR, evidence specialisation, the optimiser (ADR 0043). |
crates/louise_interp/ | The reference interpreter (the native backend's test oracle). |
crates/louise_build/ | The native build: compiles the generated C and native dependencies, links louise_rt. |
tests/run/ | Programs with expected output (//> lines; see tests/README.md). |
crates/louise_testkit/ | Helpers for the compiler's integration tests (dev-only). |
tests/ui/ | Type-checker tests with inline //~ ERROR / //~ TYPE expectations. |
crates/louise_span/, crates/louise_diag/ | Source positions; diagnostics and their rendering. |
docs/reference/ | Grammar and diagnostic codes. |
runtime/louise_rt/ | Runtime staticlib (Rust, C ABI). include/louise_rt.h is the ABI. |
runtime/louise_rt_prims/ | The runtime's pure kernels and constants, shared with the interpreter and the compiler. |
runtime/spike/ | Hand-written "generated" C exercising the ABI, run under sanitizers. |
docs/runtime-abi.md | The ABI explained. |
docs/wire-format.md | Distribution's type descriptors, type hash and value encoding (ADR 0072). |
examples/, packages/ | Example programs, and packages such as argon2. |
docs/adr/ | Architecture decisions (index, with their review status). |
scripts/ci.sh | Every check CI runs. |
.toboggan/workflows/ | The forge's CI, on toboggan.cloud's CI host in its Rust image (runs-on: rust: the pinned toolchains, clang, lld, mold, sccache): ci.yml (scripts/ci.sh's four parts — LOUISE_CI_PART check, native, packages, runtime — as parallel jobs; a pull request runs the quick lane, a push to main runs everything; every compilation goes through sccache against the host's compile cache, which main's runs write and pull requests read), tsan.yml (scripts/tsan.sh, its instrumented std from the same cache) and asan.yml (on a pull request that touches the runtime, the compiler, std or the test programs, and nightly on main), bench.yml (benchmarks over time, on a dedicated runner), release.yml (a tag's prebuilt binaries, which louise self update installs). |
Fast local CI
scripts/ci.sh runs every check; locally it picks a profile from the diff so a docs change doesn't pay for loom and sanitizers. Explicit: scripts/ci.sh docs|compiler|runtime|full (or LOUISE_CI_PROFILE=…; auto is the local default, full on runners where CI=true).
| Profile | Runs |
|---|---|
docs | rustfmt, clippy, unit tests, the Louise fmt check |
compiler | docs + native differential tests, packages/examples, stress |
runtime | everything: loom, aarch64, the ABI spike, sanitizers |
full | everything (what main runs) |
Three more things that are always on, so nobody has to remember them:
- mold:
scripts/lib.sh(sourced byci.shand the bench/stress scripts) links Rust builds with mold when it's installed; override by settingRUSTFLAGS. - Shared hosts: with several agents on one machine,
LOUISE_CI_SHARED_HOST=1serializes the heavy lanes (loom, aarch64, spike, sanitizers, stress) through/tmp/louise-ci-heavy.lock, niced. Standalone scripts get the same viaheavy()inscripts/lib.sh(e.g.same-output.shwraps its compiler builds), so the lock covers them too. - The forge carries CI: open PRs as drafts (
tob pr create,tob pr draft) — a pull request runs the quick lane on a runner, and merging to main runs everything. A branch's newer push cancels its older run. Agents: AGENTS.md.
On a shared host, CARGO_BUILD_JOBS around CPUs÷agents keeps builds out of each other's way. If you have mask, mask ci, mask test, mask bench etc. alias the scripts (see maskfile.md); nothing requires it.
Decisions
Architecture, type-system and runtime decisions are recorded as ADRs in docs/adr, and need engineering review before they are marked Accepted (issue #44).
Cutting a release
- Bump
versionin the workspaceCargo.toml— it is whatlouise --versionprints — and commit. - Tag the merge
v<version>and push the tag. .toboggan/workflows/release.ymlbuilds the dist compiler and the runtime archives, smoke-tests that the tag names the workspace version, and uploadslouise-<tag>-x86_64-linux.tar.xzas the run's artifact.louise self updatefinds it from there.