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#
pub struct StepErrorA build graph or step violated its declared input or output contract.
Field message#
pub message: StringThe diagnostic describing the refused operation.
Implementation Debug for StepError#
impl Debug for StepErrorOperation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterStepFailure#
pub type StepFailure = StepError
| AtomicWriteError
| FileError
| ProcessError
| HostInputError
| SchemaError
| WriterError
| OutOfMemoryErrorFailures preserved by the build runner and its file, process, and serialization operations.
Deferred#
pub struct Deferred<T>A typed reference to a source, a known value, or a step result. Only Make resolves it.
describedPath#
pub static fn describedPath(input: Description) -> Deferred<Path>Describes an input during static plan construction without allocating a graph node.
sourcePath#
pub static fn sourcePath(path: string<'static>) -> Deferred<Path>Names a package-relative file during static plan construction.
suppliedPath#
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>#
impl<T> Deferred<T>Associated function fromDescription#
pub fn fromDescription(input: Description) -> Deferred<Path>Retains a standard-action description already read by runtime graph construction.
Method description#
pub static fn description(self: &Self) -> DescriptionReads the static description; runtime deferred values cannot enter a package plan.
Implementation Deferred<T>#
impl<T> Deferred<T>Method copy#
pub effect fn copy(self: &Self) -> Self
! OutOfMemoryError
? &mut AllocatorRetains a deferred reference without evaluating it or starting its producer.
Implementation Deferred<T>#
impl<T> Deferred<T>Associated function source#
pub effect fn source(path: string) -> Deferred<Path>
! OutOfMemoryError
? &mut AllocatorNames a path relative to the package root. The runner refuses paths that leave that root.
Associated function external#
pub effect fn external(path: string) -> Deferred<Path>
! OutOfMemoryError
? &mut AllocatorNames an explicitly supplied absolute host path.
Implementation Schema for Deferred<T>#
impl<T> Schema for Deferred<T>A deferred value travels in a step description as its reference, never as its result.
Operation read#
effect fn read<R: SchemaReader>(reader: &mut R) -> Self
! Issue | OutOfMemoryError
? &mut AllocatorOperation write#
effect fn write<W: SchemaWriter>(self: &Self, writer: &mut W) -> ()
! Issue | WriterError | OutOfMemoryError
? &mut Writer | &mut AllocatorImplementation Deferred<T>#
impl<T: Schema> Deferred<T>Associated function value#
pub effect fn value(value: T) -> Self
! StepFailure
? &mut AllocatorCaptures a known value without exposing a way to read deferred results while constructing the graph.
Method map#
pub effect fn map<
U: Schema + Transferable + 'static,
F: fn<'static>(T) -> U + Transferable + 'static
>(self: Self, transform: F) -> Deferred<U>
! StepFailure
? &mut AllocatorApplies 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#
pub struct KeyThe complete inputs of a step. Its methods record inputs without reading files or running work.
Implementation Key#
impl KeyAssociated function collecting#
pub fn collecting() -> SelfStarts an empty key, for collecting what a described step declares.
Method producers#
pub effect fn producers(self: &Self) -> List<StepHandle>
! OutOfMemoryError
? &mut AllocatorRetains every step whose output this key declares as an input.
Method bytes#
pub effect fn bytes(self: &mut Self, value: &[u8]) -> ()
! OutOfMemoryError
? &mut AllocatorAdds bytes with a length prefix so adjacent values cannot collide.
Method text#
pub effect fn text(self: &mut Self, value: string) -> ()
! OutOfMemoryError
? &mut AllocatorAdds text to the step's identity.
Method file#
pub effect fn file(self: &mut Self, value: &Deferred<Path>) -> ()
! OutOfMemoryError
? &mut AllocatorDeclares one readable file; its bytes or producer key participate in this step's key.
Method toolchain#
pub effect fn toolchain(self: &mut Self, compiler: &Deferred<Path>) -> ()
! OutOfMemoryError
? &mut AllocatorHashes 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#
pub effect fn tree(self: &mut Self, value: &Deferred<Path>) -> ()
! OutOfMemoryError
? &mut AllocatorDeclares a readable directory tree, including its names and file contents.
Method packageTree#
pub effect fn packageTree(self: &mut Self, value: &Deferred<Path>) -> ()
! OutOfMemoryError
? &mut AllocatorDeclares package contents, excluding the root build directory and .git metadata.
Generated inputs below build must be declared separately through their producer.
Method value#
pub effect fn value<T>(self: &mut Self, value: &Deferred<T>) -> ()
! OutOfMemoryError
? &mut AllocatorDeclares a typed value; a produced value contributes its producer key before it exists.
Method files#
pub effect fn files(self: &mut Self, paths: &Deferred<List<String>>) -> ()
! OutOfMemoryError
? &mut AllocatorDeclares 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#
pub effect fn trees(self: &mut Self, paths: &Deferred<List<String>>) -> ()
! OutOfMemoryError
? &mut AllocatorDeclares deferred absolute directory paths, hashing each complete tree before cache lookup.
Method packageTrees#
pub effect fn packageTrees(self: &mut Self, paths: &Deferred<List<String>>) -> ()
! OutOfMemoryError
? &mut AllocatorDeclares deferred package directories, excluding each root's build and version-control data.
Method environment#
pub effect fn environment(self: &mut Self, name: string) -> ()
! OutOfMemoryError
? &mut AllocatorDeclares an environment variable. Its presence and value enter the key and the child environment.
Method passEnvironment#
pub effect fn passEnvironment(self: &mut Self, name: string) -> ()
! OutOfMemoryError
? &mut AllocatorPasses 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#
pub fn always(self: &mut Self) -> ()Runs this step and every consumer on every invocation, even when their keys are unchanged.
Step#
pub interface StepWork a root task explicitly adds to its build graph. Package plans cannot introduce custom implementations.
Operation prepare#
effect fn prepare(self: Self) -> Self
! StepFailure
? &mut AllocatorMaterializes a static description before its inputs are recorded. This phase allocates only.
Operation key#
effect fn key(self: &Self, key: &mut Key) -> () ! StepFailure ? &mut AllocatorRecords everything the work reads. It must perform no filesystem or process operations.
Operation make#
effect fn make(self: &Self, make: &mut Make) -> () ! StepFailure ? &mut AllocatorProduces the outputs through Make, which rejects undeclared file and value inputs.
Operation memory#
fn memory(self: &Self) -> u64The estimated peak memory, used to bound concurrently running steps. Defaults to 256 MiB.
Operation compilation#
fn compilation(self: &Self) -> boolWhether this step writes a compilation request and can stop before invoking the compiler.
Provision#
pub struct ProvisionWhere a step that another process ran left its outputs.
Field directory#
pub directory: StringThe step's cache directory, named by its key.
Field volatile#
pub volatile: boolWhether the step runs every time, so its consumers do too.
Field compilation#
pub compilation: boolWhether the step is a compilation.
Field compiled#
pub compiled: boolWhether a compilation built its artifact, or only wrote its request.
Implementation Schema for Provision#
impl Schema for ProvisionOperation spec#
static fn spec() -> Spec<Provision>StepHandle#
pub struct StepHandleAn owned step registered in a graph. Several deferred outputs may retain the same step.
StepDescription#
pub struct StepDescriptionOne step of a described graph: what the task program hands to the compiler.
Field node#
pub node: u64The step's identity within its description.
Field kind#
pub kind: StringThe kind of standard step.
Field step#
pub step: StringThe step's own JSON description.
Implementation Schema for StepDescription#
impl Schema for StepDescriptionOperation spec#
static fn spec() -> Spec<StepDescription>Link#
pub struct LinkA described step's identity and the step restored for it.
Implementation StepHandle#
impl StepHandleMethod copy#
pub fn copy(self: &Self) -> SelfRetains the step without copying or running its work.
Method identity#
pub fn identity(self: &Self) -> usizeThe step's identity among the live steps of this process.
Associated function described#
pub effect fn described(kind: string, step: Bytes, producers: List<StepHandle>) -> Self
! OutOfMemoryError
? &mut AllocatorHolds 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#
pub effect fn provided(provision: Provision) -> Self
! OutOfMemoryError
? &mut AllocatorHolds a step that already ran, as the directory its outputs are in.
Method description#
pub effect fn description(self: &Self) -> Option<StepDescription>
! StepFailure
? &mut AllocatorThe step's description, when it is a standard step that has not been restored.
Method install#
pub effect fn install(self: &Self, restored: &StepHandle) -> ()
! OutOfMemoryError
? &mut AllocatorGives this step the work, or the provision, of the step restored from its description.
Associated function linkedSteps#
pub effect fn linkedSteps(links: &[Link]) -> List<StepHandle>
! OutOfMemoryError
? &mut AllocatorThe steps restored for a description, in its order.
Associated function describeAll#
pub effect fn describeAll(targets: &[StepHandle]) -> Option<List<StepDescription>>
! StepFailure
? &mut AllocatorDescribes 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#
pub effect fn executorOf(targets: &[StepHandle]) -> Option<Graphs.Executor>
! OutOfMemoryError
? &mut AllocatorFinds the executor of a custom step among these steps and everything they read.
Associated function restoreAll#
pub effect fn restoreAll(steps: &[StepDescription]) -> List<Link>
! OutOfMemoryError
? &mut AllocatorRestores described steps without running them, and answers the link of each.
Associated function linked#
pub fn linked(links: &[Link], node: u64) -> Option<StepHandle>Finds the step restored for node of a description.
Method output#
pub effect fn output(self: &Self, name: string) -> Deferred<Path>
! StepError | OutOfMemoryError
? &mut AllocatorNames one file that this step will produce. The path must stay below its output directory.
Method resolvedPath#
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#
pub effect fn valueFile<T: Schema>(self: &Self, name: string) -> Deferred<T>
! StepError | OutOfMemoryError
? &mut AllocatorNames a typed JSON output published by Make.valueFile during this step.
Method value#
pub effect fn value<T: Schema>(self: &Self) -> Deferred<T>
! OutOfMemoryError
? &mut AllocatorNames the typed value published by Make.value during this step.
Implementation Step#
impl StepAssociated function register#
pub effect fn register<T: Step + Transferable + 'static>(input: T) -> StepHandle
! StepFailure
? &mut AllocatorTakes ownership of custom work and records its key without running it. Outputs retain this handle.
Associated function describe#
pub effect fn describe<T: Step + Schema>(kind: string, input: T) -> StepHandle
! StepFailure
? &mut AllocatorHolds a standard step as its description, without its work. kind names how the compiler
restores it.
Associated function output#
pub effect fn output(step: &StepHandle, name: string) -> Deferred<Path>
! StepError | OutOfMemoryError
? &mut AllocatorNames an output of registered work, creating its dependency edge without running it.
Make#
pub struct MakeThe resolved inputs and output directory visible only while a step runs.
Implementation Make#
impl MakeMethod readWithin#
pub effect fn readWithin(self: &mut Self, tree: &Deferred<Path>, name: string) -> Bytes
! StepFailure
? &mut AllocatorReads one relative child of a directory declared with Key.tree.
Method glob#
pub effect fn glob(self: &mut Self, tree: &Deferred<Path>, pattern: string) -> List<Path>
! StepFailure
? &mut AllocatorLists files matching a package-relative glob within a declared tree.
The directory must have been declared with Key.tree or Key.packageTree.
Method requireOutput#
pub effect fn requireOutput(self: &mut Self, name: string) -> ()
! StepFailure
? &mut AllocatorVerifies that a process wrote a declared output before the runner publishes its cache entry.
Method path#
pub effect fn path(self: &Self, value: &Deferred<Path>) -> Path
! StepFailure
? &mut AllocatorResolves a file previously declared with Key.file or Key.tree.
Method producer#
pub effect fn producer<T>(self: &Self, value: &Deferred<T>) -> Option<String>
! StepFailure
? &mut AllocatorReturns a declared input's producer key, absent for source files and known values.
Method read#
pub effect fn read(self: &mut Self, value: &Deferred<Path>) -> Bytes
! StepFailure
? &mut AllocatorReads a file previously declared in the key; undeclared access fails before opening a file.
Method get#
pub effect fn get<T: Schema>(self: &mut Self, value: &Deferred<T>) -> T
! StepFailure
? &mut AllocatorResolves a typed value previously declared with Key.value.
Method output#
pub effect fn output(self: &Self, name: string) -> Path
! StepFailure
? &mut AllocatorReturns a path below this step's output directory, refusing traversal and absolute names.
Method readOutput#
pub effect fn readOutput(self: &mut Self, name: string) -> Bytes
! StepFailure
? &mut AllocatorReads a file produced inside this step's output directory, refusing paths outside it.
Method write#
pub effect fn write(self: &mut Self, name: string, bytes: &[u8]) -> ()
! StepFailure
? &mut AllocatorWrites a file below this step's output directory, creating its parent directories.
Method valueFile#
pub effect fn valueFile<T: Schema>(self: &mut Self, name: string, value: &T) -> ()
! StepFailure
? &mut AllocatorPublishes one named typed result as JSON for deferred consumers.
Method value#
pub effect fn value<T: Schema>(self: &mut Self, value: &T) -> ()
! StepFailure
? &mut AllocatorPublishes this step's typed result for deferred consumers.
Method resolvedPath#
pub effect fn resolvedPath(self: &mut Self, path: &String) -> ()
! StepFailure
? &mut AllocatorPublishes 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#
pub effect fn exec(
self: &mut Self,
program: &Deferred<Path>,
arguments: &[string],
) -> ProcessOutcome
! StepFailure
? &mut AllocatorExecutes a declared program in the output directory with only the keyed environment.
Method execConfined#
pub effect fn execConfined(
self: &mut Self,
launcher: &Deferred<Path>,
program: &Deferred<Path>,
arguments: &[string],
) -> ProcessOutcome
! StepFailure
? &mut AllocatorExecutes a declared program through a declared sandbox launcher with only keyed reads.
Method shouldCompile#
pub fn shouldCompile(self: &Self) -> boolWhether this compilation should invoke the compiler after writing its request.
Runner#
pub struct RunnerExecutes an immutable graph with content-verified caching and bounded worker memory.
CompilationOutput#
pub struct CompilationOutputOne compilation reached through the requested graph.
Field directory#
pub directory: PathIts cache directory, containing the complete request and emitted files.
Field compiled#
pub compiled: boolWhether the artifact was built, including prerequisites of a planning invocation.
StepOutput#
pub struct StepOutputOne step the runner prepared.
Field identity#
pub identity: usizeThe identity of the step's handle.
Field directory#
pub directory: PathThe step's cache directory.
Field volatile#
pub volatile: boolWhether the step runs every time.
Field compilation#
pub compilation: boolWhether the step is a compilation.
Field compiled#
pub compiled: boolWhether a compilation built its artifact, or only wrote its request.
Execution#
pub struct ExecutionCompleted root outputs and every reachable compilation.
Field outputs#
pub outputs: List<Path>Cache directories in the order roots were requested.
Field compilations#
pub compilations: List<CompilationOutput>Reachable compilations, including tools needed by other steps.
Field steps#
pub steps: List<StepOutput>Every step the runner prepared, producers first.
Implementation Runner#
impl RunnerAssociated function make#
pub effect fn make(root: Path, cache: Path, identity: &[u8]) -> Self
! OutOfMemoryError
? &mut AllocatorSets 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#
pub fn linking(self: Self, links: List<Link>) -> SelfSupplies the steps restored from a description, which their consumers name by identity.
Method memory#
pub fn memory(self: Self, bytes: u64) -> SelfLimits the sum of running steps' memory estimates. A step larger than the budget runs alone.
Method parallelism#
pub fn parallelism(self: Self, workers: usize) -> SelfLimits the number of worker fibers; zero selects one worker.
Method execute#
pub effect fn execute(self: &Self, targets: &[StepHandle], compile: bool) -> Execution
! StepFailure | SpawnError | Cancelled
? &mut Allocator | &mut FileSystem | &mut HostInputResolves 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#
pub effect fn recordDirectory(cache: &Path) -> Path
! FileError | OutOfMemoryError
? &mut AllocatorWhere 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.