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#
pub type Options = Standard.OptionsThe shared target, optimization, and debug command-line options.
Optimize#
pub type Optimize = Standard.OptimizeA compilation or defining package's optimization mode.
Compilation#
pub type Compilation = Compilations.CompilationOne compilation; its settings freeze when an artifact or step handle is first requested.
Package#
pub type Package = Packages.PackageBackend settings and parameters for a declared package.
Deferred#
pub type Deferred = Steps.DeferredA typed value that only the running step can resolve.
Step#
pub type Step = Steps.StepCustom work with a declared key and a constrained make context.
Key#
pub type Key = Steps.KeyThe inputs that determine a step's cached outputs.
Make#
pub type Make = Steps.MakeThe declared inputs and output directory available while a step executes.
Run#
pub type Run = Runs.RunA process invocation with declared inputs, environment, outputs, and captured values.
WriteFiles#
pub type WriteFiles = Files.WriteFilesText files generated from known or deferred values.
BuildError#
pub type BuildError = StepFailure | SpawnError | CancelledA failure to prepare, schedule, run, or publish a build graph.
Build#
pub struct BuildRequested root steps and compilations, executed only by compile or write.
Artifact#
pub struct ArtifactThe paths of a completed compilation, including its stable request file.
Field name#
pub name: StringThe artifact name chosen by its compilation.
Field path#
pub path: PathThe compilation's fixed output path, or a custom step's cache output path.
Field request#
pub request: Option<Path>The stable request file, when this root is a compilation.
Built#
pub struct BuiltCompleted root artifacts in the order they were added to a build.
Field artifacts#
pub artifacts: List<Artifact>The completed artifacts, with their published request files.
Planned#
pub struct PlannedPublished requests and intended output paths, without compiling the requested artifacts.
Field artifacts#
pub artifacts: List<Artifact>The planned output paths. These artifacts are not available to launch or copy.
Implementation Build#
impl BuildMethod when#
pub effect fn when<'env, E, ? R>(
self: Self,
condition: bool,
transform: once effect fn<'env>(Self) -> Self ! E ? R,
) -> Self
! E
? RApplies transform when condition is true, returning the original value otherwise.
Associated function make#
pub effect fn make() -> Self
! BuildError
? &mut Allocator | &mut HostInput | &mut FileSystemStarts a graph in the current package, keying the executable that constructs it.
Associated function at#
pub effect fn at(root: Path, identity: &[u8]) -> Self
! BuildError
? &mut AllocatorStarts a graph at an explicit root with the content identity of its constructing program.
Method add#
pub effect fn add(self: Self, compilation: Compilation) -> Self
! BuildError
? &mut AllocatorAdds a requested compilation. Settings freeze when execution starts or an artifact is used. Dependencies follow its deferred inputs.
Method addStep#
pub effect fn addStep(self: Self, step: StepHandle, output: string) -> Self
! BuildError
? &mut AllocatorAdds custom work as a requested root. The named output becomes one returned artifact.
Method embed#
pub effect fn embed(self: Self, name: string, input: Deferred<Path>) -> Self
! BuildError
? &mut AllocatorEmbeds 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#
pub fn memoryBudget(self: Self, bytes: u64) -> SelfBounds the sum of estimates for running steps; a larger single step runs alone.
Method parallelism#
pub fn parallelism(self: Self, workers: usize) -> SelfSets the maximum number of worker fibers. Zero requests one worker.
Method compile#
pub effect fn compile(self: Self) -> Built
! BuildError
? &mut Allocator | &mut FileSystem | &mut HostInputRuns the requested graph, publishes complete requests, and returns the resulting artifacts.
Method write#
pub effect fn write(self: Self) -> Planned
! BuildError
? &mut Allocator | &mut FileSystem | &mut HostInputResolves dependencies and publishes requests, stopping before requested compilations run. Prerequisite tool compilations still build. Failures leave previously published requests intact.
Method perform#
pub effect fn perform(self: Self, compile: bool) -> Built
! BuildError
? &mut Allocator | &mut FileSystem | &mut HostInputRuns the graph in this process. The compiler calls this for a described graph.
Method describe#
pub effect fn describe(self: &Self, compile: bool) -> Option<GraphDescription>
! BuildError
? &mut AllocatorDescribes 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#
pub effect fn restore(description: &GraphDescription) -> Self
! BuildError
? &mut Allocator | &mut FileSystemRestores a described graph without running any of its steps.
Implementation Built#
impl BuiltMethod outcome#
pub effect fn outcome(self: &Self) -> Outcome
! BuildError
? &mut AllocatorDescribes the completed artifacts for the task program that requested them.
Job#
pub struct JobWhat a custom step's executor runs: one whole graph, with the program's inputs as they were when the build was requested.
Executor#
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#
pub effect fn executor() -> Executor
! OutOfMemoryError
? &mut AllocatorMakes an executor for a custom step. The step registration calls this.
Implementation Built#
impl BuiltMethod launch#
pub effect fn launch(self: &Self, arguments: &[string]) -> ()
! BuildError | TaskError
? &mut Allocator | &mut FileSystem | &mut HostInputLaunches 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#
pub effect fn launchAt(self: &Self, index: usize, arguments: &[string]) -> ()
! BuildError | TaskError
? &mut Allocator | &mut FileSystem | &mut HostInputLaunches artifact index, passing runner arguments, the artifact path, then arguments.
A nonzero process status is preserved in TaskError.status.
Method write#
pub effect fn write(self: Self, directory: string) -> Self
! BuildError
? &mut Allocator | &mut FileSystem | &mut HostInputCopies 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.