canic/
lib.rs

1//! Canic facade crate.
2//!
3//! This crate is the recommended dependency for downstream canister projects. It
4//! re-exports the public Canic runtime surface and provides the common macro entry points:
5//!
6//! - `build!` for configured canisters and generated local sandbox/probe config
7//! - `start!` for `lib.rs` (wire lifecycle hooks and export endpoints)
8//!
9//! For lower-level access, use the `api`, `dto`, and `memory` modules.
10//! These surfaces are for configured canister role packages. Shared runtime
11//! libraries should remain independent of Canic and use upstream crates such
12//! as `candid` or `ic-cdk` directly when they need generic IC types or APIs.
13//! Direct access to internal core modules is intentionally unsupported.
14
15pub mod access;
16pub mod api;
17#[cfg(any(not(target_arch = "wasm32"), test))]
18mod build_support;
19pub mod dto;
20pub mod ids;
21mod instructions;
22mod macros; // private implementation boundary
23pub mod prelude;
24pub mod protocol;
25
26#[doc(hidden)]
27pub mod __internal {
28    // NOTE:
29    // This module exists ONLY for macro expansion.
30    // Do NOT re-export canic_core publicly.
31    #[cfg(any(feature = "control-plane", feature = "wasm-store-canister"))]
32    pub use canic_control_plane as control_plane;
33    pub use canic_core as core;
34
35    pub mod cdk {
36        pub use canic_core::cdk::types::Principal;
37        pub use canic_core::cdk::{
38            export_candid, init, inspect_message, post_upgrade, query, update,
39        };
40
41        pub mod api {
42            pub use canic_core::cdk::api::{
43                canister_cycle_balance, canister_version, is_controller, msg_caller, time,
44            };
45        }
46    }
47
48    pub mod instructions {
49        pub use crate::instructions::format_instructions;
50    }
51}
52
53#[doc(hidden)]
54#[cfg(any(not(target_arch = "wasm32"), test))]
55pub mod __build {
56    pub use crate::build_support::{
57        METRICS_TIER_CORE, METRICS_TIER_PLACEMENT, METRICS_TIER_PLATFORM, METRICS_TIER_RUNTIME,
58        METRICS_TIER_SECURITY, METRICS_TIER_STORAGE, assert_canonical_role_contract_build,
59        config_attaches_role, config_contains_role, config_declares_role, config_fleet_name,
60        declared_package_metadata, declared_package_role,
61        emit_root_wasm_store_bootstrap_release_set, manifest_declares_workspace,
62        metrics_feature_enabled, metrics_profile_tier_mask, read_config_source_or_default,
63        required_package_metadata, required_package_role,
64    };
65}
66
67// -----------------------------------------------------------------------------
68// Sub-crates
69// -----------------------------------------------------------------------------
70pub use canic_core::memory;
71
72// -----------------------------------------------------------------------------
73// Re-exports
74// -----------------------------------------------------------------------------
75pub use canic_core::dto::error::Error;
76pub use canic_core::{impl_storable_bounded, impl_storable_unbounded};
77pub use canic_macros::{canic_query, canic_update};
78
79// -----------------------------------------------------------------------------
80// Constants
81// -----------------------------------------------------------------------------
82
83pub const CRATE_NAME: &str = env!("CARGO_PKG_NAME");
84pub const VERSION: &str = env!("CARGO_PKG_VERSION");
85pub const CANIC_WASM_CHUNK_BYTES: usize = canic_core::CANIC_WASM_CHUNK_BYTES;
86pub const CANIC_DEFAULT_UPDATE_INGRESS_MAX_BYTES: usize =
87    canic_core::ingress::payload::DEFAULT_UPDATE_INGRESS_MAX_BYTES;
canic/lib.rs

canic/
lib.rs
