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 configured canister lifecycle hooks and endpoints
8//! - `start_fleet_coordinator!` for Canic's canonical Coordinator artifact source
9//!
10//! For lower-level access, use the `api`, `dto`, and `memory` modules.
11//! These surfaces are for configured canister role packages. Shared runtime
12//! libraries should remain independent of Canic and use upstream crates such
13//! as `candid` or `ic-cdk` directly when they need generic IC types or APIs.
14//! Direct access to internal core modules is intentionally unsupported.
15
16pub mod access;
17pub mod api;
18#[cfg(any(not(target_arch = "wasm32"), test))]
19mod build_support;
20pub mod diagnostics;
21pub mod dto;
22pub mod ids;
23mod instructions;
24mod macros; // private implementation boundary
25pub mod prelude;
26pub mod protocol;
27
28#[doc(hidden)]
29pub mod __internal {
30    // NOTE:
31    // This module exists ONLY for macro expansion.
32    // Do NOT re-export canic_core publicly.
33    pub use candid;
34    #[cfg(any(
35        feature = "control-plane",
36        feature = "fleet-coordinator-canister",
37        feature = "wasm-store-canister"
38    ))]
39    pub use canic_control_plane as control_plane;
40    pub use canic_core as core;
41    pub use serde;
42
43    pub mod cdk {
44        pub use candid::Principal;
45        pub use ic_cdk::{
46            export_candid, futures, init, inspect_message, post_upgrade, query, trap, update,
47        };
48
49        pub mod api {
50            pub use ic_cdk::api::{
51                canister_cycle_balance, canister_version, is_controller, msg_caller, msg_reply,
52                time,
53            };
54        }
55
56        pub mod raw {
57            pub use ic0::{msg_arg_data_copy, msg_arg_data_size};
58        }
59    }
60
61    pub mod instructions {
62        pub use crate::instructions::format_instructions;
63    }
64}
65
66#[doc(hidden)]
67#[cfg(any(not(target_arch = "wasm32"), test))]
68pub mod __build {
69    pub use crate::build_support::{
70        CANIC_CUSTOM_CFG_NAMES, METRICS_TIER_CORE, METRICS_TIER_PLACEMENT, METRICS_TIER_PLATFORM,
71        METRICS_TIER_RUNTIME, METRICS_TIER_SECURITY, METRICS_TIER_STORAGE,
72        assert_canonical_role_contract_build, config_app_id, config_contains_role,
73        config_declares_role, configured_role_metrics_tier_mask, declared_package_metadata,
74        declared_package_role, metrics_profile_tier_mask, read_config_source_or_default,
75        required_package_metadata, required_package_role,
76    };
77}
78
79// -----------------------------------------------------------------------------
80// Sub-crates
81// -----------------------------------------------------------------------------
82pub use canic_core::memory;
83
84// -----------------------------------------------------------------------------
85// Re-exports
86// -----------------------------------------------------------------------------
87pub use canic_core::dto::error::Error;
88pub use canic_core::{impl_storable_bounded, impl_storable_unbounded};
89pub use canic_macros::{canic_query, canic_update};
90pub use diagnostics::{DiagnosticCode, RegisteredDiagnosticCode};
91
92// -----------------------------------------------------------------------------
93// Constants
94// -----------------------------------------------------------------------------
95
96pub const VERSION: &str = env!("CARGO_PKG_VERSION");
97pub const CANIC_WASM_CHUNK_BYTES: usize = canic_core::CANIC_WASM_CHUNK_BYTES;
98pub const CANIC_DEFAULT_UPDATE_INGRESS_MAX_BYTES: usize =
99    canic_core::ingress::payload::DEFAULT_UPDATE_INGRESS_MAX_BYTES;
canic/lib.rs

canic/
lib.rs
