Module Files
Want operates on units called Modules. A Module is a filesystem tree with a file named WANT at its root.
The WANT file provides module-level configuration and doubles as a sanity
check that a directory is supposed to be built by Want. It is a Spore body that evaluates to a module config:
.deps = [
{"want", \(_: Ctx) FS LATEST},
]
.deps
.deps lists the module's dependencies. Each dep is a tuple of a name and a
proc that produces the dependency's filesystem from a build context
((#Product String (#Proc build.Ctx build.FS))). At plan time every dep's
proc runs and its returned filesystem is registered as a Spore source under
<name>:; planning files import its packages as <name>:pkg.
The WANT file is compiled with a preamble binding Ctx (build.Ctx), FS
(build.FS, a wantfs.Segment) and LATEST (the compiled-in want standard
library as an FS), so the default dep above gives the module the standard
library under want: without any imports. The spore standard library
(core:) is always implicit; a module that does not declare a want dep has
no want stdlib. want init writes the default config above.
.budget
.budget optionally sets the total resource ceiling for a build of the
module, including everything its child jobs claim. It has the same shape as
build.Limits: memory in bytes, cpu in microseconds per second (one core is
1000000), and a wall-clock timeout in seconds.
.budget = {
.memory = 1073741824 // bytes
.cpu = 2000000 // microseconds per second (2 cores)
.timeout = 600 // seconds
}
The export is optional: a WANT with no .budget has no module-level ceiling,
and the root job's own limit (the config directory's .budget, or 75% of the
host) applies. When .budget is present its fields are literal ceilings: the
build job inspects its own spawn-time ceiling and claims the difference
between it and the budget, so the module's child jobs can only draw the budget
in total, and each child is spawned with the budget as its ceiling. A zero
memory or cpu is therefore a zero ceiling, which leaves the build with no
resources for that dimension (it will block or fail); it is not "unset". If
the build job's own ceiling is already below the budget, nothing is claimed
and the child ceiling is unchanged. A zero .timeout means no module-level
timeout (the job's own timeout is kept). .timeout is a per-job wall-clock
ceiling, so it bounds each child job, not the build job itself. want init
does not write a .budget (a WANT with none builds unconstrained at the
module level).
.secrets
.secrets grants named secrets to the module's planning files. It is a list
of {paths, names} tuples, where paths is a paths.Set matched against a
planning file's module-root-relative path, and names is the list of secret
names that file may access:
paths = (#import "want:build/paths")
.secrets = [
{{.all = {}}, ["cloudflare"]}, // the whole module
{(paths.prefix "site/"), ["S3_KEY"]}, // files under site/
{(paths.unit "build/doc.want"), ["DOCS_TOKEN"]}, // one file
]
Only want build --publish uses secrets. Each matching target's build and
sink contexts receive the granted names as a (#List (#Port Unit Unit)) in
grant order (first occurrence wins), so a sink reads the first granted secret
with (#listslot ctx.secrets 0). The names must be supplied on the command
line:
-
--secret NAME:PATH— a single secret: the file's bytes. -
--secrets NAME:PATH— a spore module whose exports are the map entries:.CLOUDFLARE_API_TOKEN = "..." .CLOUDFLARE_ACCOUNT_ID = "..."
--secrets cloudflare:~/.config/want/cloudflare.sp supplies the map under the
name cloudflare, matching the grant above. A GitHub release upload takes a
file exporting .GITHUB_TOKEN in the same way:
--secrets github:~/.config/want/github.sp. A name supplied twice is an
error; names supplied but unused are ignored. A publish build fails before
running any target if a file it will publish is granted a name that was not
supplied. Secret values are loaded into memory (never the content store), and
only port tokens travel through tasks. Keep secret files outside the module
tree (or dot-ignored, as .* in the default .wantignore) so the workspace
import does not capture them as ordinary sources.
.wantignore
Which paths are imported into the module is configured separately, by a root
.wantignore file. It uses gitignore-style patterns, one per line: any path
matching a pattern is left out of the imported module tree.
By default a project that uses Git should ignore its VCS metadata and build outputs. For example:
.*
zig-out/
zig-cache/
.* ignores every dotfile (including .git), which keeps the import fast; the
other entries ignore build output directories.
.want is always ignored, and files starting with .want cannot be imported.