tobogganSe connecter

louise

Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.

89 lignes · 7945 octetsBrut · Historique

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

PathWhat
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.mdThe ABI explained.
docs/wire-format.mdDistribution'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.shEvery 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).

ProfileRuns
docsrustfmt, clippy, unit tests, the Louise fmt check
compilerdocs + native differential tests, packages/examples, stress
runtimeeverything: loom, aarch64, the ABI spike, sanitizers
fulleverything (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.

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

  1. Bump version in the workspace Cargo.toml — it is what louise --version prints — and commit.
  2. Tag the merge v<version> 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-<tag>-x86_64-linux.tar.xz as the run's artifact. louise self update finds it from there.