Command-line reference
The axle binary is the whole toolchain. This page is the surface: one
section per subcommand, then the flags that cut across them.
axle new <NAME> [--lib | --workspace]
axle build [SOURCE] [-O LEVEL] [-o PATH] [--emit KIND]
axle run [SOURCE] [-O LEVEL] [--release] [-- ARGS]
axle check [SOURCE] [--target TRIPLE] [--deep]
axle ports [SOURCE] [--target TRIPLE]
axle fmt [FILES...] [--check] [--diff] [--json]
axle bench <SOURCE> [-O LEVEL]
axle profile [SOURCE] [-O LEVEL] [-- ARGS]
axle toolchain status [--target TRIPLE]
axle toolchain install [--target TRIPLE] [--accept-license]
axle toolchain path SOURCE is a .axle file or a directory that holds an axle.toml. Omit it,
and build, run, check and ports use the current directory. Projects and dependencies explains what a
project is.
new
axle new hello # hello/axle.toml + hello/src/main.axle
axle new mathx --lib # mathx/src/lib.axle instead: a library crate
axle new studio --workspace # studio/ (bin, the root) and studio/core (lib) NAME is the package name and the directory name. It may contain letters,
digits, _ and -, and must start with a letter or _. Any other name is
refused before a file is written. A scaffold that fails midway removes the tree
it started.
--lib and --workspace are mutually exclusive. --workspace writes a binary
crate at the root. That crate’s axle.toml also carries the [workspace] table.
It depends on a core library, so a cross-crate build works out of the box.
Build it from the root with axle build studio.
| Flag | Effect |
|---|---|
--lib | scaffold src/lib.axle (kind = "lib") instead of src/main.axle |
--workspace | scaffold a root binary with [workspace], plus a core library. Conflicts with --lib |
build
Compiles and links. A project build writes target/<name> (<name>.exe on Windows), where <name> is [package] name. A single-file build writes
the artefact beside the source, named after the file’s stem. -o overrides
either location. --emit changes the extension, for example target/<name>.ll or <stem>.o.
axle build # the project in the current directory
axle build hello # the project at a path
axle build hello.axle # a single file
axle build -O 3 -o hello # optimised, with a named output
axle build --emit llvm # stop after the LLVM pass pipeline, write the IR
axle build --incremental # skip codegen and link when nothing changed | Flag | Effect |
|---|---|
-o, --output PATH | where the artefact goes |
-O LEVEL | optimisation level, 0 to 3 (see -O LEVEL). A project build that names none follows the [profile] table; a single-file build defaults to 1 |
--release | build in release mode: [profile.release] governs, defaulting to the optimised level |
--optimize | legacy boolean shortcut for -O 2. An explicit -O beside it still wins |
--emit KIND | stop at an intermediate stage (see --emit KIND) |
--incremental | skip codegen and link on a cache hit, under .axle-cache/ |
--link-lib LIB | link a native library (repeatable), e.g. --link-lib SDL2 |
--lib-path DIR | add a directory to the native-library search path (repeatable) |
--target TRIPLE | cross-compile. Unrecognised triples are rejected before codegen |
--target-cpu CPU | tune for a named CPU (znver3, skylake, …), or native for the building machine |
--target-features F | a feature string such as +avx2,+fma |
--pie | force a position-independent executable |
--codegen-units N | how many object files to build from, concurrently (see below) |
--alloc-stats | print the program’s allocation tally to its stderr when it exits (see below) |
--timings | per-phase timings (lex, parse, sema) on stderr |
--features NAMES | turn features on in the root crate, comma-separated or repeated |
-v, --verbose | per-phase detail. -v prints the same timings as --timings |
--codegen-units defaults to a value that follows the program’s size and the
machine’s cores. A small program stays at one unit, because splitting it would
add more merging cost than it saves. 1 forces the single-module build, which
is the reference that a split build is compared against. A larger N is a
ceiling, not a command. The compiler lowers it to its own maximum of 8, and to
the number of function bodies available to split. Every non-binary --emit uses one unit regardless, because an intermediate artefact is a whole-program
artefact by definition.
--alloc-stats instruments the program, not the compiler. Every allocator call
in the linked program, stdlib bodies included, is counted. Each allocation then
costs a call and two atomics, so measure time without the flag. The runtime’s own
internal allocations are not counted: Shared<T> blocks, task argument blocks and
task stacks. See Memory placement.
run
axle run # build the project in the current directory, then run it
axle run hello.axle -- a b # run one file, passing a and b to the program A project directory and a single .axle file take the same route. axle run builds a native binary through the same link as axle build. The
runtime libraries that every program calls into are therefore present. It then
runs the binary and exits with the program’s exit code. A single file’s binary
is built in a private temporary directory, and that directory is removed
afterwards, whether the build succeeds or fails.
run takes -O, --link-lib, --lib-path, --pie, --features and the -- ARGS tail, and nothing else. The arguments after -- reach the program
verbatim, and the program reads them through std::sys::process. It inherits the
environment and the standard streams. run never uses the build cache: a
binary that is about to be executed is always built fresh.
check
axle check # analyse the project, generate nothing
axle check --target x86_64-unknown-linux-gnu
axle check --deep # also lower to LLVM IR and verify it Lexes, parses and runs sema. By default it performs no codegen and no link, which
is what keeps it fast. --target selects the port that is active, so the half of
a program written for another platform can be checked without that platform’s
toolchain. check takes --target, --features and --deep.
In a project, check answers for the plain build: it reads [profile.dev] (its target-cpu and target-features decide which vector widths a loop may ask for,
and its opt-level which transforms run), the way axle build does. It takes no --release.
--deep goes one step further after sema: it lowers the program to LLVM IR with
no optimisation and runs the module verifier, writing and linking nothing. A
program that passes sema and that code generation would refuse is reported as an
error, with a non-zero exit, instead of at your first build. The editor’s checks
and the default axle check stop at sema and do not show those.
ports
axle ports # which ports the project declares, and what each owes Prints one row per module path that crosses a port boundary, and one column per
port. It also names the file to write for each missing piece. This is the same
reading that build refuses on, so a listing that shows a port complete agrees
with the build. ports takes --target and --features. A port whose when names a feature becomes active when that feature is on. See code that differs by operating system.
fmt
axle fmt src/ # format in place
axle fmt --check src/ # list what would change, exit non-zero, write nothing
axle fmt --diff src/ # show what would change as a coloured diff, write nothing
axle fmt --json src/ # print a JSON report, write nothing With no path, fmt formats every .axle file under the current directory. The
layout comes from the [fmt] table of axle.toml when there is one. See the manifest reference. Otherwise the formatter’s defaults apply.
All three reporting modes leave every file untouched. --diff prints each
file’s would-be change as a coloured line diff and exits non-zero when any file
differs, like --check. --json prints one stable report
(schema_version first, one entry per file with its status — formatted, would_reformat, or error) for editors and CI; --json --diff adds each
file’s plain-text diff to its entry, and the exit code is non-zero while any
file would change or failed.
A construct the author fenced off with // fmt: off … // fmt: on — or
skipped alone with // fmt-ignore on the line above — is re-emitted
byte-for-byte, at item granularity: a SPIR-V table, a LUT, anything whose
bytes are load-bearing.
bench
axle bench tests/bench/x.axle
axle bench x.axle --compare cpp,rust --format json --output bench.json Runs the program repeatedly and reports timings. Every variant (each -O level, and each comparison) is built first. All of them then run in interleaved rounds: one run of each variant per round, with the starting
variant rotating round by round. A drift in the machine (boost, heat, background
work) is therefore spread over every variant. It does not read as a difference
between two of them. Times are reported as median plus or minus the median
absolute deviation.
| Flag | Default | Effect |
|---|---|---|
-O LEVEL | sweep 0 to 3 | a single level instead of the sweep |
--runs N | 30 | measured rounds (and timed builds per variant). This is the floor when --min-seconds is set |
--warmup N | 10 | untimed rounds first. Their medians calibrate --min-seconds |
--min-seconds S | none | size the round count so each variant is measured for about S seconds. The count is capped at 5000 rounds |
--compare cpp,rust,... | none | build and run other-language baselines from <stem>.cpp and <stem>.rs beside the input. A missing compiler or source is skipped with a warning |
--cpp-source FILE | none | the C++ source to compare against, wherever it lives. Implies --compare cpp |
--rust-source FILE | none | the Rust source to compare against, wherever it lives. Implies --compare rust |
--baseline AXLE | none | also build the input with another axle binary, and report the speed ratio with its 95 % interval. The report says “not significant” when the two cannot be told apart |
--build-once | off | build each variant once rather than once per round. Conflicts with --no-compile-timing |
--no-compile-timing | off | build each variant once, and leave compile times out of the report |
--pin | off | run the measured programs on one core, at raised priority |
--target-cpu CPU | the compiler’s baseline | build every Axle variant for CPU, as axle build --target-cpu does. C++ and Rust comparisons are always built for the host, so pass this flag to compare like with like |
--format text\|json | text | report format. json writes a structured report (schema_version = 2) |
--output PATH | none | write the report to a file. Only used with --format json. Without it, the report goes to stdout |
# Did a compiler change make this program faster? Old compiler vs this one:
axle bench prog.axle -O 3 --baseline old/axle.exe --build-once --pin bench is the one subcommand whose absent -O means something other than a
default. Without it, bench sweeps 0, 1, 2 and 3 in a single invocation.
profile
axle profile game.axle --top 20
axle profile game.axle -- --snap Runs a program and reports where its time and its memory went. The output is
two flamegraphs, <name>.cpu.svg and <name>.ram.svg, plus the heaviest
functions of each, with their file and line.
By default, profile instruments the build. The compiler emits entry and exit
hooks, so every frame is named, including the frames the optimiser inlined. The
result therefore moves with -O. A function whose body was inlined into its
caller has its share attributed to where the work ended up. --sample asks the
OS to sample the program instead: perf on Linux, or an ETW session on Windows.
That adds no instrumentation overhead, but only frames that still have a symbol
appear.
| Flag | Default | Effect |
|---|---|---|
-O LEVEL | 3 | optimisation level to build at. A profile of unoptimised code tells you about the compiler, not the program |
-o, --output PATH | the program’s own name | base path for the flamegraphs. -o report.svg writes report.cpu.svg and report.ram.svg |
--timeout SECS | 30 | how long the program may run before it is asked to stop |
--top N | 15 | how many functions the hot list carries |
--frequency HZ | 999 | sampling frequency. Only used with --sample |
--sample | off | ask the OS to sample, instead of instrumenting the build |
--features NAMES | none | features to enable in the root crate |
-- ARGS | none | passed to the program after -- |
A program with a main loop is ended by --timeout, or by Ctrl-C. The report is
written in either case. That is how a game is profiled, and it is not a failure
of the run.
What a profile does not cover
- The memory half is a floor. Only allocations the program itself makes are
charged to a function. Blocks the runtime allocates internally (
Shared<T>values, arenas, task stacks,asyncframes) do not appear, so a program built from them can show little memory inprofileand a lot in its resident set. - Time is the instrumented program’s. The hooks cost two clock reads and a lock per call, so the shape is real and the absolute durations are longer than the shipped program’s.
- Windows: a program stopped by
--timeoutleaves no call tree. The run is ended by terminating the process, which skips the step that writes the tree. Make the program exit on its own, or use a unix host, to get the full report. --sampleon Windows ignores--frequency, and--timeoutdoes not stop the run. On macOSprofileis unavailable.
toolchain
What a link needs on this machine. The subcommands live under toolchain and
nowhere else.
| Command | Does |
|---|---|
axle toolchain status | where the Windows system libraries come from (the AXLE_SYSROOT folder, the sysroot Axle manages, or the linker’s own search), then the result of linking a program |
axle toolchain install | downloads the Windows SDK and MSVC runtime import libraries from Microsoft into the sysroot Axle manages, after asking you to accept Microsoft’s licence (--accept-license answers for a script) |
axle toolchain path | the directory of the sysroot Axle manages, on one line |
status takes --target TRIPLE to report for another platform. It exits 1 when the probe does not link, with the build’s own diagnostic above it. Install the compiler says what a Windows machine needs and how to provide it.
-O LEVEL
| Level | What runs |
|---|---|
0 | nothing. Neither the HIR transforms nor the LLVM pipeline run, so the module reaches the backend exactly as codegen wrote it |
1 | every HIR transform, with the canonicalisation pipeline behind them: inline the stamped thunks, promote the binding allocas, fold the obvious |
2 | everything in 1, plus LLVM’s own pipeline |
3 | everything in 2, plus LLVM’s more aggressive passes |
axle build -O 0 # is an optimisation responsible for this? -O 0 is the level to build at when the question is whether an optimisation
changed behaviour. It turns off both halves, so any difference between -O 0 and -O 3 is a difference the optimiser made. The default is 1 for build and run, and 3 for profile.
Note: the value is read as a byte, and any value above
3is accepted.axle build -O 7silently builds at-O 3. Stay within0to3.
--emit KIND
--emit stops the build at an intermediate stage, and writes that stage instead
of a binary.
| Kind | What you get |
|---|---|
binary | the default: a linked executable |
ast | the parsed syntax tree (a debug dump) |
hir | Axle’s typed IR, after the sema transforms (a debug dump) |
decisions | the decision journal: what each instrumented pass concluded, and what it refused, with the missing premise for each refusal |
llvm | textual LLVM IR, after the LLVM pass pipeline |
llvm-raw | the IR exactly as codegen emitted it, before any LLVM pass |
bitcode | LLVM bitcode |
asm | target assembly text |
object | a relocatable object file, before link |
header | a C header that declares the program’s extern "C" exports |
llvm-raw against llvm is the pair to compare when deciding whether an
oddity comes from Axle or from LLVM. decisions answers why an optimisation
did not apply: a bounds check that was kept, a divisor left unhoisted, a loop
left scalar. Each entry carries the premise a reader could supply.
Exit codes
| Situation | Exit code |
|---|---|
| success | 0 |
| a user error: a diagnostic, an invalid option, a missing input | 1 |
axle run | the program’s own exit code. If the program is killed by a signal, run exits 1 and prints a message naming it |
Limits / Uncabled
| Feature | State | Detail / workaround |
|---|---|---|
run with the build cache | Not used | A binary about to run is always built fresh, so --incremental does nothing for run |
--alloc-stats and --profile-hooks | Change the program | --alloc-stats instruments every allocation. --profile-hooks (hidden, set by profile) emits entry and exit hooks. Both measure a program that is not the one you would ship, so the build cache keys on them |
-O above 3 | Accepted, treated as 3 | Use 0 to 3 |
--target-cpu and --target-features | Override the portable default | Left unset, the compiler tunes for the target triple’s baseline: x86-64-v2 on x86-64 (SSE4.2 and POPCNT, present on every x86-64 CPU since about 2009) and generic on AArch64. A binary built at -O3 therefore still runs on another machine. --target-cpu x86-64-v3 adds AVX2 and FMA, for a machine known to have them. --target-cpu native tunes for the machine doing the compiling, which suits a throwaway build and not a shipped one. A feature you name applies to the code the --target triple describes, whether or not the running machine has it |
Vector width for loops and @vectorize | Follows the target | 128-bit by default, 256-bit with AVX2, 512-bit with AVX-512. It never follows the width of the compiling machine unless you ask for native |
profile --sample | Needs an OS sampler | perf on Linux, or an ETW session on Windows. Only frames with a symbol appear |
bench --min-seconds | Capped | At most 5000 rounds, to avoid runaway loops on very short programs |
See also
- Projects and dependencies:
axle.toml, local dependencies, ports - The manifest: every table and key of
axle.toml - Install the compiler: putting
axleand LLVM onPATH - Reading compiler errors: what a diagnostic says