canic/
lib.rs

1//! Canic facade crate.
2//!
3//! This crate is the recommended dependency for downstream canister projects. It
4//! re-exports the core Canic stack and provides the common macro entry points:
5//! - `build!` / `build_root!` for `build.rs` (validate/embed `canic.toml`)
6//! - `start!` / `start_root!` for `lib.rs` (wire lifecycle hooks and export endpoints)
7//!
8//! For lower-level access, use the `api`, `cdk`, `memory`, and `utils` modules.
9//! Direct access to internal core modules is intentionally unsupported.
10
11mod macros;
12
13#[doc(hidden)]
14pub mod __internal {
15    pub use canic_core as core;
16}
17#[doc(hidden)]
18pub use __internal::core;
19
20// -----------------------------------------------------------------------------
21// Sub-crates
22// -----------------------------------------------------------------------------
23pub use canic_cdk as cdk;
24pub use canic_utils as utils;
25
26// -----------------------------------------------------------------------------
27// Re-exports
28// -----------------------------------------------------------------------------
29pub use canic_core::PublicError;
30pub use canic_memory::{
31    eager_init, eager_static, ic_memory, ic_memory_range, impl_storable_bounded,
32    impl_storable_unbounded,
33};
34
35// -----------------------------------------------------------------------------
36// Constants
37// -----------------------------------------------------------------------------
38
39pub const CRATE_NAME: &str = env!("CARGO_PKG_NAME");
40pub const VERSION: &str = env!("CARGO_PKG_VERSION");
41
42// -----------------------------------------------------------------------------
43// Prelude
44// -----------------------------------------------------------------------------
45
46///
47/// Opinionated prelude for Canic canister crates.
48///
49/// Prefer importing from the prelude in your canister `lib.rs` to keep endpoint
50/// modules small and consistent. Library crates and shared modules should
51/// generally import from specific paths instead of pulling in the entire prelude.
52///
53
54pub mod prelude {
55    pub use crate::cdk::{
56        api::{canister_self, msg_caller},
57        candid::CandidType,
58        export_candid,
59    };
60
61    pub use canic_dsl::{canic_query, canic_update};
62
63    // Explicit, curated exports (no `core::` paths)
64    pub use crate::api::{
65        Call, CanisterRole, auth_require_all, auth_require_any, is_child, is_controller, is_parent,
66        is_root, log, perf, timer, timer_interval,
67    };
68}
69
70pub mod api {
71    pub use crate::__internal::core::{
72        access::auth::{is_child, is_controller, is_parent, is_root},
73        api::{
74            ic::call::{Call, CallBuilder, CallResult},
75            placement::{scaling::ScalingApi, sharding::ShardingApi},
76            rpc::RpcApi,
77            wasm::WasmApi,
78        },
79        ids::CanisterRole,
80        log, perf,
81    };
82
83    pub use crate::{auth_require_all, auth_require_any, timer, timer_interval};
84}
canic/lib.rs

canic/
lib.rs
