Module `build`

build

Declarative build API for Yo projects.

All functions are compile-time only — they register build artifacts and steps that the build runner uses to orchestrate compilation.

Example

build :: import "std/build";

mod  :: build.module({ name: "my-lib", root: "./src/lib.yo" });
exe  :: build.executable({ name: "my-app", root: "./src/main.yo" });
install :: build.step("install", "Build all artifacts");
install.depend_on(exe);

Types

Optimize enum

Optimize

Optimization level for compiled artifacts.

Variants

Variant	Fields	Description
`Debug`		No optimizations, full debug info. Compiler Flags: `-O0 -g`
`ReleaseSafe`		Optimized with safety checks. Compiler Flags: `-O2 -g`
`ReleaseFast`		Maximum speed optimizations. Compiler Flags: `-O3`
`ReleaseSmall`		Optimize for binary size. Compiler Flags `-O2`

Allocator enum

Allocator

Memory allocator to use in the compiled artifact.

Variants

Variant	Fields	Description
`Mimalloc`		High-performance allocator (mimalloc).
`Libc`		Standard C library malloc.

Sanitize enum

Sanitize

Runtime sanitizer to enable.

Variants

Variant	Fields	Description
`None`		No sanitizer.
`Address`		AddressSanitizer — detects memory errors and leaks.
`Leak`		LeakSanitizer — detects memory leaks only.

StepKind enum

StepKind

Kind of build step.

Variants

Variant	Fields	Description
`Executable`		Configuration for building an executable.
`StaticLibrary`		Configuration for building a static library.
`SharedLibrary`		Configuration for building a shared/dynamic library.
`SystemLibrary`		System C library discovered via `pkg-config`.
`TestSuite`		Configuration for a test suite.
`Run`
`Custom`
`Documentation`

Executable struct

Executable

Configuration for building an executable.

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`root`	comptime_string	Root source file or directory to document.
`target`	comptime_string	Compilation target triple (defaults to host).
`optimize`	Optimize	Optimization level.
`allocator`	Allocator	Memory allocator.
`sanitize`	Sanitize	Runtime sanitizer.

StaticLibrary struct

StaticLibrary

Configuration for building a static library.

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`root`	comptime_string	Root source file or directory to document.
`target`	comptime_string	Compilation target triple (defaults to host).
`optimize`	Optimize	Optimization level.

SharedLibrary struct

SharedLibrary

Configuration for building a shared/dynamic library.

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`root`	comptime_string	Root source file or directory to document.
`target`	comptime_string	Compilation target triple (defaults to host).
`optimize`	Optimize	Optimization level.

TestSuite struct

TestSuite

Configuration for a test suite.

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`root`	comptime_string	Root source file or directory to document.
`target`	comptime_string	Compilation target triple (defaults to host).

BuildModule struct

BuildModule

Represents a named source module that declares system library requirements. Modules are the unit of reuse across Yo dependencies.

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`root`	comptime_string	Root source file or directory to document.
`_dep`	comptime_string

impl(BuildModule, ...)

link :

(BuildModule) fn(comptime(self) : BuildModule, comptime(library) : Step) -> (comptime(fn_return_yo3e0b6a2b_id_159) : unit)

Link a system library into this module.

Parameters

Name	Type	Notes
`self`	BuildModule	comptime
`library`	Step	comptime

Returns: unit

ImportEntry struct

ImportEntry

Pairs an import name with a module for use with add_import/add_import_list.

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`module`	BuildModule	Get a module from the dependency's `build.yo`. Empty `module_name` defaults to the sole module if exactly one exists.

Step struct

Step

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

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`kind`	StepKind	Kind of step.

impl(Step, ...)

depend_on : (Step) fn(comptime(self) : Step, comptime(dep) : Step) -> (comptime(fn_return_yo3e0b6a2b_id_140) : unit)

Add a dependency — dep must complete before this step runs.

Parameters

Name	Type	Notes
`self`	Step	comptime
`dep`	Step	comptime

Returns: unit

link : (Step) fn(comptime(self) : Step, comptime(library) : Step) -> (comptime(fn_return_yo3e0b6a2b_id_143) : unit)

Link a system library into this module.

Parameters

Name	Type	Notes
`self`	Step	comptime
`library`	Step	comptime

Returns: unit

add_import : (Step) fn(comptime(self) : Step, comptime(entry) : ImportEntry) -> (comptime(fn_return_yo3e0b6a2b_id_146) : unit)

Add a single module import to this step.

Parameters

Name	Type	Notes
`self`	Step	comptime
`entry`	ImportEntry	comptime

Returns: unit

add_import_list :

(Step) fn(comptime(self) : Step, comptime(entries) : ComptimeList(ImportEntry)) -> (comptime(fn_return_yo3e0b6a2b_id_149) : unit)

Add a list of module imports to this step.

Parameters

Name	Type	Notes
`self`	Step	comptime
`entries`	ComptimeList(ImportEntry)	comptime

Returns: unit

add_c_flags : (Step) fn(comptime(self) : Step, comptime(flags) : comptime_string) -> (comptime(fn_return_yo3e0b6a2b_id_155) : unit)

Add extra C compiler flags to this step.

Parameters

Name	Type	Notes
`self`	Step	comptime
`flags`	comptime_string	comptime

Returns: unit

BuildOption struct

BuildOption

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

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`description`	comptime_string	Human-readable description.
`default`	comptime_string	Default value if not provided.

GitDependency struct

GitDependency

Git-hosted dependency configuration.

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`url`	comptime_string	Git repository URL.
`ref`	comptime_string	Git ref (tag, branch, or commit SHA). Defaults to `"HEAD"`.
`path`	comptime_string	Filesystem path to the dependency root.

PathDependency struct

PathDependency

Local path dependency configuration.

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`path`	comptime_string	Filesystem path to the dependency root.

SystemLibrary struct

SystemLibrary

System C library discovered via pkg-config.

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`fallback_include`	comptime_string	Fallback include path if pkg-config fails.
`fallback_lib`	comptime_string	Fallback library path.
`fallback_link`	comptime_string	Fallback link flags.
`defines`	comptime_string	Extra C preprocessor defines.

Dependency struct

Dependency

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

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").

impl(Dependency, ...)

artifact :

(Dependency) fn(comptime(self) : Dependency, comptime(artifact_name) : comptime_string) -> (comptime(fn_return_yo3e0b6a2b_id_203) : Step)

Access a named artifact from the dependency's build.yo. Returns a Step that can be linked to the consumer's artifacts.

Parameters

Name	Type	Notes
`self`	Dependency	comptime
`artifact_name`	comptime_string	comptime

Returns: Step

module :

(Dependency) fn(comptime(self) : Dependency, (comptime(module_name) : comptime_string) ?= "") -> (comptime(fn_return_yo3e0b6a2b_id_206) : BuildModule)

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

Parameters

Name	Type	Notes
`self`	Dependency	comptime
`module_name`	comptime_string	comptime, default: [object Object]

Returns: BuildModule

ModuleConfig struct

ModuleConfig

Module configuration for shared compilation units.

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`root`	comptime_string	Root source file or directory to document.

DocFormat enum

DocFormat

Output format for documentation generation.

Variants

Variant	Fields	Description
`Html`
`Markdown`
`Json`

DocConfig struct

DocConfig

Configuration for documentation generation.

Fields

Name	Type	Description
`name`	comptime_string	Step name (e.g., "doc").
`root`	comptime_string	Root source file or directory to document.
`output`	comptime_string	Output directory (default: "yo-out/doc").
`format`	DocFormat	Output format (default: Html).
`include_private`	bool	Document non-exported (private) items.
`include_deps`	bool	Document dependencies too.
`title`	comptime_string	Custom site title (default: project name).
`version`	comptime_string	Release version to display (e.g., "v1.0.0"). When empty, auto-detects from git tag or commit hash.
`logo`	comptime_string	Path to logo image.
`favicon`	comptime_string	Path to favicon.

Functions

executable function

fn(comptime(config) : Executable) -> (comptime(fn_return_yo3e0b6a2b_id_209) : Step)

Parameters

Name	Type	Notes
`config`	Executable	comptime

Returns: Step

static_library function

fn(comptime(config) : StaticLibrary) -> (comptime(fn_return_yo3e0b6a2b_id_212) : Step)

Parameters

Name	Type	Notes
`config`	StaticLibrary	comptime

Returns: Step

shared_library function

fn(comptime(config) : SharedLibrary) -> (comptime(fn_return_yo3e0b6a2b_id_215) : Step)

Parameters

Name	Type	Notes
`config`	SharedLibrary	comptime

Returns: Step

test function

fn(comptime(config) : TestSuite) -> (comptime(fn_return_yo3e0b6a2b_id_218) : Step)

Parameters

Name	Type	Notes
`config`	TestSuite	comptime

Returns: Step

run function

fn(comptime(artifact) : Step) -> (comptime(fn_return_yo3e0b6a2b_id_221) : Step)

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

Parameters

Name	Type	Notes	Description
`artifact`	Step	comptime	Access a named artifact from the dependency's `build.yo`. Returns a `Step` that can be linked to the consumer's artifacts.

Returns: Step

step function

fn(comptime(name) : comptime_string, comptime(description) : comptime_string) -> (comptime(fn_return_yo3e0b6a2b_id_224) : Step)

Parameters

Name	Type	Notes	Description
`name`	comptime_string	comptime	Step name (e.g., "doc").
`description`	comptime_string	comptime	Human-readable description.

Returns: Step

dependency function

fn(comptime(config) : GitDependency) -> (comptime(fn_return_yo3e0b6a2b_id_227) : Dependency)

Parameters

Name	Type	Notes
`config`	GitDependency	comptime

Returns: Dependency

path_dependency function

fn(comptime(config) : PathDependency) -> (comptime(fn_return_yo3e0b6a2b_id_230) : Dependency)

Parameters

Name	Type	Notes
`config`	PathDependency	comptime

Returns: Dependency

system_library function

fn(comptime(config) : SystemLibrary) -> (comptime(fn_return_yo3e0b6a2b_id_233) : Step)

Parameters

Name	Type	Notes
`config`	SystemLibrary	comptime

Returns: Step

module function

fn(comptime(config) : ModuleConfig) -> (comptime(fn_return_yo3e0b6a2b_id_244) : BuildModule)

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

Parameters

Name	Type	Notes
`config`	ModuleConfig	comptime

Returns: BuildModule

option function

fn(comptime(config) : BuildOption) -> (comptime(fn_return_yo3e0b6a2b_id_247) : str)

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

Parameters

Name	Type	Notes
`config`	BuildOption	comptime

Returns: str

doc function

fn(comptime(config) : DocConfig) -> (comptime(fn_return_yo3e0b6a2b_id_278) : Step)

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

Parameters

Name	Type	Notes
`config`	DocConfig	comptime

Returns: Step

Constants

CompilationTarget constant struct(X86_64_Linux_Gnu: comptime_string, X86_64_Linux_Musl: comptime_string, Aarch64_Linux_Gnu: comptime_string, Aarch64_Linux_Musl: comptime_string, Aarch64_Macos: comptime_string, X86_64_Macos: comptime_string, X86_64_Windows_Msvc: comptime_string, Wasm32_Emscripten: comptime_string, Wasm32_Wasi: comptime_string)

Value: _(X86_64_Linux_Gnu: "x86_64-linux-gnu", X86_64_Linux_Musl: "x86_64-linux-musl", Aarch64_Linux_Gnu: "aarch64-linux-gnu", Aarch64_Linux_Musl: "aarch64-linux-musl", Aarch64_Macos: "aarch64-macos", X86_64_Macos: "x86_64-macos", X86_64_Windows_Msvc: "x86_64-windows-msvc", Wasm32_Emscripten: "wasm32-emscripten", Wasm32_Wasi: "wasm32-wasi")

target_host constant comptime_string

Host compilation target string.

Value: "x86_64-linux-gnu"

Module build

Example

Types

Variants

Variants

Variants

Variants

Fields

Fields

Fields

Fields

Fields

Parameters

Fields

Fields

Parameters

Parameters

Parameters

Parameters

Parameters

Fields

Fields

Fields

Fields

Fields

Parameters

Parameters

Fields

Variants

Fields

Functions

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Example

Parameters

Examples

Parameters

Constants

Module `build`