IC Build

IC Build provides common Cargo/Wasm builds and retained artifact caches, moved from IC Testkit, and feature-safe Cargo grouping from Canic. The published 0.4 family is available on crates.io. The owning extraction issue tracks producer and consumer acceptance.

ic_build::artifacts owns exact Cargo input resolution, transactional artifact publication, retained records, Wasm caches, sessions, batch results and explicit maintenance. ic_build::cargo groups packages only when their resolved normal and build dependency trees match isolated resolution. Consumers own recipes, tools, output budgets, source custody, release identities and lifecycle. PocketIC stays in Testkit; complete-release admission stays in Canic.

Start with Build ownership and extraction. It records the inspected build paths, duplicated responsibilities, intended owners, retained safety boundaries and extraction sequence. Read the current handoff before implementation. The artifact API guide covers recipes, retained records, freshness, batching and explicit maintenance. Version 0.1.3 also provides temporary staging and bounded capture of producer outputs, with caller-owned qualification and publication.

The dependency direction is application adapters → IC Build → IC Host Tooling. IC Build must not depend on Canic, IcyDB, PocketIC or IC Testkit.

Use

Add the registry dependency to your host-side package:

[dependencies]
ic-build = "0.4"

Rust 1.91.0 or newer is required. Import the engine directly and keep the returned record alive while using its artifacts. With a prepared Cargo/Wasm toolchain and a caller-held source lease:

use ic_build::artifacts::{WasmBuildSpec, build_wasm_canisters_cached};
use std::path::Path;

fn build(workspace: &Path) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let target = workspace.join("target/canister-builds");
    let spec = WasmBuildSpec::new(workspace, &target, &["counter_canister"], "release")
        .with_cargo_profile_args(["--release", "--locked"]);
    let outcome = build_wasm_canisters_cached(&spec)?;
    let wasm = std::fs::read(&outcome.record().artifacts()[0])?;
    Ok(wasm)
}

Consumers select packages, profiles, environment and maintenance policy. Select IC Host 0.18 when passing OutputLimits or typed Host failures across IC Build's public grouping/capture boundary. The deployable-Wasm LTO guidance records whole-canister measurements and shows how a common adapter can apply full LTO through the existing API, with complete-application qualification before adopting a shared release default. Publication makes the engine available; #1 still tracks consumer acceptance, Canic production convergence and required native macOS qualification. See the artifact guide for source custody and retained-cache contracts.

Development

Shared Tooling 0.15.0 is pinned in .shared-tooling.snapshot; commands use this reviewed local snapshot. The Make interface owns common setup, formatting, hook installation and release entrypoints.

The virtual root Cargo manifest owns the workspace version, edition 2024, MSRV 1.91.0, common metadata and lints. The ic-build package inherits them and permits registry publication through the explicit tagged-release command. The library root exports the generic engine. The root lockfile records its selected dependencies; none depend on Testkit, PocketIC or Canic.

Cargo.toml                  # Virtual workspace and shared metadata
Cargo.lock                  # One selected graph
crates/ic-build/Cargo.toml   # Inherited package metadata; publish = true
crates/ic-build/src/lib.rs   # Generic engine modules

Prepare the declared development compiler and common tools explicitly:

rustup toolchain install --profile minimal --component rustfmt --target wasm32-unknown-unknown --no-self-update
make install-tools
cargo fetch --locked
make install-hooks

make install-tools also prepares the consumer-pinned cargo-set-version release editor from ci/release-tools.env through the canonical shared Cargo tool installer. make tools-check admits it offline; release adapters use that admitted executable directly. Global Cargo plugins are not setup prerequisites.

rust-toolchain.toml selects the existing Rust 1.99.0 development compiler, rustfmt, Clippy and its Wasm target independently of the qualified Linux library MSRV. Explicit setup reads that target from the toolchain file. The complete common toolset is prepared and checked on Linux x86-64. Interactive shells use the PATH selection in local developer setup. Fetch the selected workspace dependencies before the offline validation gate; installing developer tools does not populate this project cache. CI performs the same locked fetch on each host and retains its preparation log on failure. make test resolves the repository-selected compiler and passes its absolute path as RUSTC to the test command. Independent Cargo/Wasm fixtures therefore use the prepared compiler even outside this repository's toolchain selection.

The full local delivery suite is make ci plus make lint check-secrets on Linux after explicit tool setup. CI runs lint/security on Linux and the package gate on Linux x86-64, macOS 15 Apple Silicon and macOS 15 Intel. It explicitly prepares the minimum compiler from Cargo.toml. Failed native jobs use the shared evidence action. These jobs are configured but have not yet qualified the extracted engine on native macOS.

Keep Cargo.lock tracked: the full shared pin checker enforces lockfile custody as well as root/member dependency inheritance. Each dependency graph is checked with its selected lockfile; validation never changes package versions.

make cloc reports workspace Rust LOC. The transferred tests execute real filesystem and process boundaries, Cargo metadata and Wasm compilation, alongside synthetic producer fixtures for failure and concurrency cases. These checks passed on Linux; native macOS qualification remains pending. The release and publication guide describes the consumer adapters, exact tagged-source admission and retained recovery evidence. The adapter fixtures qualify command behavior; they do not establish publication or native macOS support. Published-version custody is recorded in the handoff.

Existing Testkit v1 stamp bytes, digest domains and .ic-testkit cache/lock names are retained unchanged during the ownership move. There is one reader and no automatic cache migration or cleanup. Returned records must remain alive until their artifact paths have finished being consumed.

The transactional transform example composes a caller-selected, admitted tool with the generic cache; it chooses its own recipe and maintenance policy. Follow AGENTS.md and the ownership design for further convergence of Canic's complete-build mechanics.

Coordination

The design owns architectural decisions, not issue status. GitHub issues in the owning GitHub repository remain the sole follow-up tracker. Changes in Canic, Testkit, IcyDB or Shared Tooling require authorization for that repository. Consumer migrations and cleanup require their own scoped authorization.