46 releases (23 major breaking)
24.0.1 | Sep 25, 2024 |
---|---|
24.0.0 | Jul 18, 2024 |
23.0.0 | Jun 21, 2024 |
22.0.1 | Jun 13, 2024 |
1.0.4 | Jul 8, 2019 |
#25 in #wasm-build
13,444 downloads per month
Used in 57 crates
(36 directly)
610KB
4.5K
SLoC
Release
Polkadot SDK stable2409
lib.rs
:
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:
- Add a
build.rs
file. - Add
wasm-builder
as dependency intobuild-dependencies
.
The build.rs
file needs to contain the following code:
use substrate_wasm_builder::WasmBuilder;
fn main() {
// Builds the WASM binary using the recommended defaults.
// If you need more control, you can call `new` or `init_with_defaults`.
WasmBuilder::build_using_defaults();
}
As the final step, you need to add the following to your project:
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 toNone
.WASM_BUILD_TYPE
- Sets the build type for building Wasm binaries. Supported values arerelease
ordebug
. 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 instructscargo
to watch for file changes this environment variable should only be required in certain circumstances.WASM_BUILD_RUSTFLAGS
- ExtendRUSTFLAGS
given tocargo 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 aCargo.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
- Iftrue
,--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
.
Dependencies
~20–37MB
~646K SLoC