Axle v0.22.0

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.

FlagEffect
--libscaffold src/lib.axle (kind = "lib") instead of src/main.axle
--workspacescaffold 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
FlagEffect
-o, --output PATHwhere the artefact goes
-O LEVELoptimisation level, 0 to 3 (see -O LEVEL). A project build that names none follows the [profile] table; a single-file build defaults to 1
--releasebuild in release mode: [profile.release] governs, defaulting to the optimised level
--optimizelegacy boolean shortcut for -O 2. An explicit -O beside it still wins
--emit KINDstop at an intermediate stage (see --emit KIND)
--incrementalskip codegen and link on a cache hit, under .axle-cache/
--link-lib LIBlink a native library (repeatable), e.g. --link-lib SDL2
--lib-path DIRadd a directory to the native-library search path (repeatable)
--target TRIPLEcross-compile. Unrecognised triples are rejected before codegen
--target-cpu CPUtune for a named CPU (znver3, skylake, …), or native for the building machine
--target-features Fa feature string such as +avx2,+fma
--pieforce a position-independent executable
--codegen-units Nhow many object files to build from, concurrently (see below)
--alloc-statsprint the program’s allocation tally to its stderr when it exits (see below)
--timingsper-phase timings (lex, parse, sema) on stderr
--features NAMESturn features on in the root crate, comma-separated or repeated
-v, --verboseper-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.

FlagDefaultEffect
-O LEVELsweep 0 to 3a single level instead of the sweep
--runs N30measured rounds (and timed builds per variant). This is the floor when --min-seconds is set
--warmup N10untimed rounds first. Their medians calibrate --min-seconds
--min-seconds Snonesize the round count so each variant is measured for about S seconds. The count is capped at 5000 rounds
--compare cpp,rust,...nonebuild 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 FILEnonethe C++ source to compare against, wherever it lives. Implies --compare cpp
--rust-source FILEnonethe Rust source to compare against, wherever it lives. Implies --compare rust
--baseline AXLEnonealso 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-onceoffbuild each variant once rather than once per round. Conflicts with --no-compile-timing
--no-compile-timingoffbuild each variant once, and leave compile times out of the report
--pinoffrun the measured programs on one core, at raised priority
--target-cpu CPUthe compiler’s baselinebuild 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\|jsontextreport format. json writes a structured report (schema_version = 2)
--output PATHnonewrite 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.

FlagDefaultEffect
-O LEVEL3optimisation level to build at. A profile of unoptimised code tells you about the compiler, not the program
-o, --output PATHthe program’s own namebase path for the flamegraphs. -o report.svg writes report.cpu.svg and report.ram.svg
--timeout SECS30how long the program may run before it is asked to stop
--top N15how many functions the hot list carries
--frequency HZ999sampling frequency. Only used with --sample
--sampleoffask the OS to sample, instead of instrumenting the build
--features NAMESnonefeatures to enable in the root crate
-- ARGSnonepassed 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, async frames) do not appear, so a program built from them can show little memory in profile and 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 --timeout leaves 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.
  • --sample on Windows ignores --frequency, and --timeout does not stop the run. On macOS profile is unavailable.

toolchain

What a link needs on this machine. The subcommands live under toolchain and nowhere else.

CommandDoes
axle toolchain statuswhere 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 installdownloads 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 paththe 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

LevelWhat runs
0nothing. Neither the HIR transforms nor the LLVM pipeline run, so the module reaches the backend exactly as codegen wrote it
1every HIR transform, with the canonicalisation pipeline behind them: inline the stamped thunks, promote the binding allocas, fold the obvious
2everything in 1, plus LLVM’s own pipeline
3everything 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 3 is accepted. axle build -O 7 silently builds at -O 3. Stay within 0 to 3.

--emit KIND

--emit stops the build at an intermediate stage, and writes that stage instead of a binary.

KindWhat you get
binarythe default: a linked executable
astthe parsed syntax tree (a debug dump)
hirAxle’s typed IR, after the sema transforms (a debug dump)
decisionsthe decision journal: what each instrumented pass concluded, and what it refused, with the missing premise for each refusal
llvmtextual LLVM IR, after the LLVM pass pipeline
llvm-rawthe IR exactly as codegen emitted it, before any LLVM pass
bitcodeLLVM bitcode
asmtarget assembly text
objecta relocatable object file, before link
headera 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

SituationExit code
success0
a user error: a diagnostic, an invalid option, a missing input1
axle runthe program’s own exit code. If the program is killed by a signal, run exits 1 and prints a message naming it

Limits / Uncabled

FeatureStateDetail / workaround
run with the build cacheNot usedA binary about to run is always built fresh, so --incremental does nothing for run
--alloc-stats and --profile-hooksChange 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 3Accepted, treated as 3Use 0 to 3
--target-cpu and --target-featuresOverride the portable defaultLeft 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 @vectorizeFollows the target128-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 --sampleNeeds an OS samplerperf on Linux, or an ETW session on Windows. Only frames with a symbol appear
bench --min-secondsCappedAt most 5000 rounds, to avoid runaway loops on very short programs

See also

clireferencebuildtooling