Build the compiler
For everyday use, install the pre-built axle binary. See Install the compiler. This page is for working on the
compiler itself: building the workspace from source, running the test
suite, and iterating on a patch.
The Axle compiler is a Rust workspace. Its rust-toolchain.toml pins the
toolchain, and rustup installs and selects it automatically. axle_codegen links LLVM 21.1.8, so the LLVM you install must be that major version.
Note: this page covers the LLVM prerequisites for each platform, the cargo commands you will run most often (build, test), the lint gate that CI applies, and what a source checkout builds that a plain
cargo builddoes not.
Prerequisites
Linux (Ubuntu / Debian)
sudo apt-get install -y \
llvm-21 llvm-21-dev \
lld-21 liblld-21-dev clang-21 build-essential pkg-config
export LLVM_SYS_211_PREFIX=/usr/lib/llvm-21 macOS
brew install llvm@21
export LLVM_SYS_211_PREFIX=$(brew --prefix llvm@21) Windows
Download the official clang+llvm-21.1.8-x86_64-pc-windows-msvc.tar.xz release,
and set LLVM_SYS_211_PREFIX to its extracted root. The LLVM 21 Windows
libraries are built against the static CRT (/MT), so the build needs a +crt-static rustflag. The repository’s .cargo/config.toml sets it.
No libxml2 is needed, even though that release names one. The build supplies the
empty libxml2s.lib that llvm-config --system-libs asks for. The compiler also
links LLD with LLVM’s no-libxml2 manifest merger. The full, reproducible Windows
setup, including the .cargo/config.toml and the Windows SDK -L native= paths,
is in SETUP-WINDOWS.md.
Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh Installing rustup is enough. The repository’s rust-toolchain.toml selects 1.94.1, and rustup fetches it on the first build. No rustup default is
needed.
Build the workspace
git clone https://gitlab.com/axle-lang/axle.git
cd axle
cargo build --workspace --release The axle driver lands at target/release/axle, or target\release\axle.exe on Windows. Put it on your PATH, or invoke it by its full path.
The four runtime archives
Every program the compiler produces links four static libraries: axle_stdlib, axle_runtime, axle_tls and axle_reactor.
axle (the driver) links on every line, in this order
───────────────── ───────────────────────────────────
searches for the archives 1. the explicit override, per archive
2. beside the axle binary
3. beside the binary, in lib/
4. one level up (cargo test layout)
5. ../lib/axle (installed prefix)
6. the AXLE_LIB_DIR directory
7. otherwise: RuntimeLibNotFound, no link cargo build --workspace builds all four, so a from-source build works. cargo build -p axle_cli does not build them. Build the workspace, or name
the four crates, before you run anything that links a program.
The shipped archives are built differently. tools/build-libs.sh builds
the archives that ship. It uses a dated nightly and -Zbuild-std, which strips std’s panic reporter. A plain cargo build keeps the panic messages, so a
binary built locally links larger than a released one. Run tools/build-libs.sh before you quote a binary size.
Run the test suite
The CI test job runs the suite in the debug profile, with the four archives built first:
cargo build -p axle_stdlib -p axle_runtime -p axle_tls -p axle_reactor
cargo test --workspace cargo test alone does not produce the .a archives. Its test binaries link
against them, which is why the build step comes first.
cargo-nextest is a faster drop-in, and it is what CI uses:
cargo install --locked cargo-nextest
cargo nextest run --workspace Lint
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings CI runs both on every merge request. Running them locally before you push keeps your pipeline green.
Limits / Uncabled
| Feature | State | Detail / workaround |
|---|---|---|
| Two toolchains | By design | rust-toolchain.toml pins the channel that builds the compiler, the LSP and the tests. The four runtime archives are built by the dated nightly that tools/build-libs.sh names, because -Zbuild-std is nightly-only. Both must share LLVM 21.1.8, or the archives’ bitcode cannot be read by the final link |
| Locally built archives | Not the shipped ones | A plain cargo build keeps the panic reporter. Use tools/build-libs.sh before you quote anything about a produced binary’s size |
cargo build -p axle_cli alone | Builds no archives | The compiler passes all four on every link line, and refuses to run without them. Build the workspace, or name the four crates |
| Shipping a subset of the archives | Caught by a repository check | The four archives form one set. The repository’s watchdog requires every build or packaging line that handles them to name the whole set |
What’s next
- The CLI subcommands are the same whether you installed via apt or built from source. See Install, CLI subcommands.
- The compiler’s internal architecture (the analyses it runs and the lowering it performs) is summarised in Compiler internals.
See also
- Install the compiler: the apt and Docker path for everyday use
- Hello, Axle: your first end-to-end build
- Concept index: every Axle concept on one page