#
pezkuwi_sdk_docs/reference_docs/
umbrella_crate.rs

    1//! # Umbrella Crate
    2//!
    3//! The Pezkuwi-SDK "umbrella" is a crate that re-exports all other published crates. This makes it
    4//! possible to have a very small `Cargo.toml` file that only has one dependency, the umbrella
    5//! crate. This helps with selecting the right combination of crate versions, since otherwise 3rd
    6//! party tools are needed to select a compatible set of versions.
    7//!
    8//!
    9//! ## Features
    10//!
    11//! The umbrella crate supports no-std builds and can therefore be used in the runtime and node.
    12//! There are two main features: `runtime` and `node`. The `runtime` feature enables all `no-std`
    13//! crates, while the `node` feature enables all `std` crates. It should be used like any other
    14//! crate in the repo, with `default-features = false`.
    15//!
    16//! For more fine-grained control, additionally, each crate can be enabled selectively. The umbrella
    17//! exposes one feature per dependency. For example, if you only want to use the `pezframe-support`
    18//! crate, you can enable the `pezframe-support` feature.
    19//!
    20//! The umbrella exposes a few more general features:
    21//! - `tuples-96`: Needs to be enabled for runtimes that have more than 64 pallets.
    22//! - `serde`: Specifically enable `serde` en/decoding support.
    23//! - `experimental`: Experimental enable experimental features - should not yet used in production.
    24//! - `with-tracing`: Enable tracing support.
    25//! - `try-runtime`, `runtime-benchmarks` and `std`: These follow the standard conventions.
    26//! - `runtime`: As described above, enable all `no-std` crates.
    27//! - `node`: As described above, enable all `std` crates.
    28//! - There does *not* exist a dedicated docs feature. To generate docs, enable the `runtime` and
    29//!   `node` feature. For `docs.rs` the manifest contains specific configuration to make it show up
    30//!   all re-exports.
    31//!
    32//! There is a specific [`zepter`](https://github.com/ggwpez/zepter) check in place to ensure that
    33//! the features of the umbrella are correctly configured. This check is run in CI and locally when
    34//! running `zepter`.
    35//!
    36//! ## Generation
    37//!
    38//! The umbrella crate needs to be updated every time when a new crate is added or removed from the
    39//! workspace. It is checked in CI by calling its generation script. The generation script is
    40//! located in `./scripts/generate-umbrella.py` and needs dependency `cargo_workspace`.
    41//!
    42//! Example: `python3 scripts/generate-umbrella.py --sdk . --version 1.9.0`
    43//!
    44//! ## Usage
    45//!
    46//! > Note: You can see a live example in the `pezstaging-node-cli` and `pez-kitchensink-runtime`
    47//! > crates.
    48//!
    49//! The umbrella crate can be added to your runtime crate like this:
    50//!
    51//! `pezkuwi-sdk = { path = "../../../../umbrella", features = ["runtime"], default-features =
    52//! false }`
    53//!
    54//! or for a node:
    55//!
    56//! `pezkuwi-sdk = { path = "../../../../umbrella", features = ["node"], default-features = false
    57//! }`
    58//!
    59//! In the code, it is then possible to bring all dependencies into scope via:
    60//!
    61//! `use pezkuwi_sdk::*;`
    62//!
    63//! ### Known Issues
    64//!
    65//! The only known issue so far is the fact that the `use` statement brings the dependencies only
    66//! into the outer module scope - not the global crate scope. For example, the following code would
    67//! need to be adjusted:
    68//!
    69//! ```rust
    70//! use pezkuwi_sdk::*;
    71//!
    72//! mod foo {
    73//!    // This does sadly not compile:
    74//!    pezframe_support::parameter_types! { }
    75//!
    76//!    // Instead, we need to do this (or add an equivalent `use` statement):
    77//!    pezkuwi_sdk::pezframe_support::parameter_types! { }
    78//! }
    79//! ```
    80//!
    81//! Apart from this, no issues are known. There could be some bugs with how macros locate their own
    82//! re-exports. Please [report issues](https://github.com/pezkuwichain/pezkuwi-sdk/issues) that arise from using this crate.
    83//!
    84//! ## Dependencies
    85//!
    86//! The umbrella crate re-exports all published crates, with a few exceptions:
    87//! - Runtime crates like `pezkuwichain-runtime` etc are not exported. This otherwise leads to very
    88//!   weird compile errors and should not be needed anyway.
    89//! - Example and fuzzing crates are not exported. This is currently detected by checking the name
    90//!   of the crate for these magic words. In the future, it will utilize custom metadata, as it is
    91//!   done in the `pezkuwichain-runtime` crate.
    92//! - The umbrella crate itself. Should be obvious :)