diff --git a/bin/utils/chain-spec-builder/src/lib.rs b/bin/utils/chain-spec-builder/src/lib.rs index fa3c6835c799e..528b6b70115a0 100644 --- a/bin/utils/chain-spec-builder/src/lib.rs +++ b/bin/utils/chain-spec-builder/src/lib.rs @@ -20,7 +20,14 @@ //! //! A chain-spec is short for `chain-configuration`. See the [`sc-chain-spec`] for more information. //! +//! Note that this binary is analogous to the `build-spec` subcommand, contained in typical +//! substrate-based nodes. This particular binary is capable of building a more sophisticated chain +//! specification that can be used with the substrate-node, ie. [`node-cli`]. +//! //! See [`ChainSpecBuilder`] for a list of available commands. +//! +//! [`sc-chain-spec`]: ../sc_chain_spec/index.html +//! [`node-cli`]: ../node_cli/index.html use std::path::{Path, PathBuf}; diff --git a/client/chain-spec/src/lib.rs b/client/chain-spec/src/lib.rs index 6239eb7326b78..341c5f28e4a44 100644 --- a/client/chain-spec/src/lib.rs +++ b/client/chain-spec/src/lib.rs @@ -116,15 +116,19 @@ //! ```json //! // The human readable name of the chain. //! "name": "Flaming Fir", +//! //! // The id of the chain. //! "id": "flamingfir9", +//! //! // The chain type of this chain. //! // Possible values are `Live`, `Development`, `Local`. //! "chainType": "Live", +//! //! // A list of multi addresses that belong to boot nodes of the chain. //! "bootNodes": [ //! "/dns/0.flamingfir.paritytech.net/tcp/30333/p2p/12D3KooWLK2gMLhWsYJzjW3q35zAs9FDDVqfqVfVuskiGZGRSMvR", //! ], +//! //! // Optional list of "multi address, verbosity" of telemetry endpoints. //! // The verbosity goes from `0` to `9`. With `0` being the mode with the lowest verbosity. //! "telemetryEndpoints": [ @@ -133,19 +137,24 @@ //! 0 //! ] //! ], +//! //! // Optional networking protocol id that identifies the chain. //! "protocolId": "fir9", +//! //! // Optional fork id. Should most likely be left empty. //! // Can be used to signal a fork on the network level when two chains have the //! // same genesis hash. //! "forkId": "random_fork", +//! //! // Custom properties. //! "properties": { //! "tokenDecimals": 15, //! "tokenSymbol": "FIR" //! }, +//! //! // Deprecated field. Should be ignored. //! "consensusEngine": null, +//! //! // The genesis declaration of the chain. //! // //! // `runtime`, `raw`, `stateRootHash` denote the type of the genesis declaration. @@ -159,6 +168,7 @@ //! // type depends on the hash used by the chain. //! // //! "genesis": { "runtime": {} }, +//! //! /// Optional map of `block_number` to `wasm_code`. //! /// //! /// The given `wasm_code` will be used to substitute the on-chain wasm code starting with the @@ -172,6 +182,8 @@ //! "codeSubstitutes": [], //! ``` //! +//! See [`ChainSpec`] for a trait representation of the above. +//! //! The chain spec can be extended with other fields that are opaque to the default chain spec. //! Specific node implementations will need to be able to deserialize these extensions. diff --git a/scripts/ci/gitlab/pipeline/build.yml b/scripts/ci/gitlab/pipeline/build.yml index 4669f705faceb..ee0a43d9e0c19 100644 --- a/scripts/ci/gitlab/pipeline/build.yml +++ b/scripts/ci/gitlab/pipeline/build.yml @@ -153,7 +153,7 @@ build-rustdoc: - .test-refs variables: SKIP_WASM_BUILD: 1 - DOC_INDEX_PAGE: "sc_service/index.html" # default redirected page + DOC_INDEX_PAGE: "substrate/index.html" # default redirected page # this variable gets overriden by "rusty-cachier environment inject", use the value as default CARGO_TARGET_DIR: "$CI_PROJECT_DIR/target" artifacts: diff --git a/src/lib.rs b/src/lib.rs index eb313ddadf76d..16a6067789657 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -105,6 +105,21 @@ //! * `pallet-*` and `frame-*` crates, located under `./frame` folder. These are the crates related //! to FRAME. See [`frame_support`] for more information. //! +//! ### Wasm Build +//! +//! Many of the Substrate crates, such as entire `sp-*`, need to compile to both Wasm (when a Wasm +//! runtime is being generated) and native (for example, when testing). To achieve this, Substrate +//! follows the convention of the Rust community, and uses a `feature = "std"` to signify that a +//! crate is being built with the standard library, and is built for native. Otherwise, it is built +//! for `no_std`. +//! +//! This can be summarized in `#![cfg_attr(not(feature = "std"), no_std)]`, which you can often find +//! in any Substrate-based runtime. +//! +//! Substrate-based runtimes use [`substrate-wasm-builder`] in their `build.rs` to automatically +//! build their Wasm files as a part of normal build commandsOnce built, the wasm file is placed in +//! `./target/{debug|release}/wbuild/{runtime_name}.wasm`. +//! //! ### Binaries //! //! Multiple binaries are shipped with substrate, the most important of which are located in the @@ -112,12 +127,29 @@ //! //! * [`node`] is an extensive substrate node that contains the superset of all runtime and client //! side features. The corresponding runtime, called [`kitchensink_runtime`] contains all of the -//! modules that are provided with `FRAME`. This node and runtime is only used for testing. +//! modules that are provided with `FRAME`. This node and runtime is only used for testing and +//! demonstration. +//! * [`chain-spec-builder`]: Utility to build more detailed chain-specs for the aforementioned +//! node. Other projects typically contain a `build-spec` subcommand that does the same. //! * [`node-template`]: a template node that contains a minimal set of features and can act as a //! starting point of a project. //! * [`subkey`]: Substrate's key management utility. -//! * [`chain-spec-builder`]: Substrate's utility to build *chain specifications*. Such -//! specifications can then be used with `--chain` argument of a typical substrate node's CLI. +//! +//! ### Anatomy of a Binary Crate +//! +//! From the above, [`node`] and [`node-template`] are essentially blueprints of a substrate-based +//! project, as the name of the latter is implying. Each substrate-based project typically contains +//! the following: +//! +//! * Under `./runtime`, a `./runtime/src/lib.rs` which is the top level runtime amalgamator file. +//! This file typically contains the [`frame_support::construct_runtime`] macro, which is the +//! final definition of a runtime. +//! +//! * Under `./node`, a `main.rs`, which is the point, and a `./service.rs`, which contains all the +//! client side components. Skimming this file yields an overview of the networking, database, +//! consensus and similar client side components. +//! +//! > The above two are conventions, not rules. //! //! ## Parachain? //! @@ -132,7 +164,7 @@ //! //! Additional noteworthy crates within substrate: //! -//! - RPC APIs of a Substrate node: [`sc-rpc-api`] +//! - RPC APIs of a Substrate node: [`sc-rpc-api`]/[`sc-rpc`] //! - CLI Options of a Substrate node: [`sc-cli`] //! - All of the consensus related crates provided by Substrate: //! - [`sc-consensus-aura`] @@ -151,6 +183,7 @@ //! //! Notable upstream crates: //! +//! - [`parity-scale-codec`](https://github.com/paritytech/parity-scale-codec) //! - [`parity-db`](https://github.com/paritytech/parity-db) //! - [`trie`](https://github.com/paritytech/trie) //! - [`parity-common`](https://github.com/paritytech/parity-common) @@ -172,6 +205,7 @@ //! [`sc-client-db`]: ../sc_client_db/index.html //! [`sc-network`]: ../sc_network/index.html //! [`sc-rpc-api`]: ../sc_rpc_api/index.html +//! [`sc-rpc`]: ../sc_rpc/index.html //! [`sc-cli`]: ../sc_cli/index.html //! [`sc-consensus-aura`]: ../sc_consensus_aura/index.html //! [`sc-consensus-babe`]: ../sc_consensus_babe/index.html @@ -182,8 +216,9 @@ //! [`node`]: ../node_cli/index.html //! [`node-template`]: ../node_template/index.html //! [`kitchensink_runtime`]: ../kitchensink_runtime/index.html -//! [`subkey`]: ..//subkey/index.html -//! [`chian-spec-builder`]: ../chain_spec_builder/index.html +//! [`subkey`]: ../subkey/index.html +//! [`chain-spec-builder`]: ../chain_spec_builder/index.html +//! [`substrate-wasm-builder`]: https://crates.io/crates/substrate-wasm-builder #![deny(rustdoc::broken_intra_doc_links)] #![deny(rustdoc::private_intra_doc_links)]