Module build

Optimization level for compiled artifacts.

Memory allocator to use in the compiled artifact.

Runtime sanitizer to enable.

Kind of build step.

Configuration for building an executable.

Configuration for building a static library.

Configuration for building a shared/dynamic library.

Configuration for a test suite.

A named module of this package or of a dependency, as a handle for linking system libraries (mod.link(sys)). Which FILE the module is — and what import("name") resolves to — is the manifest's business (yo.toml [modules], plans/BUILD_AND_DEPENDENCY_SYSTEM_REDESIGN.md §4.1).

A build step returned by all registration functions. Use step.depend_on(dep) to wire dependencies between steps.

User-configurable build option (declared in build.yo, set via yo build -Dname=value).

System C library discovered via pkg-config.

Handle to a manifest dependency. Use .artifact() or .module() to access its exports.

Module configuration. The module's root file is declared in yo.toml's [modules] table (default = "src/lib.yo", board = "src/board.yo"); build.module names one of those to attach system libraries to it.

Output format for documentation generation.

Configuration for documentation generation.

Register an executable artifact. Returns a Step for dependency wiring.

Register a static library artifact. Returns a Step for dependency wiring.

Register a shared/dynamic library artifact. Returns a Step for dependency wiring.

Register a test-suite artifact. Returns a Step for dependency wiring.

Create a run step (compile + execute an artifact). Returns a Step.

Register a named build step. Use step.depend_on(dep) to add dependencies.

The handle of a dependency declared in yo.toml's [dependencies] (or [dev-dependencies]) — Zig's b.dependency(name, .{}). Where the dependency comes from (git, version, path) is the manifest's; the build file only names it. The runner rejects a name the manifest lacks.

Register a system C library discovered via pkg-config. Returns a Step for linking.

Get a module from the dependency's build.yo. Empty module_name defaults to the sole module if exactly one exists.

Declare a user-configurable build option. Returns the option value (from CLI -Dname=value, or the default).

Example

strip :: build.option({
  name: "strip",
  description: "Strip debug symbols",
  default: "false"
});

The environment variable name, or fallback when it is unset.

Readable ONLY from a build file. An ordinary module that read the environment would mean something different under yo build, yo check, yo test and the editor, so the builtin is a compile error everywhere else.

Every read is folded into the artifact input stamp, so changing a variable the build file branches on rebuilds rather than serving a stale artifact.

PREFER build.option and -Dname=value: an option is declared, listed by yo build --list-options, and visible in the command that produced a build. Reach for env for what genuinely belongs to the environment — CI detection, PKG_CONFIG_PATH, a default that depends on the machine.

Whether name is set at all, which env alone cannot tell you: a variable set to the same text as the fallback is indistinguishable from an unset one.

Register a documentation generation step. Returns a Step for dependency wiring.

Examples

build :: import "std/build";

// Minimal — just works with defaults
doc_step :: build.doc({ name: "doc", root: "./src/lib.yo" });

// Full customization
doc_step :: build.doc({
  name: "doc",
  root: "./src",
  output: "docs/api",
  format: DocFormat.Markdown,
  title: "My Library API",
  version: "v1.0.0"
});

install :: build.step("install", "Build all artifacts");
install.depend_on(doc_step);

The supported compilation targets, named by their canonical Rust-style triple (<arch>-<vendor>-<os>[-<env>], plus wasm32-wasip1) — the same strings yo compile --target takes and the release assets are named by. There are no aliases: an unrecognised spelling is rejected with this list.

Host compilation target string.