gsubstrate_wasm_builder/
builder.rs

1// Copyright (C) Parity Technologies (UK) Ltd.
2// SPDX-License-Identifier: Apache-2.0
3
4// See `README.md` for the upstream source and license reference.
5
6use std::{
7    env,
8    path::{Path, PathBuf},
9    process,
10};
11
12use crate::RuntimeTarget;
13
14/// Extra information when generating the `metadata-hash`.
15#[cfg(feature = "metadata-hash")]
16pub(crate) struct MetadataExtraInfo {
17    pub decimals: u8,
18    pub token_symbol: String,
19}
20
21/// Returns the manifest dir from the `CARGO_MANIFEST_DIR` env.
22fn get_manifest_dir() -> PathBuf {
23    env::var("CARGO_MANIFEST_DIR")
24        .expect("`CARGO_MANIFEST_DIR` is always set for `build.rs` files; qed")
25        .into()
26}
27
28/// First step of the [`WasmBuilder`] to select the project to build.
29pub struct WasmBuilderSelectProject {
30    /// This parameter just exists to make it impossible to construct
31    /// this type outside of this crate.
32    _ignore: (),
33}
34
35impl WasmBuilderSelectProject {
36    /// Use the current project as project for building the WASM binary.
37    ///
38    /// # Panics
39    ///
40    /// Panics if the `CARGO_MANIFEST_DIR` variable is not set. This variable
41    /// is always set by `Cargo` in `build.rs` files.
42    pub fn with_current_project(self) -> WasmBuilder {
43        WasmBuilder {
44            cargo_flags: Vec::new(),
45            rust_flags: Vec::new(),
46            file_name: None,
47            project_cargo_toml: get_manifest_dir().join("Cargo.toml"),
48            features_to_enable: Vec::new(),
49            disable_runtime_version_section_check: false,
50            export_heap_base: false,
51            import_memory: false,
52            #[cfg(feature = "metadata-hash")]
53            enable_metadata_hash: None,
54        }
55    }
56
57    /// Use the given `path` as project for building the WASM binary.
58    ///
59    /// Returns an error if the given `path` does not points to a `Cargo.toml`.
60    pub fn with_project(self, path: impl Into<PathBuf>) -> Result<WasmBuilder, &'static str> {
61        let path = path.into();
62
63        if path.ends_with("Cargo.toml") && path.exists() {
64            Ok(WasmBuilder {
65                cargo_flags: Vec::new(),
66                rust_flags: Vec::new(),
67                file_name: None,
68                project_cargo_toml: path,
69                features_to_enable: Vec::new(),
70                disable_runtime_version_section_check: false,
71                export_heap_base: false,
72                import_memory: false,
73                #[cfg(feature = "metadata-hash")]
74                enable_metadata_hash: None,
75            })
76        } else {
77            Err("Project path must point to the `Cargo.toml` of the project")
78        }
79    }
80}
81
82/// The builder for building a wasm binary.
83///
84/// The builder itself is separated into multiple structs to make the setup type safe.
85///
86/// Building a wasm binary:
87///
88/// 1. Call [`WasmBuilder::new`] to create a new builder.
89/// 2. Select the project to build using the methods of [`WasmBuilderSelectProject`].
90/// 3. Set additional `RUST_FLAGS` or a different name for the file containing the WASM code using
91///    methods of [`WasmBuilder`].
92/// 4. Build the WASM binary using [`Self::build`].
93pub struct WasmBuilder {
94    /// Flags that should be appended to `cargo rustc` invocation.
95    cargo_flags: Vec<String>,
96    /// Flags that should be appended to `RUST_FLAGS` env variable.
97    rust_flags: Vec<String>,
98    /// The name of the file that is being generated in `OUT_DIR`.
99    ///
100    /// Defaults to `wasm_binary.rs`.
101    file_name: Option<String>,
102    /// The path to the `Cargo.toml` of the project that should be built
103    /// for wasm.
104    project_cargo_toml: PathBuf,
105    /// Features that should be enabled when building the wasm binary.
106    features_to_enable: Vec<String>,
107    /// Should the builder not check that the `runtime_version` section exists in the wasm binary?
108    disable_runtime_version_section_check: bool,
109
110    /// Whether `__heap_base` should be exported (WASM-only).
111    export_heap_base: bool,
112    /// Whether `--import-memory` should be added to the link args (WASM-only).
113    import_memory: bool,
114
115    /// Whether to enable the metadata hash generation.
116    #[cfg(feature = "metadata-hash")]
117    enable_metadata_hash: Option<MetadataExtraInfo>,
118}
119
120impl WasmBuilder {
121    /// Create a new instance of the builder.
122    pub fn new() -> WasmBuilderSelectProject {
123        WasmBuilderSelectProject { _ignore: () }
124    }
125
126    /// Build the WASM binary using the recommended default values.
127    ///
128    /// This is the same as calling:
129    /// ```no_run
130    /// substrate_wasm_builder::WasmBuilder::new()
131    ///     .with_current_project()
132    ///     .import_memory()
133    ///     .export_heap_base()
134    ///     .build();
135    /// ```
136    pub fn build_using_defaults() {
137        WasmBuilder::new()
138            .with_current_project()
139            .import_memory()
140            .export_heap_base()
141            .build();
142    }
143
144    /// Init the wasm builder with the recommended default values.
145    ///
146    /// In contrast to [`Self::build_using_defaults`] it does not build the WASM binary directly.
147    ///
148    /// This is the same as calling:
149    /// ```no_run
150    /// substrate_wasm_builder::WasmBuilder::new()
151    ///     .with_current_project()
152    ///     .import_memory()
153    ///     .export_heap_base();
154    /// ```
155    pub fn init_with_defaults() -> Self {
156        WasmBuilder::new()
157            .with_current_project()
158            .import_memory()
159            .export_heap_base()
160    }
161
162    /// Enable exporting `__heap_base` as global variable in the WASM binary.
163    ///
164    /// This adds `-C link-arg=--export=__heap_base` to `RUST_FLAGS`.
165    pub fn export_heap_base(mut self) -> Self {
166        self.export_heap_base = true;
167        self
168    }
169
170    /// Set the name of the file that will be generated in `OUT_DIR`.
171    ///
172    /// This file needs to be included to get access to the build WASM binary.
173    ///
174    /// If this function is not called, `file_name` defaults to `wasm_binary.rs`
175    pub fn set_file_name(mut self, file_name: impl Into<String>) -> Self {
176        self.file_name = Some(file_name.into());
177        self
178    }
179
180    /// Instruct the linker to import the memory into the WASM binary.
181    ///
182    /// This adds `-C link-arg=--import-memory` to `RUST_FLAGS`.
183    pub fn import_memory(mut self) -> Self {
184        self.import_memory = true;
185        self
186    }
187
188    /// Append the given `flag` to `cargo rustc` invocation.
189    ///
190    /// `flag` is appended as is, so it needs to be a valid flag.
191    pub fn append_to_cargo_flags(mut self, flag: impl Into<String>) -> Self {
192        self.cargo_flags.push(flag.into());
193        self
194    }
195
196    /// Append the given `flag` to `RUST_FLAGS`.
197    ///
198    /// `flag` is appended as is, so it needs to be a valid flag.
199    pub fn append_to_rust_flags(mut self, flag: impl Into<String>) -> Self {
200        self.rust_flags.push(flag.into());
201        self
202    }
203
204    /// Enable the given feature when building the wasm binary.
205    ///
206    /// `feature` needs to be a valid feature that is defined in the project `Cargo.toml`.
207    pub fn enable_feature(mut self, feature: impl Into<String>) -> Self {
208        self.features_to_enable.push(feature.into());
209        self
210    }
211
212    /// Enable generation of the metadata hash.
213    ///
214    /// This will compile the runtime once, fetch the metadata, build the metadata hash and
215    /// then compile again with the env `RUNTIME_METADATA_HASH` set. For more information
216    /// about the metadata hash see [RFC78](https://polkadot-fellows.github.io/RFCs/approved/0078-merkleized-metadata.html).
217    ///
218    /// - `token_symbol`: The symbol of the main native token of the chain.
219    /// - `decimals`: The number of decimals of the main native token.
220    #[cfg(feature = "metadata-hash")]
221    pub fn enable_metadata_hash(mut self, token_symbol: impl Into<String>, decimals: u8) -> Self {
222        self.enable_metadata_hash = Some(MetadataExtraInfo {
223            token_symbol: token_symbol.into(),
224            decimals,
225        });
226
227        self
228    }
229
230    /// Disable the check for the `runtime_version` wasm section.
231    ///
232    /// By default the `wasm-builder` will ensure that the `runtime_version` section will
233    /// exists in the build wasm binary. This `runtime_version` section is used to get the
234    /// `RuntimeVersion` without needing to call into the wasm binary. However, for some
235    /// use cases (like tests) you may want to disable this check.
236    pub fn disable_runtime_version_section_check(mut self) -> Self {
237        self.disable_runtime_version_section_check = true;
238        self
239    }
240
241    /// Build the WASM binary.
242    pub fn build(mut self) {
243        let target = crate::runtime_target();
244        if target == RuntimeTarget::Wasm {
245            if self.export_heap_base {
246                self.rust_flags
247                    .push("-C link-arg=--export=__heap_base".into());
248            }
249
250            if self.import_memory {
251                self.rust_flags.push("-C link-arg=--import-memory".into());
252            }
253        }
254
255        let out_dir = PathBuf::from(env::var("OUT_DIR").expect("`OUT_DIR` is set by cargo!"));
256        let file_path = out_dir.join(
257            self.file_name
258                .clone()
259                .unwrap_or_else(|| "wasm_binary.rs".into()),
260        );
261
262        if check_skip_build() {
263            // If we skip the build, we still want to make sure to be called when an env variable
264            // changes
265            generate_rerun_if_changed_instructions();
266
267            provide_dummy_wasm_binary_if_not_exist(&file_path);
268
269            return;
270        }
271
272        build_project(
273            target,
274            file_path,
275            self.project_cargo_toml,
276            self.cargo_flags,
277            self.rust_flags.join(" "),
278            self.features_to_enable,
279            self.file_name,
280            !self.disable_runtime_version_section_check,
281            #[cfg(feature = "metadata-hash")]
282            self.enable_metadata_hash,
283        );
284
285        // As last step we need to generate our `rerun-if-changed` stuff. If a build fails, we don't
286        // want to spam the output!
287        generate_rerun_if_changed_instructions();
288    }
289}
290
291/// Generate the name of the skip build environment variable for the current crate.
292fn generate_crate_skip_build_env_name() -> String {
293    format!(
294        "SKIP_{}_WASM_BUILD",
295        env::var("CARGO_PKG_NAME")
296            .expect("Package name is set")
297            .to_uppercase()
298            .replace('-', "_"),
299    )
300}
301
302/// Checks if the build of the WASM binary should be skipped.
303fn check_skip_build() -> bool {
304    env::var(crate::SKIP_BUILD_ENV).is_ok() ||
305		env::var(generate_crate_skip_build_env_name()).is_ok() ||
306		// If we are running in docs.rs, let's skip building.
307		// https://docs.rs/about/builds#detecting-docsrs
308		env::var("DOCS_RS").is_ok()
309}
310
311/// Provide a dummy WASM binary if there doesn't exist one.
312fn provide_dummy_wasm_binary_if_not_exist(file_path: &Path) {
313    if !file_path.exists() {
314        crate::write_file_if_changed(
315            file_path,
316            "pub const WASM_BINARY: Option<&[u8]> = None;\
317			 pub const WASM_BINARY_BLOATY: Option<&[u8]> = None;",
318        );
319    }
320}
321
322/// Generate the `rerun-if-changed` instructions for cargo to make sure that the WASM binary is
323/// rebuilt when needed.
324fn generate_rerun_if_changed_instructions() {
325    // Make sure that the `build.rs` is called again if one of the following env variables changes.
326    println!("cargo:rerun-if-env-changed={}", crate::SKIP_BUILD_ENV);
327    println!("cargo:rerun-if-env-changed={}", crate::FORCE_WASM_BUILD_ENV);
328    println!(
329        "cargo:rerun-if-env-changed={}",
330        generate_crate_skip_build_env_name()
331    );
332}
333
334/// Build the currently built project as wasm binary.
335///
336/// The current project is determined by using the `CARGO_MANIFEST_DIR` environment variable.
337///
338/// `file_name` - The name + path of the file being generated. The file contains the
339/// constant `WASM_BINARY`, which contains the built wasm binary.
340///
341/// `project_cargo_toml` - The path to the `Cargo.toml` of the project that should be built.
342///
343/// `default_rustflags` - Default `RUSTFLAGS` that will always be set for the build.
344///
345/// `features_to_enable` - Features that should be enabled for the project.
346///
347/// `wasm_binary_name` - The optional wasm binary name that is extended with
348/// `.compact.compressed.wasm`. If `None`, the project name will be used.
349///
350/// `check_for_runtime_version_section` - Should the wasm binary be checked for the
351/// `runtime_version` section?
352fn build_project(
353    target: RuntimeTarget,
354    file_name: PathBuf,
355    project_cargo_toml: PathBuf,
356    default_cargo_flags: Vec<String>,
357    default_rustflags: String,
358    features_to_enable: Vec<String>,
359    wasm_binary_name: Option<String>,
360    check_for_runtime_version_section: bool,
361    #[cfg(feature = "metadata-hash")] enable_metadata_hash: Option<MetadataExtraInfo>,
362) {
363    // Init jobserver as soon as possible
364    crate::wasm_project::get_jobserver();
365    let cargo_cmd = match crate::prerequisites::check(target) {
366        Ok(cmd) => cmd,
367        Err(err_msg) => {
368            eprintln!("{err_msg}");
369            process::exit(1);
370        }
371    };
372
373    let (wasm_binary, bloaty) = crate::wasm_project::create_and_compile(
374        target,
375        &project_cargo_toml,
376        &default_cargo_flags,
377        &default_rustflags,
378        cargo_cmd,
379        features_to_enable,
380        wasm_binary_name,
381        check_for_runtime_version_section,
382        #[cfg(feature = "metadata-hash")]
383        enable_metadata_hash,
384    );
385
386    let (wasm_binary, wasm_binary_bloaty) = if let Some(wasm_binary) = wasm_binary {
387        (
388            wasm_binary.wasm_binary_path_escaped(),
389            bloaty.bloaty_path_escaped(),
390        )
391    } else {
392        (bloaty.bloaty_path_escaped(), bloaty.bloaty_path_escaped())
393    };
394
395    crate::write_file_if_changed(
396        file_name,
397        format!(
398            r#"
399				pub const WASM_BINARY: Option<&[u8]> = Some(include_bytes!("{wasm_binary}"));
400				pub const WASM_BINARY_BLOATY: Option<&[u8]> = Some(include_bytes!("{wasm_binary_bloaty}"));
401			"#,
402            wasm_binary = wasm_binary,
403            wasm_binary_bloaty = wasm_binary_bloaty,
404        ),
405    );
406}
gsubstrate_wasm_builder/builder.rs

gsubstrate_wasm_builder/
builder.rs
