Build WASM binaries as part of cargo build (#2868)

* Introduce `wasm-builder` and `wasm-builder-runner` to retire `build.sh` Make use of `wasm-builder` in `test-runtime`. * Add build script and remove the wasm project * Port `node-runtime` to new wasm-builder * Make `substrate-executor` tests work with `wasm-builder` * Move `node-template` to `wasm-builder` * Remove `build.sh` :) * Remove the last include_bytes * Adds the missing build.rs files * Remove `build.sh` from CI * Debug CI * Make it work in CI * CI attempt 3 * Make `substrate-runtime-test` compile on stable * Ahhh, some missed `include_bytes!` * AHH * Add suggestions * Improve search for `Cargo.lock` and don't panic if it is not found * Searching from manifest path was no good idea * Make the `wasm-builder` source better configurable * Expose the bloaty wasm binary as well * Make sure to rerun WASM recompilation on changes in dependencies * Introduce new `WASM_BUILD_TYPE` env and make sure to call `build.rs` on changes to env variables * Remove `build.sh` from READMEs * Rename the projects * Fixes CI * Update lock file * Fixes merge-conflict * Apply suggestions from code review Co-Authored-By: TriplEight <denis.pisarev@parity.io> * Try to make windows happy * Replace all back slashes in paths with slashes * Apply suggestions from code review Co-Authored-By: Pierre Krieger <pierre.krieger1708@gmail.com> * Use cargo from `CARGO` env variable * Fix compilation * Use `rustup` for running the nightly build * Make individual projects skipable * Fix compilation * Fixes compilation * Build all WASM projects in one workspace * Replace more back slashes! * Remove `inlcude_bytes!` * Adds some documentation * Apply suggestions from code review Co-Authored-By: Shawn Tabrizi <shawntabrizi@gmail.com> * Apply suggestions from code review Co-Authored-By: Shawn Tabrizi <shawntabrizi@gmail.com> * More review comments * Update `Cargo.lock` * Set license * Apply suggestions from code review Co-Authored-By: joe petrowski <25483142+joepetrowski@users.noreply.github.com> * More review comments + adds `TRIGGER_WASM_BUILD` env * Fix doc tests * Increase version + update README * Switch crates.io version of `wasm-builder` * Update README * Switch to released version of `wasm-builder-runner`
2026-06-17 21:51:06 +00:00 · 2019-07-04 11:34:06 +02:00
parent eca9c36b75
commit fe08221479
57 changed files with 1187 additions and 11869 deletions
@@ -0,0 +1,65 @@
+## 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 `substrate-wasm-builder-runner` as dependency into `build-dependencies`.
+3. Add a feature called `no-std`.
+
+The `build.rs` file needs to contain the following code:
+
+```rust
+use wasm_builder_runner::{build_current_project, WasmBuilderSource};
+
+fn main() {
+	build_current_project(
+		// The name of the file being generated in out-dir.
+		"wasm_binary.rs",
+		// How to include wasm-builder, in this case from crates.io.
+		WasmBuilderSource::Crates("1.0.0"),
+	);
+}
+```
+
+The `no-std` feature will be enabled by WASM builder while compiling your project to WASM.
+
+As the final step, you need to add the following to your project:
+
+```rust
+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 not compacted.
+
+### 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.
+- `BUILD_DUMMY_WASM_BINARY` - Builds dummy WASM binaries. These dummy binaries are empty and useful
+                             for `cargo check` runs.
+- `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.
+- `TRIGGER_WASM_BUILD` - Can be set to trigger 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.
+
+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`.
+
+### Prerequisites:
+
+WASM builder requires the following prerequisities for building the WASM binary:
+
+- rust nightly + `wasm32-unknown-unknown` toolchain
+- wasm-gc
+
+
+License: GPL-3.0