Module build

Optimization level for compiled artifacts.

Memory allocator to use in the compiled artifact.

Whether the compiled artifact carries the reference-cycle collector (yo compile --cycle-collector auto|off, plans/backlog/WEAK_AND_UNCOLLECTED_RC.md §1).

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/archive/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.

The [package] table of the yo.toml beside the build file being evaluated. A field the manifest does not set, and every field outside a build, reads as "".

Output format for documentation generation.

Configuration for documentation generation.

The mode a build.verify step runs its target files in (the same two modes Pragma.Verify / Pragma.VerifyOrAssert select per file, see docs/en-US/FORMAL_VERIFICATION.md §Modes).

Configuration for a verification step.

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.

The manifest of the package whose build file is being evaluated, so an artifact or step can be named by yo.toml instead of repeating it.

A function, not a module-level value: std/build.yo is evaluated once per yo build, and a dependency's build.yo runs after the project's against that same evaluation. A value would keep the project's fields there; each call reads the manifest of the build file it is evaluated in.

Examples

build :: import("std/build");

exe :: build.executable({ name : build.manifest().name, root : "./src/main.yo" });

install :: build.step("install", build.manifest().version);
install.depend_on(exe);

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);

Register a verification step: yo build <name> runs yo verify <root> with the pinned Z3. Returns a Step for dependency wiring. This is the project-level "every build proves my contracts" switch; yo check stays solver-free by design.

Examples

build :: import("std/build");

proofs :: build.verify({ name : "verify", root : "./src" });

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

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.