Automatically configure getrandom web backend #547
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,52 @@ | ||||||
| # `getrandom` | ||||||
|
|
||||||
| `getrandom` is a popular crate that allows retrieving random data from system resources. | ||||||
| It is used by `bevy` and many other crates. | ||||||
| It provides multiple backends which retrieve the random data from different sources. | ||||||
|
|
||||||
| This works great, except when targeting the web. | ||||||
| Unlike most other platforms, there is no compilation target available that guarantees web APIs to exist. | ||||||
| Just because you're building for `wasm32-unknown-unknown` doesn't necessarily mean you are making a web app -- | ||||||
| you could also be building a standalone Wasm application. | ||||||
|
|
||||||
| So the target cannot be used to automatically activate the web backend. | ||||||
| Features are also inadequate: They are additive, so if _any_ dependency pulled in the web feature, | ||||||
| the backend would be used everywhere or the build would be broken. | ||||||
| Considering the security-sensitive nature of random data, this was deemed unacceptable. | ||||||
|
|
||||||
| So in addition to a feature to make the backend available, | ||||||
| `getrandom` requires you to pass a `RUSTFLAG` to the compiler to activate the backend. | ||||||
| This guarantees that the backend can only be configured once (by "outer" package). | ||||||
|
|
||||||
| ## Configuring the web backend | ||||||
|
|
||||||
| Since you are the application developer, you _know_ that you are building for the web and not just any Wasm target. | ||||||
| This allows you to set up the `getrandom` backend properly, for example like this: | ||||||
|
|
||||||
| ```toml | ||||||
| [target.'cfg(all(target_family = "wasm", any(target_os = "unknown", target_os = "none")))'.dependencies] | ||||||
| getrandom = { version = "0.3", features = ["wasm_js"] } | ||||||
| getrandom_02 = { version = "0.2", features = ["js"], package = "getrandom" } | ||||||
| ``` | ||||||
|
|
||||||
| This activates the necessary feature flags for `getrandom`, accounting for both v0.2 and v0.3 (as they can both be in the dependency tree, depending on the Bevy version used). | ||||||
|
|
||||||
| Additionally, you need to add `--cfg getrandom_backend="wasm_js"` to your `RUSTFLAGS`. | ||||||
| This can be done in several places: | ||||||
|
|
||||||
| - Setting `rustflags` in `.cargo/config.toml` | ||||||
| - Setting `build.rustflags` in `Cargo.toml` | ||||||
| - Setting the `RUSTFLAGS` env variable when running `cargo` | ||||||
|
|
||||||
| However, not that the rustflags are not merged, but _overwritten_. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| So if you have e.g. `rustflags` defined in your `~/.cargo/config.toml` to optimize your compile times, | ||||||
| but then have again `rustflags` defined in your workspace to set the `getrandom` backend, | ||||||
| only the workspace `rustflags` will be used. | ||||||
|
|
||||||
| ## Automated by the CLI | ||||||
|
|
||||||
| The Bevy CLI automatically applies the web `getrandom` backend when `bevy build web` or `bevy run web` is used | ||||||
| and you haven't configured the backend yourself. | ||||||
| This allows more projects to work out-of-the-box for the web and simplifies the configuration. | ||||||
|
|
||||||
| You can still explicitly define the backend if you wish (or need to). | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,117 @@ | ||||||
| use semver::{Version, VersionReq}; | ||||||
|
|
||||||
| use crate::{commands::build::BuildArgs, external_cli::cargo}; | ||||||
|
|
||||||
| /// Apply the web backend to getrandom. | ||||||
| /// | ||||||
| /// This is a consistent pain point for users, so we try to automate it. | ||||||
| /// | ||||||
| /// There's two things you need to do: | ||||||
| /// | ||||||
| /// 1. Enabling the corresponding feature in the `getrandom` dependency | ||||||
| /// 2. Setting the `--cfg getrandom_backend="wasm_js"` RUSTFLAG | ||||||
| /// | ||||||
| /// This function can handle both v2 and v3 dependencies. | ||||||
| /// | ||||||
| /// If `getrandom` is not a dependency, nothing happens. | ||||||
| pub fn apply_getrandom_backend(args: &mut BuildArgs, target: &str) -> anyhow::Result<bool> { | ||||||
| // Obtaining the metadata again to filter dependencies and their features by the used target | ||||||
| let metadata = cargo::metadata::metadata_with_args(["--filter-platform", target])?; | ||||||
|
|
||||||
| let getrandom_packages = metadata | ||||||
| .packages | ||||||
| .iter() | ||||||
| .filter(|pkg| pkg.name.as_str() == "getrandom") | ||||||
| .collect::<Vec<_>>(); | ||||||
|
|
||||||
| if getrandom_packages.is_empty() { | ||||||
| // Nothing to do when `getrandom` isn't used | ||||||
| return Ok(false); | ||||||
| } | ||||||
|
|
||||||
| let mut backend_applied = false; | ||||||
|
|
||||||
| // The package allows us to find the correct version of the dependency | ||||||
| let v2 = getrandom_packages | ||||||
| .iter() | ||||||
| .find(|pkg| VersionReq::parse("^0.2").unwrap().matches(&pkg.version)); | ||||||
|
|
||||||
| // getrandom v2 needs the `js` feature enabled | ||||||
| if let Some(v2) = v2 { | ||||||
| // The resolved dependency includes the features that are enabled | ||||||
| let dep = metadata | ||||||
| .resolve | ||||||
| .as_ref() | ||||||
| .and_then(|resolve| resolve.nodes.iter().find(|node| node.id == v2.id)); | ||||||
|
|
||||||
| let v2_feature = "js"; | ||||||
|
|
||||||
| if let Some(dep) = dep | ||||||
| && !dep.features.iter().any(|feature| **feature == v2_feature) | ||||||
| { | ||||||
| backend_applied = true; | ||||||
|
|
||||||
| add_feature_config( | ||||||
| &mut args.cargo_args.common_args.config, | ||||||
| &v2.version, | ||||||
| v2_feature, | ||||||
| ); | ||||||
| } | ||||||
| } | ||||||
|
|
||||||
| // getrandom v3 needs the `wasm_js` feature enabled | ||||||
| // and the `--cfg getrandom_backend="wasm_js"` RUSTFLAG must be set | ||||||
| let v3 = getrandom_packages | ||||||
| .iter() | ||||||
| .find(|pkg| VersionReq::parse("^0.3").unwrap().matches(&pkg.version)); | ||||||
|
|
||||||
| if let Some(v3) = v3 { | ||||||
| let dep = metadata | ||||||
| .resolve | ||||||
| .as_ref() | ||||||
| .and_then(|resolve| resolve.nodes.iter().find(|node| node.id == v3.id)); | ||||||
|
|
||||||
| let v3_feature = "wasm_js"; | ||||||
|
|
||||||
| if let Some(dep) = dep | ||||||
| && !dep.features.iter().any(|feature| **feature == v3_feature) | ||||||
| { | ||||||
| backend_applied = true; | ||||||
|
|
||||||
| add_feature_config( | ||||||
| &mut args.cargo_args.common_args.config, | ||||||
| &v3.version, | ||||||
| v3_feature, | ||||||
| ); | ||||||
| } | ||||||
|
|
||||||
| let mut rustflags = args | ||||||
| .cargo_args | ||||||
| .common_args | ||||||
| .rustflags | ||||||
| .clone() | ||||||
| .unwrap_or_default(); | ||||||
|
|
||||||
| // Since this is only called with the `web` commands, | ||||||
| // we can safely assume that Wasm = web in this context. | ||||||
| // Still, we allow the user to override this assumption | ||||||
| // by configuring a different backend | ||||||
| if !rustflags.contains("getrandom_backend") { | ||||||
| backend_applied = true; | ||||||
| rustflags += " --cfg getrandom_backend=\"wasm_js\""; | ||||||
| args.cargo_args.common_args.rustflags = Some(rustflags); | ||||||
| } | ||||||
| } | ||||||
|
|
||||||
| Ok(backend_applied) | ||||||
| } | ||||||
|
|
||||||
| /// Adds the feature configuration for the `getrandom` dependency | ||||||
| fn add_feature_config(config: &mut Vec<String>, version: &Version, feature: &str) { | ||||||
| // Distinguish entries by version to allow multiple versions to be configured | ||||||
| let table = format!("dependencies.getrandom_{}{}", version.major, version.minor); | ||||||
| // The config arg doesn't support inline tables, so each entries must be configured separately | ||||||
|
There was a problem hiding this comment. Typo:
Suggested change
|
||||||
| config.push(format!(r#"{table}.package="getrandom""#)); | ||||||
| config.push(format!(r#"{table}.version="{}""#, version)); | ||||||
| config.push(format!(r#"{table}.features=["{feature}"]"#)); | ||||||
| } | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.