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
16#![deny(unreachable_pub)]
17
18pub mod access;
19pub mod api;
20#[cfg(any(not(target_arch = "wasm32"), test))]
21mod build_support;
22pub mod diagnostics;
23pub mod dto;
24pub mod fleet_admission;
25pub mod ids;
26mod instructions;
27mod macros; // private implementation boundary
28pub mod prelude;
29pub mod protocol;
30#[cfg(all(feature = "testing", not(target_arch = "wasm32")))]
31pub mod testing;
32
33#[doc(hidden)]
34pub mod __internal {
35    // NOTE:
36    // This module exists ONLY for macro expansion.
37    // Do NOT re-export canic_core publicly.
38    pub use candid;
39    #[cfg(any(
40        feature = "control-plane",
41        feature = "fleet-coordinator-canister",
42        feature = "wasm-store-canister"
43    ))]
44    pub use canic_control_plane as control_plane;
45    pub use canic_core as core;
46    pub use serde;
47
48    pub mod cdk {
49        pub use candid::Principal;
50        pub use ic_cdk::{
51            export_candid, futures, init, inspect_message, post_upgrade, query, trap, update,
52        };
53
54        pub mod api {
55            pub use ic_cdk::api::{
56                canister_cycle_balance, canister_version, is_controller, msg_caller, msg_reply,
57                time,
58            };
59        }
60
61        pub mod raw {
62            pub use ic0::{msg_arg_data_copy, msg_arg_data_size};
63        }
64    }
65
66    pub mod instructions {
67        pub use crate::instructions::format_instructions;
68    }
69}
70
71#[doc(hidden)]
72#[cfg(any(not(target_arch = "wasm32"), test))]
73pub mod __build {
74    pub use crate::build_support::{
75        CANIC_CUSTOM_CFG_NAMES, METRICS_TIER_CORE, METRICS_TIER_PLACEMENT, METRICS_TIER_PLATFORM,
76        METRICS_TIER_RUNTIME, METRICS_TIER_SECURITY, METRICS_TIER_STORAGE,
77        assert_canonical_role_contract_build, compile_role_build_sources, config_app_id,
78        config_contains_role, config_declares_role, configured_role_metrics_tier_mask,
79        declared_package_metadata, declared_package_role, metrics_profile_tier_mask,
80        read_config_source_or_default, required_package_metadata, required_package_role,
81    };
82}
83
84// -----------------------------------------------------------------------------
85// Sub-crates
86// -----------------------------------------------------------------------------
87pub use canic_core::memory;
88
89// -----------------------------------------------------------------------------
90// Re-exports
91// -----------------------------------------------------------------------------
92pub use canic_core::dto::error::Error;
93pub use canic_core::{impl_storable_bounded, impl_storable_unbounded};
94pub use canic_macros::{canic_query, canic_update};
95pub use diagnostics::{DiagnosticCode, RegisteredDiagnosticCode};
96
97// -----------------------------------------------------------------------------
98// Constants
99// -----------------------------------------------------------------------------
100
101pub const VERSION: &str = env!("CARGO_PKG_VERSION");
102pub const CANIC_WASM_CHUNK_BYTES: usize = canic_core::CANIC_WASM_CHUNK_BYTES;
103pub const CANIC_DEFAULT_UPDATE_INGRESS_MAX_BYTES: usize =
104    canic_core::ingress::payload::DEFAULT_UPDATE_INGRESS_MAX_BYTES;
canic/lib.rs

canic/
lib.rs
