silk.build.graph.

Build graphs that publish complete compilation requests and return their artifacts.

Import as Build with import silk.build.graph { Build }.

Public declarations: 18.

Options#

silk
pub type Options = Standard.Options

The shared target, optimization, and debug command-line options.

Optimize#

silk
pub type Optimize = Standard.Optimize

A compilation or defining package's optimization mode.

Compilation#

silk
pub type Compilation = Compilations.Compilation

One compilation; its settings freeze when an artifact or step handle is first requested.

Package#

silk
pub type Package = Packages.Package

Backend settings and parameters for a declared package.

Deferred#

silk
pub type Deferred = Steps.Deferred

A typed value that only the running step can resolve.

Step#

silk
pub type Step = Steps.Step

Custom work with a declared key and a constrained make context.

Key#

silk
pub type Key = Steps.Key

The inputs that determine a step's cached outputs.

Make#

silk
pub type Make = Steps.Make

The declared inputs and output directory available while a step executes.

Run#

silk
pub type Run = Runs.Run

A process invocation with declared inputs, environment, outputs, and captured values.

WriteFiles#

silk
pub type WriteFiles = Files.WriteFiles

Text files generated from known or deferred values.

BuildError#

silk
pub type BuildError = StepFailure | SpawnError | Cancelled

A failure to prepare, schedule, run, or publish a build graph.

Build#

silk
pub struct Build

Requested root steps and compilations, executed only by compile or write.

Artifact#

silk
pub struct Artifact

The paths of a completed compilation, including its stable request file.

Field name#

silk
pub name: String

The artifact name chosen by its compilation.

Field path#

silk
pub path: Path

The compilation's fixed output path, or a custom step's cache output path.

Field request#

silk
pub request: Option<Path>

The stable request file, when this root is a compilation.

Built#

silk
pub struct Built

Completed root artifacts in the order they were added to a build.

Field artifacts#

silk
pub artifacts: List<Artifact>

The completed artifacts, with their published request files.

Planned#

silk
pub struct Planned

Published requests and intended output paths, without compiling the requested artifacts.

Field artifacts#

silk
pub artifacts: List<Artifact>

The planned output paths. These artifacts are not available to launch or copy.

Implementation Build#

silk
impl Build

Method when#

silk
pub effect fn when<'env, E, ? R>(
    self: Self,
    condition: bool,
    transform: once effect fn<'env>(Self) -> Self ! E ? R,
  ) -> Self
    ! E
    ? R

Applies transform when condition is true, returning the original value otherwise.

Associated function make#

silk
pub effect fn make() -> Self
    ! BuildError
    ? &mut Allocator | &mut HostInput | &mut FileSystem

Starts a graph in the current package, keying the executable that constructs it.

Associated function at#

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

Starts a graph at an explicit root with the content identity of its constructing program.

Method add#

silk
pub effect fn add(self: Self, compilation: Compilation) -> Self
    ! BuildError
    ? &mut Allocator

Adds a requested compilation. Settings freeze when execution starts or an artifact is used. Dependencies follow its deferred inputs.

Method addStep#

silk
pub effect fn addStep(self: Self, step: StepHandle, output: string) -> Self
    ! BuildError
    ? &mut Allocator

Adds custom work as a requested root. The named output becomes one returned artifact.

Method embed#

silk
pub effect fn embed(self: Self, name: string, input: Deferred<Path>) -> Self
    ! BuildError
    ? &mut Allocator

Embeds a file as a generated module in every root compilation. The file stays deferred and its producer becomes a dependency of each compilation. A compilation already used as another step's input has frozen settings and cannot be changed.

Method memoryBudget#

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

Bounds the sum of estimates for running steps; a larger single step runs alone.

Method parallelism#

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

Sets the maximum number of worker fibers. Zero requests one worker.

Method compile#

silk
pub effect fn compile(self: Self) -> Built
    ! BuildError
    ? &mut Allocator | &mut FileSystem | &mut HostInput

Runs the requested graph, publishes complete requests, and returns the resulting artifacts.

Method write#

silk
pub effect fn write(self: Self) -> Planned
    ! BuildError
    ? &mut Allocator | &mut FileSystem | &mut HostInput

Resolves dependencies and publishes requests, stopping before requested compilations run. Prerequisite tool compilations still build. Failures leave previously published requests intact.

Method perform#

silk
pub effect fn perform(self: Self, compile: bool) -> Built
    ! BuildError
    ? &mut Allocator | &mut FileSystem | &mut HostInput

Runs the graph in this process. The compiler calls this for a described graph.

Method describe#

silk
pub effect fn describe(self: &Self, compile: bool) -> Option<GraphDescription>
    ! BuildError
    ? &mut Allocator

Describes the graph for the compiler to run. Answers nothing when the graph holds a custom step, which only this program can run.

Associated function restore#

silk
pub effect fn restore(description: &GraphDescription) -> Self
    ! BuildError
    ? &mut Allocator | &mut FileSystem

Restores a described graph without running any of its steps.

Implementation Built#

silk
impl Built

Method outcome#

silk
pub effect fn outcome(self: &Self) -> Outcome
    ! BuildError
    ? &mut Allocator

Describes the completed artifacts for the task program that requested them.

Job#

silk
pub struct Job

What a custom step's executor runs: one whole graph, with the program's inputs as they were when the build was requested.

Executor#

silk
pub type Executor = Arc<Mutex<Option<Pending<Job, Built, BuildError>>>>

Runs graphs in this process. Only a registered custom step creates one, so a program whose graphs the compiler can run carries no runner.

executor#

silk
pub effect fn executor() -> Executor
  ! OutOfMemoryError
  ? &mut Allocator

Makes an executor for a custom step. The step registration calls this.

Implementation Built#

silk
impl Built

Method launch#

silk
pub effect fn launch(self: &Self, arguments: &[string]) -> ()
    ! BuildError | TaskError
    ? &mut Allocator | &mut FileSystem | &mut HostInput

Launches the single completed artifact with inherited terminal streams and environment. A request's explicit runner takes precedence; WASI defaults to wasmtime run. Use launchAt to choose an artifact from a build with several roots.

Method launchAt#

silk
pub effect fn launchAt(self: &Self, index: usize, arguments: &[string]) -> ()
    ! BuildError | TaskError
    ? &mut Allocator | &mut FileSystem | &mut HostInput

Launches artifact index, passing runner arguments, the artifact path, then arguments. A nonzero process status is preserved in TaskError.status.

Method write#

silk
pub effect fn write(self: Self, directory: string) -> Self
    ! BuildError
    ? &mut Allocator | &mut FileSystem | &mut HostInput

Copies completed artifacts, generated headers, and import libraries to directory, preserving executable permissions. The returned paths name the copies; their request files remain at their build locations.

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