Axle v0.22.0

The manifest reference

axle.toml sits at a project’s root. Every table is optional except [package]. An absent key falls back to a default, not to an error. Projects and dependencies is the guided version. This page is the lookup table.

[package]
name = "smalt"
version = "0.1.0"
targets = ["x86_64-pc-windows-msvc", "x86_64-unknown-linux-gnu"]

[workspace]
members = ["app", "core"]

[dependencies]
mathx = { path = "../mathx", features = ["wayland"] }

[features]
wayland = false

[port.win32]
when = { os = "windows" }
dirs = ["win32"]

[link]
libs  = ["SDL2"]
paths = ["C:/SDL2/lib"]

[fmt]
max_line_width = 100

Table overview

TableRequiredHolds
[package]yesthe name, version, kind, entry, promised targets and the compiler-version pin
[workspace]nothe member crates compiled with this one
[dependencies]nopath dependencies, and the features they are asked to turn on
[features]nofeature names and their default state
[port.<name>]noone backend’s condition and the directories that carry it
[link]nonative libraries and their search paths
[fmt]nooverrides for axle fmt and the editor’s formatter
[profile]nowhat each build mode tunes (dev for a plain build, release for --release)

[package]

KeyTypeDefaultMeaning
namestringrequiredthe package name, and the artefact’s name in target/
versionstring""free-form. Nothing in the compiler derives behaviour from it
kind"bin" or "lib"inferredwhat the crate builds to
entrypath, relative to the projectinferredthe crate’s entry source
targetslist of triples[]the targets this project promises to serve
axleversion requirementnonethe compiler versions this package builds against, checked before any compile (see below)

kind and entry are inferred from the source layout when they are omitted:

Layoutkindentry
src/main.axle presentbinsrc/main.axle
only src/lib.axlelibsrc/lib.axle

If both files exist, the crate builds as a bin from src/main.axle. A crate that depends on it sees its library: src/lib.axle and whatever that file re-exports. It never sees the program’s main. A single package can therefore hold a program together with the library its tests import. A lib exports its pub items for dependents to import. It is never a build’s entry point.

targets is a promise, not a build setting. Listing a triple is what makes the port checks enforce it. A project that lists no triple has promised nothing, and that is what lets a port be written one module at a time. A triple the compiler does not recognise is refused, not skipped.

axle pins the compiler. Versions break weekly at the pace a young language moves, and a build against the wrong one fails somewhere unhelpful inside the compiler — so a project that needs a floor states it, and every driver that compiles (build, run, check, and the MCP server) stops with both versions named before anything parses. Three spellings say what a project means:

WrittenMeans
0.19 / 0.19.0that major.minor (any patch)
>=0.19 / >=0.19.3that version or newer
=0.19.0exactly that version

A requirement this compiler cannot read is an error, not a pass — a pin that silently accepts anything pins nothing.

[workspace]

KeyTypeDefaultMeaning
memberslist of directories[]crates compiled alongside this one

A manifest that carries [workspace] is both a crate and the root of a workspace. Members are extra graph roots, and they are compiled whether or not the root depends on them. Cross-crate use edges still come from each crate’s own [dependencies]. [workspace] members decides what is built, never what is visible.

[dependencies]

[dependencies]
mathx = { path = "../mathx", features = ["wayland"] }
KeyTypeDefaultMeaning
pathpath, relative to this manifestrequiredthe dependency’s directory
featureslist of names[]features to turn on in that dependency

Only path dependencies exist. There is no registry, no git source, and no lockfile.

features only ever enables. That is what makes the request safe to combine. Two crates that ask for different features of one library both get theirs, in any order, and neither takes anything away from the other. A feature that the dependency defaults to on is that crate’s own decision about itself.

Note: a misspelled key inside one [dependencies] entry is not refused. The entry is matched against an open set of dependency shapes, so the compiler cannot name the key. The parser reports “no known shape matches” instead.

[features]

[features]
wayland = false

Each entry is a feature name and its default state. Two things turn a feature on: its default here, or a request. A request is --features on the command line, for the root crate, or a [dependencies] edge for any other crate. Nothing turns a feature off.

A name that a [port]’s when asks for, but that this table never declares, is refused. That feature could never be on, so the port could never apply.

--features reaches the root crate and stops there. Two crates may spell the same feature name while meaning different things.

[port.<name>]

A port is one backend of a piece of code. It has a condition and the directories that carry it. Nothing is reserved. A crate with no [port] table has no port directories, so a probes/linux/ directory is an ordinary directory.

KeyTypeDefaultMeaning
whentable{} (applies everywhere)the condition under which this port is the active one
dirslist of directory namesrequired, non-emptythis port’s code, at any depth under src/

A port with no directory is refused, because nothing could ever select it.

The when axes

AxisValues
oswindows, linux, macos
archx86_64, aarch64
featureany name declared in [features]

Every axis takes one value, or a list of values:

when = { os = "linux" }
when = { os = ["linux", "macos"] }
when = { os = "linux", feature = "wayland" }

Several axes in one when must all hold. A value that no axis has is refused, and the error lists the valid ones. A feature that no [features] table declares is refused too. The alternative would be a port that is silently never active.

{ os = "linux", feature = "wayland" } is narrower than { os = "linux" }. It wins when the feature is on, and the plain Linux port serves when it is off.

Exactly one port is active for any target. A target left uncovered is refused. So are two ports that both apply when neither is narrower. The compiler does not resolve either case by declaration order.

  target: x86_64-unknown-linux-gnu, feature "wayland" off

  [port.x11]     when = { os = "linux" }                 applies, wide
  [port.wayland] when = { os = "linux", feature = "wayland" }   does not apply

  active port: x11
KeyTypeDefaultMeaning
libslist of names[]native libraries to link
pathslist of directories[]where to find them

On Windows these become /DEFAULTLIB:<name>.lib and /LIBPATH:<dir>. On Unix they become -l<name> and -L<dir>. The command-line flags extend the same lists for one build: axle build --link-lib SDL2 --lib-path C:/SDL2/lib.

[fmt]

These are overrides for axle fmt and for the language server’s formatter. Every key is optional. An absent key uses the formatter’s default.

KeyTypeMeaning
max_line_widthintegerwidth before a breakable construct wraps
indent_widthintegercolumns of indentation per nesting level
use_tabsboolindent with hard tabs instead of spaces
brace_on_same_lineboolkeep { on the construct’s line, or move it down
trailing_commabooltrailing comma on a broken brace-delimited list
max_blank_linesintegerblank lines preserved between items
single_line_if_max_widthintegercolumn ceiling under which a single-statement if with no else stays on one line. 0 disables the rule
use_sort"layers" or "none"how use lines are ordered: "layers" (the default) groups them stdlib first, then external packages, then this project’s other crates, then this crate, lexicographically within a layer, with a blank line between layers; "none" keeps the author’s order

A use run the author’s comments touch is never reordered — moving a remark onto a statement it was not written about is damage, not formatting.

[profile]

What each build mode tunes. [profile.dev] governs a plain axle build, [profile.release] a --release one (the flag exists on build and run). An explicit -O on the command line wins over either.

[profile.dev]
opt-level = 0

[profile.release]
opt-level = 3
target-cpu = "x86-64-v3"
KeyTypeDefaultMeaning
opt-levelinteger 0–31 for dev, 3 for releasethe optimisation level a build in this mode compiles at when the command line named none; a higher value saturates to 3, as -O does
target-cpustringthe target’s portable baselinethe CPU the build tunes for, as --target-cpu spells it; the flag wins over it
target-featuresstringnonethe feature string handed to LLVM ("+avx2,+fma"), as --target-features spells it; the flag wins over it

The portable baseline leaves instruction sets such as AVX2 and FMA unused, so a numeric project gains by naming a CPU. native tunes for the machine that compiles: write it in [profile.dev], not in the profile of a binary that ships to other machines. A CPU with FMA also lets the compiler fuse a multiply and an add into one rounding, so two builds for different CPUs may differ in the last bits of a float result.

The plain-build default is 1: every HIR transform, with only LLVM’s canonicalisation pipeline behind them. -O 0 is the level to compile at when the question is whether an optimisation is responsible for something, and a project that ships optimised writes the release level once, here, instead of remembering -O 3 on every invocation.

Unknown keys and tables

A misspelled key inside [package], [workspace], [link], [fmt], [profile] and its mode sections, [port.<name>] or its when table is refused, and the error names the key. An unrefused typo would show up only as a setting that has no effect. A misspelled when would leave the condition empty, so the port would apply to every target. A misspelled max_line_width would leave a formatter rule that never fires.

A whole table that this parser does not know is left alone, not refused. A manifest written for a newer compiler, one that declares a table this compiler does not know, therefore still reads with this one. The one other exception is a key inside a [dependencies] entry, described above.

Limits / Uncabled

FeatureStateDetail / workaround
Registry and git dependenciesNot providedOnly path dependencies exist. Vendor the source as a directory and point path at it
LockfileNot providedDependencies are the directories that path names
Turning a feature offNot providedfeatures only enables. A feature a dependency defaults to on stays on
Other linker options in [link]Not providedOnly libs and paths exist. The build’s command-line flags add libraries and directories (--link-lib, --lib-path) and nothing else
Two ports applying to one target, neither narrowerRefusedNarrow one of the two when tables with a feature or an arch axis

See also

manifestaxle-tomlreferenceprojectsports