Manifest

mach.toml declares a project. It separates the orthogonal axes of a build - what is produced ([artifact.*]), where it runs ([target.*]), how it is compiled ([profile.*]), and what it links or must run first ([link.*], [step.*]) - and the build engine takes their product. Nothing is inferred from another key.

The schema

[project]
id      = "demo"                       # required: identifier; root of every module path
version = "0.1.0"                      # required
src     = "src"                        # required: source dir, project-root-relative
out     = "out/{target.name}/{profile.name}"  # required: output-path template root
mach    = "^6.0"                       # required in a root manifest: the compiler range

[target.linux]                        # a platform: a fully-spelled tuple
default = true
isa = "x86_64"
os  = "linux"
abi = "sysv64"

[profile.debug]                       # a build variant: requires all five keys
default       = true
opt           = 0                     # 0 (debug pipeline) | 1 | 2 (release pipeline)
debug         = true                  # emit debug info for this profile
simd          = "scalarize"          # SIMD lever: "scalarize" | "require"
vectorize     = true                  # auto-vectorization lever
float_reassoc = false                 # associative float transforms

[artifact.demo]                       # a produced artifact
default = true
kind    = "bin"                       # "bin" | "static" | "shared"
entry   = "root.mach"                 # entry source, relative to src
out     = "bin/demo"                  # output path, relative to the project out
targets = ["*"]                        # which declared targets build it ("*" = all)
link    = []                          # [link.X] names this artifact links
need    = []                          # category-qualified names demanded directly

[dep.std]                             # a dependency: directory, manifest key, and id match
git     = "https://github.com/briar-systems/mach-std"
version = "^9.0"                    # a release range, or ref = "tag/..." for one exact selection

[project]

The output directory

Everything a build and its cache write lands under the expanded out, in one layout:

Test objects sit in obj/ beside the module objects, as obj/<project>/<module>.test.o. Artifact outputs go wherever their own out names under the directory.

mach build and mach test read obj/ as the object cache by default. Each module has its own key, so an edit rebuilds only that module and the modules whose view of it changed, and a warm build links the same binary a cold one does. An object that is missing or carries another key is rebuilt, never linked stale. --no-cache forces an uncached build.

mach clean removes obj/, ir/, asm/, .cache/, .stage/, test/, and dep/ along with every artifact output, for every declared target and profile, so the build after it is a cold one that reuses nothing. A step output may not name a path inside obj/<project.id>/, .cache/, or .stage/.

Compiler range

mach states which compilers a project builds with. Every command that reads the dependency closure - build, test, check, mach dep verify, and the language server - checks it for the root and for every realized dependency. A compiler outside any of those ranges is refused once, with every unmet requirement and the chain that states it:

error: this is mach 5.2.1, and the dependency closure does not accept it:
    app (mach.toml) requires mach ^5.3
    app -> gfx -> glfw requires mach >=5.4, <6

A root manifest must state mach. One without it is refused, with the line to add. A dependency without it states no constraint. mach init writes the oldest release of the running compiler's major that reads the key: mach = "^6.0" for every 6.x compiler. Dependency resolution also reads it: a release whose mach range excludes the running compiler is never selected.

The compiler's version is the last release it was built from. A build from an unreleased tree reports that release, so a project cannot require an unreleased feature by version.

Targets

Each <name> in [target.<name>] is a selector you pass to -t <name>. A target is a fully-spelled platform tuple; nothing is inferred from another key.

Accepted tuple values

A value outside its axis set is a strict-parse error, so a typo is caught rather than silently never matching. mach info targets prints the tuples this binary can actually build. It is derived from the same declarations composition reads, so it never advertises a tuple that would fail to resolve.

Each os has a default object format: linux to elf, windows to coff, darwin to macho, freestanding to raw, and of names a different one. An os accepts only the formats it can load, so an override the os cannot enter is refused. The default is a function of the whole tuple, not the os alone: a spirv target resolves to spv regardless of the os it names.

A freestanding target can select of = "elf" on every architecture, and gets an image with no loader construct in it: no header segment, since nothing parses a program header at run time on bare metal.

[target.metal]
isa = "x86_64"
os  = "freestanding"   # os default object format is "raw"
abi = "sysv64"
of  = "elf"            # override: emit an ELF image instead

--pie, dynamic linking, and a shared library are each refused by name on a loaderless os: a position-independent executable exists to be relocated by a program loader, a dynamically-linked one to have its imports resolved by one, and os = "freestanding" has none.

Finished-module targets

A spirv target's object output is a complete, self-contained module rather than a link input. The build delivers the module tree - one <out>/obj/<fqn-as-path>.spv per module - and runs no link phase, so a default build and --emit obj produce the same files.

[target.gpu]
isa = "spirv"
os  = "freestanding"
abi = "spirv"
# no `of`: the finished-module format resolves on its own

The artifact's out template and -o name a linked binary, which such a target has none of; the module tree is delivered instead. A static or shared artifact kind, and mach test, are refused by name.

Platform targets (bare metal)

A bare-metal platform is not its own os. It is os = "freestanding" plus two optional keys: a base load-address override, and an open platform tag a support library keys its backend on.

[target.bmos]
isa      = "x86_64"
os       = "freestanding"
abi      = "sysv64"
of       = "raw"
base     = 0xFFFF800000000000
platform = "bmos"

Artifacts

Every artifact is declared explicitly and named by its table key. $bin.name reads the selected artifact name.

• bin links an executable at the resolved out path.
• static materialises a real ar archive at the resolved out path: the per-module objects with an archive symbol index, the deliverable a consumer links as a .a.
• shared links a shared object at the resolved out path, on ELF targets only. Mach-O and PE targets are refused with link: object format cannot write shared libraries: dylib and DLL output is not implemented yet and is tracked in mach#3588. The library exports the root project's pub declarations and the names its modules re-export with fwd. A dependency's pub surface is not part of its ABI, and #[symbol] chooses a name, not a visibility. Every other definition still resolves inside the link but is not exported: it is a local symbol in the library's .symtab and absent from .dynsym. A shared artifact that exports nothing is refused. A freestanding target is refused at artifact naming (this object format has no shared-library form), or, with of = "elf", at link time because it has no loader.

Per-target extension or per-target entry is not a per-cell exception table. It is a second artifact stanza, so the condition stays visible like everything else.

Windows subsystem and resources

A PE executable records in its optional header which environment it wants, and the Windows loader honours it: "console" gets a console window attached to the process, "gui" does not. A graphical application sets "gui" to stop an empty console from opening behind it on launch. --subsystem console|gui overrides the key for one invocation.

[artifact.game]
kind      = "bin"
entry     = "root.mach"
out       = "bin/game.exe"
targets   = ["*"]
link      = []
need      = []
subsystem = "gui"
icon      = "assets/game.ico"
manifest  = "assets/game.manifest"

Only a PE image carries the subsystem field. A key written on an artifact planned for a target whose format has none (ELF, Mach-O, raw) is refused as unsupported, naming the key, the target, and the format. An omitted key is the console default and is never refused, so an artifact declaring no subsystem still builds everywhere. Resource keys like icon and manifest remain valid in a multi-target artifact, but are inert off Windows where Mach does not read either path.

Profiles

A [profile.<name>] is a build variant. The optimization level, debug toggle, and SIMD levers live here because they are variant concerns.

All five keys (opt, debug, simd, vectorize, float_reassoc) are required in a declared root profile. Emission of the human-readable IR and assembly side-artifacts is not a profile concern. It is controlled only by the --emit-ir and --emit-asm CLI flags.

Link requirements

A [link.<name>] is a named external link requirement. Artifacts reference entries by name in their link = [...], and an entry whose filters do not match the build cell is skipped. An entry with export = true also applies to any project that links this project's modules, so a platform link requirement lives once in the manifest that needs it and cascades to consumers.

[link.kernel32]
source  = "system"
name    = "kernel32.dll"
library = "kernel32"
symbols = ["Sleep", "CreateFileW", "CloseHandle"]
os      = "windows"
isa     = "*"
abi     = "*"
export  = true

library decouples source attribution from platform loader spelling. Give mutually exclusive platform entries the same logical value when they provide the same API; one unconditional #[library("glfw")] can then bind against libglfw.so.3 on Linux, an install name on Darwin, and glfw3.dll on Windows.

symbols names the symbols the dependency provides. On a two-level-namespace format (PE, Mach-O) every import must identify its provider, and #[library] can only attribute a symbol your Mach source declares. A vendored static archive leaves its own undefined references with no declaration to decorate, so the entry that provides them claims them. A symbol may be claimed only once per link.

Whether an input links statically or dynamically follows the resolved file: a loose .o / .obj or static .a / .lib links statically, while ELF .so, Mach-O .dylib, and PE .dll inputs are recorded using their format canonical loader name.

Build steps

A [step.<name>] is a command, make-recipe style, that produces files a build consumes, typically a local link input such as a vendored-C object.

Steps carry no filters and never run automatically. A step runs only when demanded: by a selected [link.X] whose local path matches the step's out, by another step's need, or by an artifact's need. Because a step has no filter of its own, the condition for running it lives in the link entry that demands it.

A step is cached by content: its declared inputs, resolved executable, expanded arguments, and effective environment contribute to its fingerprint. An unchanged step whose outputs still exist is skipped. The fingerprint of the last successful run is kept as a stamp in {project.out}/.cache/steps/, and a step's outputs under {project.out} are written into scratch space in {project.out}/.stage/<name>/ and published only once the step succeeds. A declared out inside .cache/ or .stage/ fails at manifest load. Every step process inherits the active build cell target tuple as MACH_TARGET_ISA, MACH_TARGET_OS, and MACH_TARGET_ABI.

Dependencies

Each [dep.<id>] names a dependency realized under dep/<id>/. The key, the directory, and the dependency's own [project].id are one name. The build resolves a dependency purely by vendor layout: it reads that directory's own mach.toml for its [project].id and src. A module path whose head matches a dep id resolves into that dep tree. A stanza declares exactly one source, git or path, and a git stanza exactly one selector, version or ref.

Pins are the gitlinks committed in the root repository, and there is no lock file. mach dep pull <path> realizes the whole transitive closure flat at dep/<id>/, one level deep. Builds never fetch or resolve. They check offline that every checkout is clean at its pin, that each version-selected pin is a release inside every requirer's range, and that every mach range in the closure accepts the compiler.

Bare project-id imports

A module path whose head segment matches a declared dependency's [project].id resolves into that dependency's source tree. The directory under dep/ and the id match what source code writes.

Path templates

Paths and argv arguments expand over a closed, final set of eight variables:

An artifact's out is relative to the expanded project out and is rooted there automatically. Step out lists and local link paths are not auto-rooted: they name {project.out} explicitly, which is what homes a dependency's build products into the consumer's output tree rather than the dependency's checkout.

The build matrix

A build cell is one artifact times one target times one profile.

• Cells are selected with -a/--artifact, -t/--target and -p/--profile, one per axis. Each takes an exact name, which must be declared, or a glob with * and ?, which must match, and repeats. --all fills every axis no option names with *: mach build . --all builds every artifact on every target it supports in every profile, and mach test . --all -p debug does the same in debug only.
• An axis no option names, without --all, takes the manifest's default: the native target (or the one a named artifact settles), the sole profile or the one marked default = true, and the default selection of artifacts, those marked default = true for the target when any is marked and every one of them when none is. No default is chosen by table order.
• mach build <path> and mach check <path> take the whole default selection. mach test <path> takes it when it holds one artifact, and mach run <path> takes the sole bin the target builds; with several candidates and none marked, they refuse, naming every candidate.
• A cell whose artifact does not list the cell's target is a cell the manifest never declared, so a glob that reaches it skips it. Naming that pair exactly (-a kernel -t linux-x86_64) is a different act and is refused by name, because you asked for a cell that does not exist.
• Every cell is attempted; a failure does not abandon the ones after it. Each cell's diagnostics are reported under its own heading, and every cell that succeeded leaves its artifact on disk.
• -o is accepted exactly when the selection resolves to a single build cell, and refused otherwise, naming the cells it resolved to.

Artifacts cannot share an output path: a manifest whose expanded out templates collide is rejected before the build starts.

native target resolution

native resolves the host's (isa, os) against the declared targets only, never a synthesized tuple. Exactly one host match is chosen; several matching tuples is an ambiguity error naming the candidates. With no match native is an error, raised before any step runs: a declared target that does not match the host is built only when -t names it, so a cross-only project with hosted targets selects its target with -t.

Annotated example

A project that cross-compiles to linux and windows, links a system library on each, and vendors a C object through a build step. Note where the conditions live: [step.miniz] carries no filter of its own, so it runs only because [link.miniz] demands it, and that entry is gated to os = "linux" since the host cc emits an ELF object. On the windows cell the entry filters out, the step is never demanded, and it never runs. To vendor C for the windows cell too, add a second step whose argv cross-compiles (it can branch on MACH_TARGET_OS) and a second link entry gated to os = "windows".

[project]
id      = "demo"
version = "0.1.0"
mach    = "^6.0"
src     = "src"
out     = "out/{target.name}/{profile.name}"

[target.linux]
isa     = "x86_64"
os      = "linux"
abi     = "sysv64"
default = true

[target.windows]
isa = "x86_64"
os  = "windows"
abi = "win64"

[profile.debug]
opt           = 0
debug         = true
simd          = "scalarize"
vectorize     = false
float_reassoc = false
default       = true

[profile.release]
opt           = 2
debug         = false
simd          = "scalarize"
vectorize     = true
float_reassoc = false

[step.miniz]                            # builds the vendored c object the link entry below demands
argv = ["cc", "-c", "vendor/miniz.c", "-o", "{project.out}/miniz.o"]
in   = ["vendor/miniz.c"]
out  = ["{project.out}/miniz.o"]
need = []

[link.miniz]
source = "local"
path   = "{project.out}/miniz.o"       # matches step.miniz's out, so it demands that step
os     = "linux"                     # host cc emits an ELF object, so this entry is linux-only
isa    = "*"
abi    = "*"
export = false

[link.kernel32]
source  = "system"
name    = "kernel32.dll"
os      = "windows"              # skipped on the linux cell, never a per-platform file
isa     = "*"
abi     = "*"
export  = true

[artifact.demo]
kind    = "bin"
entry   = "root.mach"
out     = "bin/demo{artifact.suffix}"
targets = ["*"]
link    = ["miniz", "kernel32"]
need    = []

[dep.std]
git     = "https://github.com/briar-systems/mach-std"
version = "^9.0"