# 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 ```sh 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](../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](adr/README.md), 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 by `ci.sh` and the bench/stress scripts) links Rust builds with mold when it's installed; override by setting `RUSTFLAGS`. - **Shared hosts**: with several agents on one machine, `LOUISE_CI_SHARED_HOST=1` serializes the heavy lanes (loom, aarch64, spike, sanitizers, stress) through `/tmp/louise-ci-heavy.lock`, niced. Standalone scripts get the same via `heavy()` in `scripts/lib.sh` (e.g. `same-output.sh` wraps 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](../AGENTS.md). On a shared host, `CARGO_BUILD_JOBS` around CPUs÷agents keeps builds out of each other's way. If you have [mask](https://github.com/jacobdeichert/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](adr/README.md), and need engineering review before they are marked Accepted (issue #44). ## Cutting a release 1. Bump `version` in the workspace `Cargo.toml` — it is what `louise --version` prints — and commit. 2. Tag the merge `v` and push the tag. 3. `.toboggan/workflows/release.yml` builds the dist compiler and the runtime archives, smoke-tests that the tag names the workspace version, and uploads `louise--x86_64-linux.tar.xz` as the run's artifact. `louise self update` finds it from there.