std/build

Types

Builder

pub type Builder

The build program's capability. Every method only records a step in the build graph; kigumi build resolves targets, compiles, links and runs tools after configure returns. configure runs in the comptime sandbox: no files, processes or network beyond these methods.

Builder.request

pub fn Builder.request(self) -> Request

The request kigumi build is carrying out.

Builder.hostTarget

pub fn Builder.hostTarget(self) -> Target

The machine kigumi build runs on, whatever --target says.

Builder.target

pub fn Builder.target(self, triple: String) -> Target

Names a target by triple (--sys is derived; x86_64-freestanding gives the freestanding layer).

Builder.framework

pub fn Builder.framework(self, name: String, version: String) -> Framework

References a Framework; whether the toolchain has it is checked once a tool step depends on it.

Builder.secret

pub fn Builder.secret(self, name: String) -> Secret

A handle to the named build secret, resolved only when a tool run needs it.

Builder.file

pub fn Builder.file(self, path: String) -> FilePath!

An existing file, relative to the module root; fails outside the root module, the required modules and the build output directory.

Builder.write

pub fn Builder.write(self, name: String, content: String) -> FilePath!

A file named name in the build output directory holding content, written when the graph executes.

Builder.executable

pub fn Builder.executable(self, name: String, dir: String, target: Target) -> Artifact!

Declares an executable compiled from the package tree at dir (root-relative, one entry file) for target.

Builder.library

pub fn Builder.library(self, name: String, dir: String, target: Target) -> Artifact!

Declares a library: an archive with a kigumi_main entry for an embedder. target must be freestanding or --sys none.

Builder.runTool

pub fn Builder.runTool(self, fw: Framework, tool: String, args: Array[String], inputs: Array[FilePath], outputs: Array[String], secrets: Array[Secret]) -> Array[FilePath]!

Runs one of the tools fw's descriptor registers. args are literal except $in:<i>, $out:<i> and $secret:<i>, replaced with real paths just before the process starts. Nothing runs during configure.

Builder.runArtifact

pub fn Builder.runArtifact(self, artifact: Artifact, args: Array[String], inputs: Array[FilePath], outputs: Array[String]) -> Array[FilePath]!

Runs a host executable artifact built earlier in this graph, as a tool step: same placeholder and trusted-mode rules as runTool, but no secrets and no Framework, since the artifact is the program.

Builder.toolchain

pub fn Builder.toolchain(self) -> Framework

The cc and ld of the toolchain kigumi build itself links with (zig, when installed), as a Framework named "toolchain"; the same value b.framework("toolchain", "") would return.

Builder.runToolOutput

pub fn Builder.runToolOutput(self, fw: Framework, tool: String, args: Array[String], inputs: Array[FilePath], output: String, secrets: Array[Secret]) -> FilePath!

runTool for a tool with exactly one declared output.

Request

@unsafeGuarantee(Copy)
pub type Request

The kigumi build invocation this run of configure serves. Safety: a read-only view over the request; its accessors touch no build-graph state, so duplicating it is free.

Request.target

pub fn Request.target(self) -> Target

The target --target / --sys selected, or the host.

Request.flag

pub fn Request.flag(self, name: String) -> Bool

Whether --<name> was given after -- on the command line.

Target

@unsafeGuarantee(Copy)
pub type Target

A target triple such as "x86_64-linux-musl" or "x86_64-freestanding"; the host when empty. Resolved when the graph executes, so a bad triple is a build error there, never a configure failure. Safety: either a plain triple string or an index into the build graph's target table; duplicating it does not touch build-graph state.

Framework

@unsafeGuarantee(Copy)
pub type Framework

A provider-namespaced Framework (b.framework("intel/sgx-sdk", "2.30")) whose descriptor lists the external tools runTool may call. Safety: a plain index into the build graph's framework table; duplicating it does not touch build-graph state.

Secret

@unsafeGuarantee(Copy)
pub type Secret

An opaque build secret (a signing key). configure never sees its bytes; runTool binds it to a $secret:<i> argument for one tool run. Safety: a plain index into the build graph's secret table, never the key bytes; duplicating it does not touch build-graph state.

FilePath

@unsafeGuarantee(Copy)
pub type FilePath

A file inside the root module, a required module or the build output directory. Safety: a plain index into the build graph's file table; duplicating it does not touch build-graph state.

Artifact

pub type Artifact

A declared executable or library artifact.

Artifact.output

pub fn Artifact.output(self) -> FilePath

This artifact's compiled output, usable as a later step's input.

Artifact.uses

pub fn Artifact.uses(self, other: Artifact)

Builds other first and merges its C sources and link flags into self.

Artifact.addSource

pub fn Artifact.addSource(self, file: FilePath)

Adds a C source compiled into self, alongside mod.kg's Source records.

Artifact.addLink

pub fn Artifact.addLink(self, library: String, search: String)

Adds a link flag alongside mod.kg's Link records: library is a -l name, search a -L directory.

Artifact.linkerScript

pub fn Artifact.linkerScript(self, file: FilePath)

Sets self's linker script (-T); a later call replaces it. Needs a hosted target: never a freestanding one, which links as an archive instead.

Artifact.linkFlags

pub fn Artifact.linkFlags(self, flags: Array[String])

Adds flags to self's link step, such as -nostdlib or -static-pie; later calls add to the list.

Artifact.entry

pub fn Artifact.entry(self, name: String)

Sets self's link entry symbol; a later call replaces it.

Artifact.availability

pub fn Artifact.availability(self, deny: Array[String], ceiling: String)

Restricts which std packages self's package graph may import: deny bars each listed path outright, ceiling caps every std package to that layer or lower ("core", "alloc", "sys" or "tool"; "" for no ceiling). A barred package is unavailable transitively too, reported at the importing package. A later call adds to deny and replaces a non-empty ceiling. Each deny path must name a real std package; an unknown path aborts configure.

NoToolOutput

pub type NoToolOutput = {
    pub tool String
}

Error raised when a tool declares outputs but the run produced none.

NoToolOutput.message

pub fn NoToolOutput.message(self) -> String

The failure text.