Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Build the standard library crates when building the runtimes #2217

Merged
merged 8 commits into from
Nov 27, 2023
Merged

Build the standard library crates when building the runtimes #2217

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
041d5d2
Also build the standard library crates when building the runtimes
koute Nov 8, 2023
7ef428e
Refactor and simplify the check for the WASM toolchain
koute Nov 8, 2023
3067b53
Detect whether `rust-src` is installed, and if not print an error mes…
koute Nov 8, 2023
ecf6651
Merge remote-tracking branch 'origin/master' into master_wasm_build_std
koute Nov 27, 2023
b9225bd
Apply review suggestion
koute Nov 27, 2023
e593b53
Remove `#![warn(unused_crate_dependencies)]`
koute Nov 27, 2023
5f637d8
Merge branch 'master' into master_wasm_build_std
bkchr Nov 27, 2023
0f560a8
Unify `wasm-builder`'s README and crate docs
koute Nov 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions polkadot/parachain/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,6 @@
// You should have received a copy of the GNU General Public License
// along with Polkadot. If not, see <http://www.gnu.org/licenses/>.

#![warn(unused_crate_dependencies)]

//! Defines primitive types for creating or validating a parachain.
//!
//! When compiled with standard library support, this crate exports a `wasm`
Expand Down
12 changes: 9 additions & 3 deletions substrate/utils/wasm-builder/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")]
{
Expand All @@ -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"));
```

Expand Down Expand Up @@ -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

Expand Down
126 changes: 33 additions & 93 deletions substrate/utils/wasm-builder/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,99 +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.
//! - `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")]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NOOOO 😿
#2465

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm.... okay, so, do we want to get rid of the README completely? I can easily make another PR. :P

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah :P

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, no problem; I'll make a PR tomorrow. :P


use std::{
env, fs,
Expand Down Expand Up @@ -158,6 +66,9 @@ const FORCE_WASM_BUILD_ENV: &str = "FORCE_WASM_BUILD";
/// Environment variable that hints the workspace we are building.
const WASM_BUILD_WORKSPACE_HINT: &str = "WASM_BUILD_WORKSPACE_HINT";

/// Environment variable to set whether we'll build `core`/`std`.
const WASM_BUILD_STD: &str = "WASM_BUILD_STD";

/// Write to the given `file` if the `content` is different.
fn write_file_if_changed(file: impl AsRef<Path>, content: impl AsRef<str>) {
if fs::read_to_string(file.as_ref()).ok().as_deref() != Some(content.as_ref()) {
Expand Down Expand Up @@ -282,6 +193,12 @@ impl CargoCommand {
self.version
}

/// Returns whether this version of the toolchain supports nightly features.
fn supports_nightly_features(&self) -> bool {
self.version.map_or(false, |version| version.is_nightly) ||
env::var("RUSTC_BOOTSTRAP").is_ok()
}

/// Check if the supplied cargo command supports our Substrate wasm environment.
///
/// This means that either the cargo version is at minimum 1.68.0 or this is a nightly cargo.
Expand Down Expand Up @@ -332,3 +249,26 @@ impl std::ops::Deref for CargoCommandVersioned {
fn color_output_enabled() -> bool {
env::var(crate::WASM_BUILD_NO_COLOR).is_err()
}

/// Fetches a boolean environment variable. Will exit the process if the value is invalid.
fn get_bool_environment_variable(name: &str) -> Option<bool> {
let value = env::var_os(name)?;

// We're comparing `OsString`s here so we can't use a `match`.
if value == "1" {
Some(true)
} else if value == "0" {
Some(false)
} else {
build_helper::warning!(
"the '{}' environment variable has an invalid value; it must be either '1' or '0'",
name
);
std::process::exit(1);
}
}

/// Returns whether we need to also compile the standard library when compiling the runtime.
fn build_std_required() -> bool {
crate::get_bool_environment_variable(crate::WASM_BUILD_STD).unwrap_or(true)
}
Loading