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
| Table | Required | Holds |
|---|---|---|
[package] | yes | the name, version, kind, entry, promised targets and the compiler-version pin |
[workspace] | no | the member crates compiled with this one |
[dependencies] | no | path dependencies, and the features they are asked to turn on |
[features] | no | feature names and their default state |
[port.<name>] | no | one backend’s condition and the directories that carry it |
[link] | no | native libraries and their search paths |
[fmt] | no | overrides for axle fmt and the editor’s formatter |
[profile] | no | what each build mode tunes (dev for a plain build, release for --release) |
[package]
| Key | Type | Default | Meaning |
|---|---|---|---|
name | string | required | the package name, and the artefact’s name in target/ |
version | string | "" | free-form. Nothing in the compiler derives behaviour from it |
kind | "bin" or "lib" | inferred | what the crate builds to |
entry | path, relative to the project | inferred | the crate’s entry source |
targets | list of triples | [] | the targets this project promises to serve |
axle | version requirement | none | the 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:
| Layout | kind | entry |
|---|---|---|
src/main.axle present | bin | src/main.axle |
only src/lib.axle | lib | src/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:
| Written | Means |
|---|---|
0.19 / 0.19.0 | that major.minor (any patch) |
>=0.19 / >=0.19.3 | that version or newer |
=0.19.0 | exactly that version |
A requirement this compiler cannot read is an error, not a pass — a pin that silently accepts anything pins nothing.
[workspace]
| Key | Type | Default | Meaning |
|---|---|---|---|
members | list 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"] } | Key | Type | Default | Meaning |
|---|---|---|---|
path | path, relative to this manifest | required | the dependency’s directory |
features | list 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.
| Key | Type | Default | Meaning |
|---|---|---|---|
when | table | {} (applies everywhere) | the condition under which this port is the active one |
dirs | list of directory names | required, non-empty | this port’s code, at any depth under src/ |
A port with no directory is refused, because nothing could ever select it.
The when axes
| Axis | Values |
|---|---|
os | windows, linux, macos |
arch | x86_64, aarch64 |
feature | any 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 [link]
| Key | Type | Default | Meaning |
|---|---|---|---|
libs | list of names | [] | native libraries to link |
paths | list 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.
| Key | Type | Meaning |
|---|---|---|
max_line_width | integer | width before a breakable construct wraps |
indent_width | integer | columns of indentation per nesting level |
use_tabs | bool | indent with hard tabs instead of spaces |
brace_on_same_line | bool | keep { on the construct’s line, or move it down |
trailing_comma | bool | trailing comma on a broken brace-delimited list |
max_blank_lines | integer | blank lines preserved between items |
single_line_if_max_width | integer | column 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" | Key | Type | Default | Meaning |
|---|---|---|---|
opt-level | integer 0–3 | 1 for dev, 3 for release | the 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-cpu | string | the target’s portable baseline | the CPU the build tunes for, as --target-cpu spells it; the flag wins over it |
target-features | string | none | the 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
| Feature | State | Detail / workaround |
|---|---|---|
| Registry and git dependencies | Not provided | Only path dependencies exist. Vendor the source as a directory and point path at it |
| Lockfile | Not provided | Dependencies are the directories that path names |
| Turning a feature off | Not provided | features only enables. A feature a dependency defaults to on stays on |
Other linker options in [link] | Not provided | Only 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 narrower | Refused | Narrow one of the two when tables with a feature or an arch axis |
See also
- Projects and dependencies: dependencies, ports and the checks around them, by example
- Command-line reference: the flags that override these tables