Schema Reference

The authoritative type definitions are in ../schema.cue. A feature is considered implemented only when it survives schema validation, CUE export, generated spec, and Zig execution.

Module fields

Field	Purpose	Default
`kind`	`exe`, `static`, `shared`, or `module`	required
`root`	root Zig source	required
`artifact_name`	produced name independent of graph/import key	module key
`deps`	internal module dependencies	`[]`
`profile`	`debug` or `release`	`debug`
`link`	`abi` or `import` consumption	`abi`
`pre`, `post`	explicit argv build commands	`[]`
`install_dirs`	install/resource directory staging	`[]`
`pkg_library_paths`	package-provided library search paths	`[]`
`pkg_imports`	imported Zig package modules	`[]`
`pkg_artifacts`	linked package artifacts	`[]`
`build_options`	named user-selectable typed options	`[]`
`option_values`	fixed typed values injected into options	`[]`
`gen_imports`	Zig modules generated by host tools	`[]`
`build_options_import`	options-module import name	`build-options`
`native`	C/C++ sources, includes, objects, libs, frameworks	`{}`

A shared target is always ABI-linked. A module target is always import-only and produces no standalone artifact.

Import and ABI edges

link: "import" uses Zig module import semantics and avoids a separate artifact for that dependency. link: "abi" keeps an independent compile artifact and links it. Large projects can combine the two into clusters: import-connected internals with ABI boundaries between clusters.

Toolchains and profiles

Projects can declare accepted Zig minor-version lanes and a preferred lane. The generated build rejects a compiler outside the declared set before doing real work. debug resolves to Zig Debug; release resolves to ReleaseFast.

Native build metadata

native can describe C sources, include/system-include directories, library paths, object files, system libraries, pkg-config libraries, Apple frameworks, and libc/libc++ linkage. System availability is still external; richer first-class prerequisite diagnostics are on the roadmap.

Options, packages, and generated modules

Top-level options currently support bool, string, and u32 values. Modules can also receive fixed typed option_values, including optional 40-character commit values.

pkg_imports, pkg_artifacts, and pkg_library_paths model real build.zig.zon dependency surfaces. The current corpus-proven package-option forms include backend enums and string-list fields; replacing those special cases with a generic typed dependency-argument representation is a production follow-up rather than an invitation to add more one-off fields.

gen_imports models the common pattern of compiling a host tool, running it, and importing the emitted Zig file through the build graph.

`export.cue`

project.cue contains declarations; export.cue chooses which declarations become the resolved build graph and projects every field the generator consumes. The _modules map is the explicit export list. The canonical CLI verifies that the complete module contract survived this stage, preventing schema features from being silently dropped downstream.