silk.build.step.

Build steps, their declared inputs, and values resolved only by the graph runner.

Import as Step with import silk.build.step { Step }.

Public declarations: 18.

StepError#

silk
pub struct StepError

A build graph or step violated its declared input or output contract.

Field message#

silk
pub message: String

The diagnostic describing the refused operation.

Implementation Debug for StepError#

silk
impl Debug for StepError

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

StepFailure#

silk
pub type StepFailure = StepError
  | AtomicWriteError
  | FileError
  | ProcessError
  | HostInputError
  | SchemaError
  | WriterError
  | OutOfMemoryError

Failures preserved by the build runner and its file, process, and serialization operations.

Deferred#

silk
pub struct Deferred<T>

A typed reference to a source, a known value, or a step result. Only Make resolves it.

describedPath#

silk
pub static fn describedPath(input: Description) -> Deferred<Path>

Describes an input during static plan construction without allocating a graph node.

sourcePath#

silk
pub static fn sourcePath(path: string<'static>) -> Deferred<Path>

Names a package-relative file during static plan construction.

suppliedPath#

silk
pub static fn suppliedPath(path: string<'static>) -> Deferred<Path>

Names a host path explicitly supplied to a package plan by its root command.

Implementation Deferred<T>#

silk
impl<T> Deferred<T>

Associated function fromDescription#

silk
pub fn fromDescription(input: Description) -> Deferred<Path>

Retains a standard-action description already read by runtime graph construction.

Method description#

silk
pub static fn description(self: &Self) -> Description

Reads the static description; runtime deferred values cannot enter a package plan.

Implementation Deferred<T>#

silk
impl<T> Deferred<T>

Method copy#

silk
pub effect fn copy(self: &Self) -> Self
    ! OutOfMemoryError
    ? &mut Allocator

Retains a deferred reference without evaluating it or starting its producer.

Implementation Deferred<T>#

silk
impl<T> Deferred<T>

Associated function source#

silk
pub effect fn source(path: string) -> Deferred<Path>
    ! OutOfMemoryError
    ? &mut Allocator

Names a path relative to the package root. The runner refuses paths that leave that root.

Associated function external#

silk
pub effect fn external(path: string) -> Deferred<Path>
    ! OutOfMemoryError
    ? &mut Allocator

Names an explicitly supplied absolute host path.

Implementation Schema for Deferred<T>#

silk
impl<T> Schema for Deferred<T>

A deferred value travels in a step description as its reference, never as its result.

Operation read#

silk
effect fn read<R: SchemaReader>(reader: &mut R) -> Self
    ! Issue | OutOfMemoryError
    ? &mut Allocator

Operation write#

silk
effect fn write<W: SchemaWriter>(self: &Self, writer: &mut W) -> ()
    ! Issue | WriterError | OutOfMemoryError
    ? &mut Writer | &mut Allocator

Implementation Deferred<T>#

silk
impl<T: Schema> Deferred<T>

Associated function value#

silk
pub effect fn value(value: T) -> Self
    ! StepFailure
    ? &mut Allocator

Captures a known value without exposing a way to read deferred results while constructing the graph.

Method map#

silk
pub effect fn map<
    U: Schema + Transferable + 'static,
    F: fn<'static>(T) -> U + Transferable + 'static
  >(self: Self, transform: F) -> Deferred<U>
    ! StepFailure
    ? &mut Allocator

Applies a noncapturing pure function when the graph resolves this value. The function's type and the task executable identify its code in the key.

Key#

silk
pub struct Key

The complete inputs of a step. Its methods record inputs without reading files or running work.

Implementation Key#

silk
impl Key

Associated function collecting#

silk
pub fn collecting() -> Self

Starts an empty key, for collecting what a described step declares.

Method producers#

silk
pub effect fn producers(self: &Self) -> List<StepHandle>
    ! OutOfMemoryError
    ? &mut Allocator

Retains every step whose output this key declares as an input.

Method bytes#

silk
pub effect fn bytes(self: &mut Self, value: &[u8]) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Adds bytes with a length prefix so adjacent values cannot collide.

Method text#

silk
pub effect fn text(self: &mut Self, value: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Adds text to the step's identity.

Method file#

silk
pub effect fn file(self: &mut Self, value: &Deferred<Path>) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Declares one readable file; its bytes or producer key participate in this step's key.

Method toolchain#

silk
pub effect fn toolchain(self: &mut Self, compiler: &Deferred<Path>) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Hashes the compiler and the LLVM tools selected from its installation and environment. Tool contents are inspected before every cache lookup, including replacements at the same path.

Method tree#

silk
pub effect fn tree(self: &mut Self, value: &Deferred<Path>) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Declares a readable directory tree, including its names and file contents.

Method packageTree#

silk
pub effect fn packageTree(self: &mut Self, value: &Deferred<Path>) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Declares package contents, excluding the root build directory and .git metadata. Generated inputs below build must be declared separately through their producer.

Method value#

silk
pub effect fn value<T>(self: &mut Self, value: &Deferred<T>) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Declares a typed value; a produced value contributes its producer key before it exists.

Method files#

silk
pub effect fn files(self: &mut Self, paths: &Deferred<List<String>>) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Declares a deferred list of absolute file paths. The runner obtains the list first, then includes each file's path and contents in this step's key before deciding whether to run it.

Method trees#

silk
pub effect fn trees(self: &mut Self, paths: &Deferred<List<String>>) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Declares deferred absolute directory paths, hashing each complete tree before cache lookup.

Method packageTrees#

silk
pub effect fn packageTrees(self: &mut Self, paths: &Deferred<List<String>>) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Declares deferred package directories, excluding each root's build and version-control data.

Method environment#

silk
pub effect fn environment(self: &mut Self, name: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Declares an environment variable. Its presence and value enter the key and the child environment.

Method passEnvironment#

silk
pub effect fn passEnvironment(self: &mut Self, name: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Passes an environment variable to the child process without adding it to the key, for a setting that changes only what the process reports, such as its progress display.

Method always#

silk
pub fn always(self: &mut Self) -> ()

Runs this step and every consumer on every invocation, even when their keys are unchanged.

Step#

silk
pub interface Step

Work a root task explicitly adds to its build graph. Package plans cannot introduce custom implementations.

Operation prepare#

silk
effect fn prepare(self: Self) -> Self
    ! StepFailure
    ? &mut Allocator

Materializes a static description before its inputs are recorded. This phase allocates only.

Operation key#

silk
effect fn key(self: &Self, key: &mut Key) -> () ! StepFailure ? &mut Allocator

Records everything the work reads. It must perform no filesystem or process operations.

Operation make#

silk
effect fn make(self: &Self, make: &mut Make) -> () ! StepFailure ? &mut Allocator

Produces the outputs through Make, which rejects undeclared file and value inputs.

Operation memory#

silk
fn memory(self: &Self) -> u64

The estimated peak memory, used to bound concurrently running steps. Defaults to 256 MiB.

Operation compilation#

silk
fn compilation(self: &Self) -> bool

Whether this step writes a compilation request and can stop before invoking the compiler.

Provision#

silk
pub struct Provision

Where a step that another process ran left its outputs.

Field directory#

silk
pub directory: String

The step's cache directory, named by its key.

Field volatile#

silk
pub volatile: bool

Whether the step runs every time, so its consumers do too.

Field compilation#

silk
pub compilation: bool

Whether the step is a compilation.

Field compiled#

silk
pub compiled: bool

Whether a compilation built its artifact, or only wrote its request.

Implementation Schema for Provision#

silk
impl Schema for Provision

Operation spec#

silk
static fn spec() -> Spec<Provision>

StepHandle#

silk
pub struct StepHandle

An owned step registered in a graph. Several deferred outputs may retain the same step.

StepDescription#

silk
pub struct StepDescription

One step of a described graph: what the task program hands to the compiler.

Field node#

silk
pub node: u64

The step's identity within its description.

Field kind#

silk
pub kind: String

The kind of standard step.

Field step#

silk
pub step: String

The step's own JSON description.

Implementation Schema for StepDescription#

silk
impl Schema for StepDescription

Operation spec#

silk
static fn spec() -> Spec<StepDescription>
silk
pub struct Link

A described step's identity and the step restored for it.

Implementation StepHandle#

silk
impl StepHandle

Method copy#

silk
pub fn copy(self: &Self) -> Self

Retains the step without copying or running its work.

Method identity#

silk
pub fn identity(self: &Self) -> usize

The step's identity among the live steps of this process.

Associated function described#

silk
pub effect fn described(kind: string, step: Bytes, producers: List<StepHandle>) -> Self
    ! OutOfMemoryError
    ? &mut Allocator

Holds a standard step as its description. producers are the steps whose outputs it reads. The compiler restores the step by its kind and runs it.

Associated function provided#

silk
pub effect fn provided(provision: Provision) -> Self
    ! OutOfMemoryError
    ? &mut Allocator

Holds a step that already ran, as the directory its outputs are in.

Method description#

silk
pub effect fn description(self: &Self) -> Option<StepDescription>
    ! StepFailure
    ? &mut Allocator

The step's description, when it is a standard step that has not been restored.

Method install#

silk
pub effect fn install(self: &Self, restored: &StepHandle) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Gives this step the work, or the provision, of the step restored from its description.

Associated function linkedSteps#

silk
pub effect fn linkedSteps(links: &[Link]) -> List<StepHandle>
    ! OutOfMemoryError
    ? &mut Allocator

The steps restored for a description, in its order.

Associated function describeAll#

silk
pub effect fn describeAll(targets: &[StepHandle]) -> Option<List<StepDescription>>
    ! StepFailure
    ? &mut Allocator

Describes these steps and everything they read, producers first. Answers nothing when the graph holds a custom step, which only this program can run.

Associated function executorOf#

silk
pub effect fn executorOf(targets: &[StepHandle]) -> Option<Graphs.Executor>
    ! OutOfMemoryError
    ? &mut Allocator

Finds the executor of a custom step among these steps and everything they read.

Associated function restoreAll#

silk
pub effect fn restoreAll(steps: &[StepDescription]) -> List<Link>
    ! OutOfMemoryError
    ? &mut Allocator

Restores described steps without running them, and answers the link of each.

Associated function linked#

silk
pub fn linked(links: &[Link], node: u64) -> Option<StepHandle>

Finds the step restored for node of a description.

Method output#

silk
pub effect fn output(self: &Self, name: string) -> Deferred<Path>
    ! StepError | OutOfMemoryError
    ? &mut Allocator

Names one file that this step will produce. The path must stay below its output directory.

Method resolvedPath#

silk
pub fn resolvedPath(self: &Self) -> Deferred<Path>

Uses the absolute path text published by Make.value as a deferred file or tree. The producer runs when a consumer needs this path; the consumer keys the referenced contents.

Method valueFile#

silk
pub effect fn valueFile<T: Schema>(self: &Self, name: string) -> Deferred<T>
    ! StepError | OutOfMemoryError
    ? &mut Allocator

Names a typed JSON output published by Make.valueFile during this step.

Method value#

silk
pub effect fn value<T: Schema>(self: &Self) -> Deferred<T>
    ! OutOfMemoryError
    ? &mut Allocator

Names the typed value published by Make.value during this step.

Implementation Step#

silk
impl Step

Associated function register#

silk
pub effect fn register<T: Step + Transferable + 'static>(input: T) -> StepHandle
    ! StepFailure
    ? &mut Allocator

Takes ownership of custom work and records its key without running it. Outputs retain this handle.

Associated function describe#

silk
pub effect fn describe<T: Step + Schema>(kind: string, input: T) -> StepHandle
    ! StepFailure
    ? &mut Allocator

Holds a standard step as its description, without its work. kind names how the compiler restores it.

Associated function output#

silk
pub effect fn output(step: &StepHandle, name: string) -> Deferred<Path>
    ! StepError | OutOfMemoryError
    ? &mut Allocator

Names an output of registered work, creating its dependency edge without running it.

Make#

silk
pub struct Make

The resolved inputs and output directory visible only while a step runs.

Implementation Make#

silk
impl Make

Method readWithin#

silk
pub effect fn readWithin(self: &mut Self, tree: &Deferred<Path>, name: string) -> Bytes
    ! StepFailure
    ? &mut Allocator

Reads one relative child of a directory declared with Key.tree.

Method glob#

silk
pub effect fn glob(self: &mut Self, tree: &Deferred<Path>, pattern: string) -> List<Path>
    ! StepFailure
    ? &mut Allocator

Lists files matching a package-relative glob within a declared tree. The directory must have been declared with Key.tree or Key.packageTree.

Method requireOutput#

silk
pub effect fn requireOutput(self: &mut Self, name: string) -> ()
    ! StepFailure
    ? &mut Allocator

Verifies that a process wrote a declared output before the runner publishes its cache entry.

Method path#

silk
pub effect fn path(self: &Self, value: &Deferred<Path>) -> Path
    ! StepFailure
    ? &mut Allocator

Resolves a file previously declared with Key.file or Key.tree.

Method producer#

silk
pub effect fn producer<T>(self: &Self, value: &Deferred<T>) -> Option<String>
    ! StepFailure
    ? &mut Allocator

Returns a declared input's producer key, absent for source files and known values.

Method read#

silk
pub effect fn read(self: &mut Self, value: &Deferred<Path>) -> Bytes
    ! StepFailure
    ? &mut Allocator

Reads a file previously declared in the key; undeclared access fails before opening a file.

Method get#

silk
pub effect fn get<T: Schema>(self: &mut Self, value: &Deferred<T>) -> T
    ! StepFailure
    ? &mut Allocator

Resolves a typed value previously declared with Key.value.

Method output#

silk
pub effect fn output(self: &Self, name: string) -> Path
    ! StepFailure
    ? &mut Allocator

Returns a path below this step's output directory, refusing traversal and absolute names.

Method readOutput#

silk
pub effect fn readOutput(self: &mut Self, name: string) -> Bytes
    ! StepFailure
    ? &mut Allocator

Reads a file produced inside this step's output directory, refusing paths outside it.

Method write#

silk
pub effect fn write(self: &mut Self, name: string, bytes: &[u8]) -> ()
    ! StepFailure
    ? &mut Allocator

Writes a file below this step's output directory, creating its parent directories.

Method valueFile#

silk
pub effect fn valueFile<T: Schema>(self: &mut Self, name: string, value: &T) -> ()
    ! StepFailure
    ? &mut Allocator

Publishes one named typed result as JSON for deferred consumers.

Method value#

silk
pub effect fn value<T: Schema>(self: &mut Self, value: &T) -> ()
    ! StepFailure
    ? &mut Allocator

Publishes this step's typed result for deferred consumers.

Method resolvedPath#

silk
pub effect fn resolvedPath(self: &mut Self, path: &String) -> ()
    ! StepFailure
    ? &mut Allocator

Publishes an external path obtained by this step. A cache hit is valid only while it exists. Consumers hash the selected file or tree, so changing its contents also invalidates them.

Method exec#

silk
pub effect fn exec(
    self: &mut Self,
    program: &Deferred<Path>,
    arguments: &[string],
  ) -> ProcessOutcome
    ! StepFailure
    ? &mut Allocator

Executes a declared program in the output directory with only the keyed environment.

Method execConfined#

silk
pub effect fn execConfined(
    self: &mut Self,
    launcher: &Deferred<Path>,
    program: &Deferred<Path>,
    arguments: &[string],
  ) -> ProcessOutcome
    ! StepFailure
    ? &mut Allocator

Executes a declared program through a declared sandbox launcher with only keyed reads.

Method shouldCompile#

silk
pub fn shouldCompile(self: &Self) -> bool

Whether this compilation should invoke the compiler after writing its request.

Runner#

silk
pub struct Runner

Executes an immutable graph with content-verified caching and bounded worker memory.

CompilationOutput#

silk
pub struct CompilationOutput

One compilation reached through the requested graph.

Field directory#

silk
pub directory: Path

Its cache directory, containing the complete request and emitted files.

Field compiled#

silk
pub compiled: bool

Whether the artifact was built, including prerequisites of a planning invocation.

StepOutput#

silk
pub struct StepOutput

One step the runner prepared.

Field identity#

silk
pub identity: usize

The identity of the step's handle.

Field directory#

silk
pub directory: Path

The step's cache directory.

Field volatile#

silk
pub volatile: bool

Whether the step runs every time.

Field compilation#

silk
pub compilation: bool

Whether the step is a compilation.

Field compiled#

silk
pub compiled: bool

Whether a compilation built its artifact, or only wrote its request.

Execution#

silk
pub struct Execution

Completed root outputs and every reachable compilation.

Field outputs#

silk
pub outputs: List<Path>

Cache directories in the order roots were requested.

Field compilations#

silk
pub compilations: List<CompilationOutput>

Reachable compilations, including tools needed by other steps.

Field steps#

silk
pub steps: List<StepOutput>

Every step the runner prepared, producers first.

Implementation Runner#

silk
impl Runner

Associated function make#

silk
pub effect fn make(root: Path, cache: Path, identity: &[u8]) -> Self
    ! OutOfMemoryError
    ? &mut Allocator

Sets the package root, cache directory, and identity of the task program and compiler. The caller must include both executables' content digests in identity.

Method linking#

silk
pub fn linking(self: Self, links: List<Link>) -> Self

Supplies the steps restored from a description, which their consumers name by identity.

Method memory#

silk
pub fn memory(self: Self, bytes: u64) -> Self

Limits the sum of running steps' memory estimates. A step larger than the budget runs alone.

Method parallelism#

silk
pub fn parallelism(self: Self, workers: usize) -> Self

Limits the number of worker fibers; zero selects one worker.

Method execute#

silk
pub effect fn execute(self: &Self, targets: &[StepHandle], compile: bool) -> Execution
    ! StepFailure | SpawnError | Cancelled
    ? &mut Allocator | &mut FileSystem | &mut HostInput

Resolves each key before running its step, executing prerequisites needed to discover file sets. Only requested steps and their declared inputs run. When compile is false, requested compilations write requests while prerequisite tools build.

recordDirectory#

silk
pub effect fn recordDirectory(cache: &Path) -> Path
  ! FileError | OutOfMemoryError
  ? &mut Allocator

Where the digests of unchanged inputs are recorded, beside the step outputs they key.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.

View the source of this page