Axle v0.22.0

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 build does 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

FeatureStateDetail / workaround
Two toolchainsBy designrust-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 archivesNot the shipped onesA 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 aloneBuilds no archivesThe 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 archivesCaught by a repository checkThe 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

buildfrom-sourcellvmcontributing