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 child environment, selected inherited 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 fn new( workspace_root: &Path, target_dir: &Path, packages: &[&str], profile_target_dir: &str, ) -> Self

Describe one Cargo build targeting wasm32-unknown-unknown.

profile_target_dir is Cargo’s output subdirectory, such as debug, release, or the name supplied to --profile. It must be one normal path component so artifacts remain inside their target directories. It must match the profile selected by with_cargo_profile_args: the default, dev, and test use debug; release and bench use release. 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.

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_profile_args<I, S>(self, arguments: I) -> Self

where I: IntoIterator<Item = S>, S: AsRef<OsStr>,

Set Cargo profile and feature arguments used for the build and fingerprint.

Workspace, package, compilation target, and target-directory overrides are rejected before resolution or acquisition; use this specification’s corresponding fields and builders. --config overrides are also rejected: use Cargo’s discovered configuration files or explicit environment overrides so resolution and execution share tracked inputs. Help and build-graph flags are rejected because they exit successfully without building. The selected profile must match profile_target_dir; declaring an output directory does not select a Cargo profile. Binary, example, test, bench, and all-target selectors are rejected to preserve structural library/example selection. Use Self::with_example for a named example. --lib is supported only for the default library.

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

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

Merge deterministic OS-native child-process environment overrides.

Later values replace earlier values for the same name, including across calls. An empty iterator preserves previously configured overrides.

CARGO_TARGET_DIR is owned by the cache configuration and cannot be overridden here. Conflicting specifications fail before acquisition.

pub fn with_inherited_env<I, S>(self, names: I) -> Self

where I: IntoIterator<Item = S>, S: Into<OsString>,

Add ambient environment names whose current values affect the build.

Common Rust and Cargo toolchain variables are included automatically. Callers must declare application-specific variables read by build scripts.

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, use with_extra_env([("RUSTC", program)]); 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: SharedIncrementalTargetPrunePolicy, 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: ArtifactCachePrunePolicy) -> 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: ArtifactCachePrunePolicy, 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<ArtifactCachePrunePolicy>

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

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

Minimum interval between exact-entry retention attempts, when scheduled.

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, f: &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