Configurations
A target's behavior can vary by configuration: which platform it targets, which dependencies it pulls in, or which build mode it uses. Once keeps the declared graph static while letting its configured projection change between invocations. The same target identifier can resolve to different dependencies and actions without editing the manifest.
Configuration plays two roles. It selects which branch of a select value a
target uses, and it feeds target-kind analysis with the platform and tokens
the target runs against. The effective configuration is also part of a
target's identity, so two invocations with different configurations never
share outputs or receipts: each lands in its own scoped output directory and
its own action-cache partition.
Declare workspace defaults#
The workspace root manifest fixes the default configuration every invocation starts from:
[workspace.configuration]
os = "linux"
arch = "arm64"
tokens = ["release"]
Once normalizes common names (darwin to macos, arm64 to aarch64,
amd64 to x86_64) and derives an ordered set of selection tokens from the
operating system and architecture, then appends the extra tokens and
default. Inspect the resolved set with once query workspace. The
manifest reference describes the table and
normalization in full.
Override per invocation#
Pass --config KEY=VALUE to once build, once lint, once run, or
once test to override the workspace defaults for a single invocation.
Recognized keys are os, arch, and token:
once build apps/Support --config os=ios --config arch=arm64
once build apps/Support --config token=simulator
os and arch replace the workspace values; each token is appended to the
selection tokens. When an override changes the operating system or
architecture, Once re-derives the platform tokens for the new target platform
so stale tokens do not survive. Overrides apply on top of the workspace
defaults, and only the resulting values affect target identity, not the flags
that produced them.
Because the effective configuration scopes outputs and receipts, building the same target under two configurations from one checkout keeps both results:
once build apps/Support # default configuration
once build apps/Support --config token=release # separate, scoped outputs
A later invocation with the same overrides reuses the scoped receipt and reports a cache hit, while an invocation with no overrides is unaffected.
Choose values with select#
Configurable attributes and dependencies use select to vary by token. A
target can choose its dependencies for the configured platform:
[target.deps.select]
macos = ["./apple_support"]
linux = ["./linux_support"]
default = ["./portable_support"]
When several branches could match, the most specific one wins, and default
is the fallback. Each ecosystem adds its own tokens and restrictions; see the
"Choose values by configuration" section of the relevant ecosystem guide, such
as Apple.