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
.debdeclares is not recorded in this repository’s packaging scripts. Check it withapt show axlebefore 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:
| File | Role |
|---|---|
axle.exe | the compiler and its subcommands |
axle-lsp.exe | the language server, for editors |
axle-toolchain.exe | downloads the Windows system libraries; run through axle toolchain install |
axle_stdlib.lib, axle_runtime.lib, axle_tls.lib, axle_reactor.lib | the 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 have | What to do |
|---|---|
| Visual Studio, or the Build Tools, with Desktop development with C++ | Nothing: the linker finds them |
| Neither | Run 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":/workinvocation 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:
| Level | What runs |
|---|---|
-O 0 | nothing. 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 3 | everything 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
| Feature | State | Detail / workaround |
|---|---|---|
| apt repository for arm64 Linux or macOS | Not published | The repository’s sources line is pinned to arch=amd64. Use the Dockerfile above, or build from source |
| Windows through apt | Not published | Windows gets its x86_64 MSI from the download page |
| A published container image to run | Not published | The 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 .deb | Not verifiable from this repository | Run apt show axle to read what the installed package declares |
What’s next
- Write your first program: Hello, Axle.
- Wire up your editor: Editor support covers the VS Code
extension, and how to drive
axle-lspfrom other LSP-aware editors. - Browse the language tour.
- When you need a specific stdlib symbol, see the API reference.
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.