Struct WasmBuildSpec 

pub struct WasmBuildSpec { /* private fields */ }

Complete caller-owned description of one cacheable Cargo Wasm build.

The selected package graph, sources, semantic workspace projection, Cargo configuration, Rust toolchain files, target, profile arguments, explicit complete child environment and additional watched inputs contribute to the build fingerprint. The complete workspace manifest and lockfile remain conservative mutation-validation inputs.

Implementations

impl WasmBuildSpec

pub const fn with_cargo_message_bytes(self, maximum: usize) -> Self

Set the maximum bytes in one Cargo build message, including its newline.

The default is 16 MiB. This decoding budget does not affect fingerprints or impose a build deadline. Overflow refuses publication after Cargo finishes; diagnostics continue streaming and the child is not terminated.

pub fn new<I, K, V>( workspace_root: &Path, target_dir: &Path, packages: &[&str], environment: I, ) -> Self

where I: IntoIterator<Item = (K, V)>, K: Into<OsString>, V: Into<OsString>,

Describe one Cargo build targeting wasm32-unknown-unknown.

The output subdirectory is derived from Self::with_cargo_selection: the default, dev, and test use debug; release and bench use release; custom profiles use their names. The derived directory must be one normal path component so artifacts remain inside their targets. Relative workspace_root and exact target_dir paths are resolved from the caller’s working directory. Shared targets are workspace-relative. Package names are sorted and deduplicated for identity, discovery, Cargo invocation, and artifact paths. Misses share the workspace-relative target/ic-testkit-incremental Cargo target by default. Use Self::with_isolated_builds when compiler state must be independent, and select retention limits explicitly. By default, acquisition builds package libraries with Cargo’s --lib flag. Use Self::with_example for one named cdylib example. Each default-library package must declare a cdylib with Cargo’s default library name: package hyphens become underscores. Artifact paths use that admitted name; genuinely renamed libraries are refused.

environment is the complete environment for probes and builds; child inheritance is cleared. Select PATH, HOME/CARGO_HOME, Rustup and build inputs at the caller as required. CARGO and RUSTC in this map select the initial tool programs; otherwise the literal programs cargo/rustc are used.

pub fn with_example(self, name: impl Into<String>) -> Self

Select one named cdylib example instead of the default package library.

Requires exactly one package. Metadata must declare that exact example; its selection contributes to identity and outputs live under examples/. Raw example/other-target selectors in profile arguments remain refused.

pub fn example(&self) -> Option<&str>

Borrow the explicit example selection, if this is not a library recipe.

pub fn cargo_build_command(&self) -> Result<Command, WasmBuildError>

Prepare this recipe’s Cargo command without starting a process or cache.

External execution uses target_dir directly; cache/maintenance choices are not executed. Resolve inputs first and borrow their admitted output paths, retain source/target custody, execute this command with caller-owned deadline/cancellation/cleanup, and validate inputs before capturing outputs. Keep the selected arguments and environment intact. Command success alone does not admit an artifact or release.

Errors

Returns invalid selections or target-directory resolution errors.

pub fn with_cargo_selection(self, selection: CargoSelection) -> Self

Replace typed Cargo profile, feature and network/lock selections.

The same selection configures metadata, builds and cache identity. Package, target, output paths and diagnostics remain owned by this specification.

pub fn with_environment<I, K, V>(self, environment: I) -> Self

where I: IntoIterator<Item = (K, V)>, K: Into<OsString>, V: Into<OsString>,

Replace the complete environment used by identity probes, metadata and builds.

Inheritance is cleared. Absent names stay absent; duplicate names use the last supplied value. Consumers own capture, filtering and recapture policy. Cargo target directories remain owned by the build specification.

pub const fn environment(&self) -> &BTreeMap<OsString, OsString>

Borrow the explicitly selected child environment; values may contain secrets.

pub fn with_additional_inputs<I, P>(self, paths: I) -> Self

where I: IntoIterator<Item = P>, P: Into<PathBuf>,

Add files or directories not discoverable through Cargo’s local dependency graph.

Relative paths are resolved from the workspace root. Use this for build script configuration, generated schemas, or other externally read inputs.

pub fn with_target(self, target: &str) -> Self

Override the Cargo compilation target.

pub fn with_cargo_program(self, program: impl Into<OsString>) -> Self

Override the Cargo executable used by metadata, identity, and build commands.

pub fn with_rustc_identity_program(self, program: impl Into<OsString>) -> Self

Override the Rust compiler executable used to fingerprint the toolchain.

This selects the -vV identity probe; it does not change the compiler invoked by Cargo or infer a compiler hidden inside a Cargo shim. Supply the actual shim-selected compiler. To configure Cargo and its identity together, select RUSTC in the complete environment; that explicit environment selection takes precedence over this identity-only setting.

pub fn with_shared_incremental_target( self, target_dir: impl Into<PathBuf>, ) -> Self

Build cache misses in one caller-owned shared Cargo incremental target.

Exact final Wasm artifacts still live in the content-addressed cache. The shared target is coordinated across processes but is never pruned or removed by IC Build after a failed build.

pub fn with_isolated_builds(self) -> Self

Build each fingerprint in a separate Cargo target instead of sharing state.

Select this when the test explicitly requires isolated compiler state. Retained targets need a caller-selected prune policy to bound disk use.

pub const fn with_shared_incremental_target_maintenance_at_most_every( self, policy: CacheRetentionLimits, minimum_interval: Duration, ) -> Self

Schedule caller-owned shared-target retention as part of acquisition.

This option requires shared incremental mode (the default). Every acquisition coordinates through that target, including an exact hit, so a missing target can be created and receive its first schedule marker immediately. Matching recent passes only check the marker; due passes reuse the acquisition’s exact Cargo input resolution before evaluating retention. The structured result is attached to the build record and emitted through observed progress. Maintenance failures fail the acquisition and do not record a successful schedule marker.

pub const fn with_shared_incremental_target_maintenance( self, config: SharedIncrementalTargetMaintenanceConfig, ) -> Self

Attach an explicit shared-target maintenance configuration.

This is the configurable counterpart to Self::with_shared_incremental_target_maintenance_at_most_every and supports strict or best-effort failure handling.

pub const fn with_prune_policy(self, policy: CacheRetentionLimits) -> Self

Apply cache retention under the build operation’s existing process lock.

Maintenance is best-effort: its structured result is attached to the successful build record and cannot turn ready artifacts into a build failure. The active fingerprint is protected from this pruning pass.

pub const fn with_prune_policy_at_most_every( self, policy: CacheRetentionLimits, minimum_interval: Duration, ) -> Self

Apply exact-entry retention at most once per minimum_interval.

The active fingerprint remains protected. A zero interval is equivalent to Self::with_prune_policy. The interval covers attempted maintenance, including a nonfatal failed attempt. This schedule never owns or scans a caller-owned shared incremental Cargo target.

pub fn workspace_root(&self) -> &Path

Workspace containing the selected Cargo packages.

pub fn target_dir(&self) -> &Path

Cargo target directory containing artifacts, lock, and stamps.

pub fn packages(&self) -> &[String]

Selected Cargo package names in sorted order, without duplicates.

pub const fn cache_mode(&self) -> &WasmBuildCacheMode

Cargo-target ownership mode used for cache misses.

pub const fn prune_policy(&self) -> Option<CacheRetentionLimits>

Exact-entry retention policy attached to this specification, when configured.

pub const fn prune_interval(&self) -> Option<Duration>

Positive minimum interval between exact-entry retention attempts.

Both always-run builders, including an explicit zero interval, return None. Use Self::prune_policy to distinguish disabled maintenance.

pub const fn shared_incremental_target_maintenance( &self, ) -> Option<SharedIncrementalTargetMaintenanceConfig>

Shared incremental-target maintenance attached to this specification.

Trait Implementations

impl Clone for WasmBuildSpec

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WasmBuildSpec

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for WasmBuildSpec

impl PartialEq for WasmBuildSpec

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for WasmBuildSpec