From 0f560a831ab2635780f0f4bf9d82d68949247f33 Mon Sep 17 00:00:00 2001 From: Jan Bujak Date: Mon, 27 Nov 2023 09:57:28 +0000 Subject: [PATCH] Unify `wasm-builder`'s README and crate docs --- substrate/utils/wasm-builder/README.md | 12 ++- substrate/utils/wasm-builder/src/lib.rs | 97 +------------------------ 2 files changed, 10 insertions(+), 99 deletions(-) diff --git a/substrate/utils/wasm-builder/README.md b/substrate/utils/wasm-builder/README.md index db32f5cbc955..6dfc743816cb 100644 --- a/substrate/utils/wasm-builder/README.md +++ b/substrate/utils/wasm-builder/README.md @@ -13,7 +13,7 @@ A project that should be compiled as a Wasm binary needs to: The `build.rs` file needs to contain the following code: -```rust +```rust,no_run fn main() { #[cfg(feature = "std")] { @@ -32,7 +32,7 @@ fn main() { As the final step, you need to add the following to your project: -```rust +```rust,ignore include!(concat!(env!("OUT_DIR"), "/wasm_binary.rs")); ``` @@ -63,11 +63,17 @@ By using environment variables, you can configure which Wasm binaries are built - `WASM_TARGET_DIRECTORY` - Will copy any build Wasm binary to the given directory. The path needs to be absolute. - `WASM_BUILD_TOOLCHAIN` - The toolchain that should be used to build the Wasm binaries. The format needs to be the same as used by cargo, e.g. `nightly-2020-02-20`. +- `WASM_BUILD_WORKSPACE_HINT` - Hint the workspace that is being built. This is normally not required as we walk up from + the target directory until we find a `Cargo.toml`. If the target directory is changed for + the build, this environment variable can be used to point to the actual workspace. +- `WASM_BUILD_STD` - Sets whether the Rust's standard library crates will also be built. This is necessary to make sure + the standard library crates only use the exact WASM feature set that our executor supports. + Enabled by default. - `CARGO_NET_OFFLINE` - If `true`, `--offline` will be passed to all processes launched to prevent network access. Useful in offline environments. Each project can be skipped individually by using the environment variable `SKIP_PROJECT_NAME_WASM_BUILD`. Where -`PROJECT_NAME` needs to be replaced by the name of the cargo project, e.g. `node-runtime` will be `NODE_RUNTIME`. +`PROJECT_NAME` needs to be replaced by the name of the cargo project, e.g. `kitchensink-runtime` will be `NODE_RUNTIME`. ## Prerequisites diff --git a/substrate/utils/wasm-builder/src/lib.rs b/substrate/utils/wasm-builder/src/lib.rs index ec85fd1ffddb..cd31a8cba105 100644 --- a/substrate/utils/wasm-builder/src/lib.rs +++ b/substrate/utils/wasm-builder/src/lib.rs @@ -15,102 +15,7 @@ // See the License for the specific language governing permissions and // limitations under the License. -//! # Wasm builder is a utility for building a project as a Wasm binary -//! -//! The Wasm builder is a tool that integrates the process of building the WASM binary of your -//! project into the main `cargo` build process. -//! -//! ## Project setup -//! -//! A project that should be compiled as a Wasm binary needs to: -//! -//! 1. Add a `build.rs` file. -//! 2. Add `wasm-builder` as dependency into `build-dependencies`. -//! -//! The `build.rs` file needs to contain the following code: -//! -//! ```no_run -//! use substrate_wasm_builder::WasmBuilder; -//! -//! fn main() { -//! WasmBuilder::new() -//! // Tell the builder to build the project (crate) this `build.rs` is part of. -//! .with_current_project() -//! // Make sure to export the `heap_base` global, this is required by Substrate -//! .export_heap_base() -//! // Build the Wasm file so that it imports the memory (need to be provided by at instantiation) -//! .import_memory() -//! // Build it. -//! .build() -//! } -//! ``` -//! -//! As the final step, you need to add the following to your project: -//! -//! ```ignore -//! include!(concat!(env!("OUT_DIR"), "/wasm_binary.rs")); -//! ``` -//! -//! This will include the generated Wasm binary as two constants `WASM_BINARY` and -//! `WASM_BINARY_BLOATY`. The former is a compact Wasm binary and the latter is the Wasm binary as -//! being generated by the compiler. Both variables have `Option<&'static [u8]>` as type. -//! -//! ### Feature -//! -//! Wasm builder supports to enable cargo features while building the Wasm binary. By default it -//! will enable all features in the wasm build that are enabled for the native build except the -//! `default` and `std` features. Besides that, wasm builder supports the special `runtime-wasm` -//! feature. This `runtime-wasm` feature will be enabled by the wasm builder when it compiles the -//! Wasm binary. If this feature is not present, it will not be enabled. -//! -//! ## Environment variables -//! -//! By using environment variables, you can configure which Wasm binaries are built and how: -//! -//! - `SKIP_WASM_BUILD` - Skips building any Wasm binary. This is useful when only native should be -//! recompiled. If this is the first run and there doesn't exist a Wasm binary, this will set both -//! variables to `None`. -//! - `WASM_BUILD_TYPE` - Sets the build type for building Wasm binaries. Supported values are -//! `release` or `debug`. By default the build type is equal to the build type used by the main -//! build. -//! - `FORCE_WASM_BUILD` - Can be set to force a Wasm build. On subsequent calls the value of the -//! variable needs to change. As wasm-builder instructs `cargo` to watch for file changes this -//! environment variable should only be required in certain circumstances. -//! - `WASM_BUILD_RUSTFLAGS` - Extend `RUSTFLAGS` given to `cargo build` while building the wasm -//! binary. -//! - `WASM_BUILD_NO_COLOR` - Disable color output of the wasm build. -//! - `WASM_TARGET_DIRECTORY` - Will copy any build Wasm binary to the given directory. The path -//! needs to be absolute. -//! - `WASM_BUILD_TOOLCHAIN` - The toolchain that should be used to build the Wasm binaries. The -//! format needs to be the same as used by cargo, e.g. `nightly-2020-02-20`. -//! - `WASM_BUILD_WORKSPACE_HINT` - Hint the workspace that is being built. This is normally not -//! required as we walk up from the target directory until we find a `Cargo.toml`. If the target -//! directory is changed for the build, this environment variable can be used to point to the -//! actual workspace. -//! - `WASM_BUILD_STD` - Sets whether the Rust's standard library crates will also be built. This is -//! necessary to make sure the standard library crates only use the exact WASM feature set that -//! our executor supports. Enabled by default. -//! - `CARGO_NET_OFFLINE` - If `true`, `--offline` will be passed to all processes launched to -//! prevent network access. Useful in offline environments. -//! -//! Each project can be skipped individually by using the environment variable -//! `SKIP_PROJECT_NAME_WASM_BUILD`. Where `PROJECT_NAME` needs to be replaced by the name of the -//! cargo project, e.g. `kitchensink-runtime` will be `NODE_RUNTIME`. -//! -//! ## Prerequisites: -//! -//! Wasm builder requires the following prerequisites for building the Wasm binary: -//! -//! - rust nightly + `wasm32-unknown-unknown` toolchain -//! -//! or -//! -//! - rust stable and version at least 1.68.0 + `wasm32-unknown-unknown` toolchain -//! -//! If a specific rust is installed with `rustup`, it is important that the wasm target is -//! installed as well. For example if installing the rust from 20.02.2020 using `rustup -//! install nightly-2020-02-20`, the wasm target needs to be installed as well `rustup target add -//! wasm32-unknown-unknown --toolchain nightly-2020-02-20`. +#![doc = include_str!("../README.md")] use std::{ env, fs,