canic-host 0.32.6

Host-side build, install, fleet, and release-set library for Canic workspaces
Documentation

canic-host

Host-side build, install, fleet, and thin-root staging tooling for Canic workspaces.

When to use it

Use this crate directly when you need:

  • Canic build/install backend code in CI or local automation
  • root staging from published backend APIs
  • the lower-level host library surface without cloning the full repo

For normal local setup, use the tagged repo installer script:

curl -fsSL https://raw.githubusercontent.com/dragginzgame/canic/v0.32.6/scripts/dev/install_dev.sh | bash

That script bootstraps Rust when needed and installs the pinned internal toolchain, the canic CLI, wasm/Candid utilities, and dfx when missing. This README documents the lower-level host library surface.

What this crate is not

This crate is not a general deployment framework and it is not the main Canic application facade. It owns host-side build/install/fleet/staging utilities for standard Canic root/bootstrap/store flows. For normal operator use, prefer canic build, canic install, and other canic commands.

It is also separate from:

  • canic-backup, which owns backup/restore manifests, journals, topology snapshots, backup layout validation, and restore planning.
  • canic-core and canic-control-plane, which run inside canisters or provide canister-runtime support. canic-host runs on the operator machine and may call Cargo, dfx, and the local filesystem.

Public thin-root flow:

  • build visible canister artifacts through the backend builder used by canic build
  • build the implicit bootstrap wasm_store through the backend builder used by canic build wasm_store
  • emit the root staging manifest under .dfx/<network>/canisters/root/
  • stage the ordinary fleet artifacts into root
  • resume root bootstrap
  • drive local root install, including one clean local dfx restart attempt when dfx ping local fails

Build profile selection:

  • CANIC_WASM_PROFILE=debug builds raw debug wasm
  • CANIC_WASM_PROFILE=fast builds the middle shrunk local/test/demo lane
  • CANIC_WASM_PROFILE=release builds the shipping/install lane

If unset, backend builds default to release.

When the Rust workspace root and DFX/project root differ, set both:

  • CANIC_WORKSPACE_ROOT for Cargo, canic.toml, and canister manifests
  • CANIC_DFX_ROOT for dfx.json, .dfx, and emitted artifacts

If canister crates live outside the default fleets/ directory, host discovery first tries Cargo workspace metadata. No extra config is needed when package names follow canister_<role>, even in nested paths.

If you need to override discovery explicitly, set:

  • CANIC_CANISTERS_ROOT for the canister crate root relative to CANIC_WORKSPACE_ROOT

or point CANIC_CONFIG_PATH at the real canic.toml path and host discovery will infer the canister-manifest root from that config location.

For canic install, the implicit network default is always local; use --network <name> for one command against another network. The public CLI requires the fleet name as the first positional argument and uses fleets/<name>/canic.toml unless --config <path> is passed.

If a package name does not follow canister_<role>, declare the role mapping in Cargo.toml:

[package.metadata.canic]
role = "project_ledger"