Axle v0.22.0

Install the compiler

The fast path is a pre-built axle binary. Install it from the project’s apt repository (Debian and Ubuntu), or from its Windows MSI. Or build the container below and run axle inside it. If you want to work on the compiler itself, see Build the compiler instead.

This page covers:

  • the apt repository setup, and what apt pulls in alongside axle;
  • the Windows MSI, and what to do on macOS or arm64 Linux;
  • a Dockerfile for a reproducible Linux environment;
  • the CLI subcommand surface, and the flags worth knowing early.

Debian / Ubuntu (apt)

The repository setup is scripted:

curl -fsSL https://axle-lang.dev/install.sh | sh

Or do it by hand:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://apt.axle-lang.dev/key.asc \
    | sudo gpg --dearmor -o /etc/apt/keyrings/axle.gpg
echo "deb [signed-by=/etc/apt/keyrings/axle.gpg arch=amd64] https://apt.axle-lang.dev stable main" \
    | sudo tee /etc/apt/sources.list.d/axle.list
sudo apt update
sudo apt install axle
axle --help

The package is the compiler driver. Two tools it drives at link time come in alongside it: an LLD linker (lld, or a versioned ld.lld-25 through ld.lld-14), and a C driver (gcc or clang). LLVM itself is not installed. The compiler links LLVM into its own binary, so no llvm-* package is needed.

Attention: the exact dependency list that the .deb declares is not recorded in this repository’s packaging scripts. Check it with apt show axle before relying on a specific linker or driver package.

Updates arrive through a plain sudo apt upgrade, once the repository is configured.

Docker

A reproducible single-image build that bundles the same apt install as above:

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
        ca-certificates curl gnupg lld-14 \
    && rm -rf /var/lib/apt/lists/*

RUN install -m 0755 -d /etc/apt/keyrings \
 && curl -fsSL https://apt.axle-lang.dev/key.asc \
      | gpg --dearmor -o /etc/apt/keyrings/axle.gpg \
 && echo "deb [signed-by=/etc/apt/keyrings/axle.gpg arch=amd64] https://apt.axle-lang.dev stable main" \
      > /etc/apt/sources.list.d/axle.list \
 && apt-get update \
 && apt-get install -y hyperfine time \
 && apt-get install -y axle \
 && rm -rf /var/lib/apt/lists/* \
 && axle --version

WORKDIR /work
ENTRYPOINT ["axle"]
CMD ["--version"]

Build the image, then use it:

docker build -t axle .
docker run --rm -v "$PWD":/work axle build hello.axle -o hello

The hyperfine and time packages are pre-installed in this image, so you can benchmark from inside the container without rebuilding it.

Windows

The release pipeline publishes an x86_64 MSI, from the download page:

https://dl.axle-lang.dev/latest/axle-windows-x86_64.msi

The installer places seven files in C:\Program Files\Axle:

FileRole
axle.exethe compiler and its subcommands
axle-lsp.exethe language server, for editors
axle-toolchain.exedownloads the Windows system libraries; run through axle toolchain install
axle_stdlib.lib, axle_runtime.lib, axle_tls.lib, axle_reactor.libthe four runtime static libraries that every program links against

The installer is unsigned, so SmartScreen warns on first run.

What a Windows machine needs besides the installer

Axle links every program itself, with no separate linker to install. A Windows program also imports from the operating system and the C runtime through a handful of import libraries (kernel32.lib, ucrt.lib, msvcrt.lib and seven more), and those belong to Microsoft’s Windows SDK and MSVC toolset: no Axle installer carries them. A machine gets them one of two ways.

You haveWhat to do
Visual Studio, or the Build Tools, with Desktop development with C++Nothing: the linker finds them
NeitherRun axle toolchain install
> axle toolchain install
The Windows SDK and MSVC runtime libraries are Microsoft's, downloaded from
Microsoft's servers under the licence at:
  https://go.microsoft.com/fwlink/?LinkId=2086102
Do you accept it? (yes / no) yes

It downloads only the libraries a link reads, for your architecture, and puts them in a folder of your user profile. Nothing else is installed, and no administrator right is needed. In a script, --accept-license answers the question.

axle toolchain status says which of these a machine has, and proves it by linking a program:

> axle toolchain status
Target x86_64-pc-windows-msvc
  AXLE_SYSROOT sysroot: not set
  Axle sysroot: nothing at C:\Users\you\AppData\Local\Axle\toolchains\windows-msvc
Served by the linker's own search (%LIB%, then an installed Visual Studio)
Link probe ok

On a machine with neither, a build stops with the list of what is missing and the two ways out, instead of a linker message about a file you never named.

axle toolchain path prints where that folder is. To use one you prepared yourself — on a build server, or to pin a version — name it with AXLE_SYSROOT: a folder laid out as crt/lib/x86_64, sdk/lib/um/x86_64 and sdk/lib/ucrt/x86_64, which is what the xwin splat tool writes.

macOS and arm64 Linux

There is no native package on either platform. The apt repository serves x86-64 Linux only, and no macOS artefact is published. You have two options:

  • Docker: use the Dockerfile above. The --rm -v "$PWD":/work invocation works the same under Docker Desktop or Colima.
  • Build from source: follow Build the compiler. It pins the Rust toolchain and LLVM 21 that the compiler needs.

CLI subcommands

axle new    <name>          Create a new project (manifest + src/main.axle);
                            --lib scaffolds a library, --workspace a
                            multi-crate workspace (the two are exclusive)
axle build  [input]         Compile a file or project to a native binary
axle run    [input]         Compile and run a file or project
axle check  [input]         Type-check only, no binary produced.
                            A directory (or nothing) checks that project;
                            --target checks another platform's port;
                            --deep also lowers to verified LLVM IR.
axle ports  [dir]           List a project's ports, its seams, and what
                            each port still owes (--target to switch)
axle fmt    [files]         Format .axle sources in place (--check to verify)
axle bench  <input>         Compile and benchmark (with --compare cpp,rust)
axle profile [input]        Run the program and report where its time went
axle toolchain status       Where the system libraries of a link come from on
                            this machine, then a link to prove it
axle toolchain install      Download the Windows system libraries a machine
                            without Visual Studio lacks
axle toolchain path         The directory of the sysroot Axle manages

axle <subcommand> --help lists every option. axle build takes --emit with ten kinds: binary (the default), llvm, llvm-raw, bitcode, asm, object, hir, ast, header and decisions. It also takes -O 0 through -O 3, and --target <triple> for cross-compilation. object and header are the pair that make a library something C can link against. See Exporting to C.

A binary build lowers the program into several object files and builds them concurrently. The number follows the program’s size and the machine’s core count. --codegen-units N pins it, and 1 gives the single-module build. Only the binary path splits. Every other --emit produces one file and one module.

The optimisation levels are not a single LLVM dial:

LevelWhat runs
-O 0nothing. Neither the HIR transforms nor the LLVM pipeline run. Use it to test whether an optimisation is responsible for something
-O 1 (default)every HIR transform, with only the canonicalisation pipeline behind them
-O 2 and -O 3everything in -O 1, plus LLVM’s own pipeline (-O 3 adds its more aggressive passes)

axle run builds a native binary and then executes it. This works for a bare .axle file as well as for a project directory. axle build performs the same build and keeps the binary.

Limits / Uncabled

FeatureStateDetail / workaround
apt repository for arm64 Linux or macOSNot publishedThe repository’s sources line is pinned to arch=amd64. Use the Dockerfile above, or build from source
Windows through aptNot publishedWindows gets its x86_64 MSI from the download page
A published container image to runNot publishedThe project pushes its CI base image to a registry. That image is not a distribution of the compiler. Build the Dockerfile above with docker build. There is nothing to docker pull
Dependency list of the .debNot verifiable from this repositoryRun apt show axle to read what the installed package declares

What’s next

See also

  • Build the compiler: if you want to work on the compiler itself, instead of using a pre-built binary.
  • Concept index: every Axle concept on one page, with a link to where it is documented.
  • Recipes: task-oriented examples, once the toolchain works.
installsetupaptdockerwindows