Allow customization of wasm-opt args (#486)

# Objective

Closes #442.

For further optimization, the user might want to get full control over
the flags that are passed to `wasm-opt`.
At the same time, users also need an easy way to enable or disable
`wasm-opt`, e.g. disabling it even in release mode or enabling it in dev
mode.

# Solution

I changed the ArgBuilder to deal with OsString instead of String, since
that's what we need to pass to the Command anyway.
This simplified this change, sorry for the noise in the diff.

- The `--wasm-opt` CLI flag now also accepts multiple string values.
These are passed as args to `wasm-opt`. Alternatively, you can still use
`true` to enable the default flags or `false` to disable `wasm-opt`
entirely.
- The `wasm-opt` config option now also accepts an array of args:

  ```toml
  [package.metadata.bevy_cli.web.release]
  wasm-opt = ["-Oz", "--enable-bulk-memory"]
  ```

# Testing

In <https://github.com/TimJentzsch/bevy_complex_repo>, the `workspace`
folder now contains a `wasm_opt` package where the new options are used
in the `Cargo.toml`.

Author: TimJentzsch

CHANGELOG.md

@@ -11,19 +11,23 @@ The format is based on [Keep a Changelog], and this project adheres to [Semantic
 
 **All Changes**: [`cli-v0.1.0-alpha.1...main`](https://github.com/TheBevyFlock/bevy_cli/compare/cli-v0.1.0-alpha.1...main)
 
+### Changed
+
+- You can now customize the flags passed to `wasm-opt` in both CLI and `Cargo.toml`. Simply pass a list of flags you want to use, e.g. `--wasm-opt=-Oz --wasm-opt=--enable-bulk-memory` in the CLI or `wasm-opt = ["-Oz", "--enable-bulk-memory"]` in the config.
+
 ## v0.1.0-alpha.1 - 2025-05-23
 
 **All Changes**: [`cli-v0.1.0-alpha.1`](https://github.com/TheBevyFlock/bevy_cli/commits/cli-v0.1.0-alpha.1)
 
 ### Added
 
 - `bevy new`: create new projects from a template using `cargo-generate` ([#2](https://github.com/TheBevyFlock/bevy_cli/pull/2))
-    - [`bevy_new_minimal`](https://github.com/TheBevyFlock/bevy_new_minimal) is the default template if none is specified ([#80](https://github.com/TheBevyFlock/bevy_cli/pull/80))
-    - There are shortcuts for templates from [TheBevyFlock](https://github.com/TheBevyFlock). For example, `-t 2d` uses [`bevy_new_2d`](https://github.com/TheBevyFlock/bevy_new_2d) ([#82](https://github.com/TheBevyFlock/bevy_cli/pull/82))
+  - [`bevy_new_minimal`](https://github.com/TheBevyFlock/bevy_new_minimal) is the default template if none is specified ([#80](https://github.com/TheBevyFlock/bevy_cli/pull/80))
+  - There are shortcuts for templates from [TheBevyFlock](https://github.com/TheBevyFlock). For example, `-t 2d` uses [`bevy_new_2d`](https://github.com/TheBevyFlock/bevy_new_2d) ([#82](https://github.com/TheBevyFlock/bevy_cli/pull/82))
 - `bevy lint`: invoke the linter if `bevy_lint` is installed ([#4](https://github.com/TheBevyFlock/bevy_cli/pull/4))
 - `bevy build` and `bevy run`: build and run your program with Bevy-specific configuration ([#76](https://github.com/TheBevyFlock/bevy_cli/pull/76), [#103](https://github.com/TheBevyFlock/bevy_cli/pull/103), [#102](https://github.com/TheBevyFlock/bevy_cli/pull/102), [#120](https://github.com/TheBevyFlock/bevy_cli/pull/120))
-    - You can use `bevy build web` and `bevy run web` to build and run your program for the web using Wasm.
-    - Web binaries can be optimized with `wasm-opt` ([#206](https://github.com/TheBevyFlock/bevy_cli/pull/206), [#430](https://github.com/TheBevyFlock/bevy_cli/pull/430))
-    - You can pass `--bundle` to pack all files needed for the web into a single folder ([#195](https://github.com/TheBevyFlock/bevy_cli/pull/195))
+  - You can use `bevy build web` and `bevy run web` to build and run your program for the web using Wasm.
+  - Web binaries can be optimized with `wasm-opt` ([#206](https://github.com/TheBevyFlock/bevy_cli/pull/206), [#430](https://github.com/TheBevyFlock/bevy_cli/pull/430))
+  - You can pass `--bundle` to pack all files needed for the web into a single folder ([#195](https://github.com/TheBevyFlock/bevy_cli/pull/195))
 - `bevy completions`: generate terminal auto-complete scripts for a variety of shells ([#265](https://github.com/TheBevyFlock/bevy_cli/pull/265))
 - The CLI can be configured with `[package.metadata.bevy_cli]` ([#331](https://github.com/TheBevyFlock/bevy_cli/pull/331), [#355](https://github.com/TheBevyFlock/bevy_cli/pull/355), [#351](https://github.com/TheBevyFlock/bevy_cli/pull/351))

MIGRATION.md

@@ -23,3 +23,23 @@ bevy run --no-default-features false
 bevy build --no-default-features
 bevy run
 ```
+
+### `--wasm-opt` needs a value
+
+You now need to provide an explicit value to the `--wasm-opt` flag.
+If you were using `--wasm-opt` you now need to use `--wasm-opt=true`.
+
+```sh
+# v0.1.0-alpha.1
+bevy build web --wasm-opt
+
+# v0.1.0-alpha.2
+bevy build web --wasm-opt=true
+```
+
+On the flip side, you can now customize the flags that are passed to `wasm-opt`:
+
+```sh
+# v0.1.0-alpha.2
+bevy build web --wasm-opt=-Oz --wasm-opt=--enable-bulk-memory
+```

docs/src/cli/configuration.md

@@ -13,12 +13,12 @@ The CLI supports two targets:
 
 For both these targets a release and dev [`profile`] exists that will automatically be chosen by the CLI:
 
-| **Profile Name**         | **Configuration Section**                          |
-|--------------------------|----------------------------------------------------|
-| `release`                | `[package.metadata.bevy_cli.native.release]`       |
-| `dev`                    | `[package.metadata.bevy_cli.native.dev]`           |
-| `web-release`            | `[package.metadata.bevy_cli.web.release]`          |
-| `web`                    | `[package.metadata.bevy_cli.web.dev]`              |
+| **Profile Name** | **Configuration Section**                    |
+| ---------------- | -------------------------------------------- |
+| `release`        | `[package.metadata.bevy_cli.native.release]` |
+| `dev`            | `[package.metadata.bevy_cli.native.dev]`     |
+| `web-release`    | `[package.metadata.bevy_cli.web.release]`    |
+| `web`            | `[package.metadata.bevy_cli.web.dev]`        |
 
 > **Note**
 >
@@ -50,6 +50,7 @@ wasm-opt = true
 [package.metadata.bevy_cli.release]
 default-features = false
 ```
+
 When building for web in release mode, the final merged configuration will be:
 
 ```toml
@@ -69,4 +70,3 @@ default-features = true
 ```
 
 [`profile`]: https://doc.rust-lang.org/cargo/reference/profiles.html
-

docs/src/cli/configuration/reference.md

@@ -2,10 +2,11 @@
 
 The following fields exist and can be configured:
 
-- [features](#features)
-- [default-features](#default-features)
-- [rustflags](#rustflags)
-- [wasm-opt](#wasm-opt)
+- [Configuration Reference](#configuration-reference)
+  - [`features`](#features)
+  - [`default-features`](#default-features)
+  - [`rustflags`](#rustflags)
+  - [`wasm-opt`](#wasm-opt)
 
 ## `features`
 
@@ -27,6 +28,6 @@ The following fields exist and can be configured:
 
 ## `wasm-opt`
 
-- Type: boolean
-- Default: true for release web builds
-- Note: Whether or not to use [`wasm-opt`](https://github.com/WebAssembly/binaryen?tab=readme-ov-file#wasm-opt) to optimize the web binary.
+- Type: boolean or array of strings
+- Default: true for web release builds, false for web dev builds and native builds
+- Note: Whether or not to use [`wasm-opt`](https://github.com/WebAssembly/binaryen?tab=readme-ov-file#wasm-opt) to optimize the web binary. The specific flags to be used can be passed as array of strings or `true` can be passed to use default options (`--strip-debug` and `-Os`).

docs/src/cli/web.md

@@ -47,6 +47,41 @@ opt-level = "z"
 
 Alternatively, you can change the profile entirely, e.g. `bevy run --profile=foo web`.
 
+## Optimization
+
+In addition to the compilation profiles, you can also optimize the Wasm binary via [`wasm-opt`](https://docs.rs/wasm-opt/latest/wasm_opt/).
+This can significantly reduce the size of the binary, but also improves performance.
+
+`wasm-opt` is enabled by default for release builds.
+If you haven't installed it, you will be asked to install it automatically.
+
+The optimization can be configured both via CLI args and `Cargo.toml`.
+You can either disable optimization with `false`, enable default values with `true` or provide a list of flags to pass to `wasm-opt` for full control.
+
+Setting it to `true` currently applies the `--strip-debug` and `-Os` flags.
+
+Examples with the CLI:
+
+- `--wasm-opt=false` to disable `wasm-opt` completely.
+- `--wasm-opt=true` to enable the default `wasm-opt` configuration.
+- `--wasm-opt=-Oz --wasm-opt=--enable-bulk-memory` to run `wasm-opt` with the `-Oz` and `--enable-bulk-memory` flags.
+
+The same can be accomplished with the following `Cargo.toml` configs:
+
+```toml
+[package.metadata.bevy_cli.web.release]
+# Disable wasm-opt even for release builds
+wasm-opt = false
+
+[package.metadata.bevy_cli.web.dev]
+# Enable wasm-opt even for dev builds, using the default configuration
+wasm-opt = true
+
+[package.metadata.bevy_cli.web.release]
+# Enable wasm-opt with custom flags
+wasm-opt = ["-Oz", "--enable-bulk-memory"]
+```
+
 ## Feature configuration
 
 Often, you want to enable certain features only in development mode or only for native and not web builds.

src/build/args.rs

@@ -1,5 +1,7 @@
 use clap::{ArgAction, Args, Subcommand};
 
+#[cfg(feature = "web")]
+use crate::external_cli::external_cli_args::ExternalCliArgs;
 use crate::{
     config::CliConfig,
     external_cli::{
@@ -68,15 +70,15 @@ impl BuildArgs {
         self.cargo_args.args_builder(self.is_web())
     }
 
-    /// Whether to use `wasm-opt`.
-    ///
-    /// Defaults to `true` for release builds.
+    /// The flags to use for `wasm-opt` if building for the web.
     #[cfg(feature = "web")]
-    pub(crate) fn use_wasm_opt(&self) -> bool {
+    pub(crate) fn wasm_opt_args(&self) -> ExternalCliArgs {
+        use crate::external_cli::external_cli_args::ExternalCliArgs;
+
         if let Some(BuildSubcommands::Web(web_args)) = &self.subcommand {
-            web_args.use_wasm_opt.map_or(self.is_release(), |v| v)
+            ExternalCliArgs::from_raw_args(web_args.wasm_opt.clone())
         } else {
-            false
+            ExternalCliArgs::Enabled(false)
         }
     }
 
@@ -107,10 +109,13 @@ impl BuildArgs {
             .clone()
             .or(config.rustflags());
 
+        #[cfg(feature = "web")]
+        let is_release = self.is_release();
+
         #[cfg(feature = "web")]
         if let Some(BuildSubcommands::Web(web_args)) = self.subcommand.as_mut() {
-            if web_args.use_wasm_opt.is_none() {
-                web_args.use_wasm_opt = config.wasm_opt();
+            if web_args.wasm_opt.is_empty() {
+                web_args.wasm_opt = config.wasm_opt(is_release).to_raw();
             }
         }
     }
@@ -127,10 +132,14 @@ pub enum BuildSubcommands {
 /// Additional Arguments for building a Bevy web project.
 #[derive(Debug, Args, Default)]
 pub struct BuildWebArgs {
-    // Bundle all web artifacts into a single folder.
+    /// Bundle all web artifacts into a single folder.
     #[arg(short = 'b', long = "bundle", action = ArgAction::SetTrue, default_value_t = false)]
     pub create_packed_bundle: bool,
-    // Use `wasm-opt` to optimize the wasm binary
-    #[arg(long = "wasm-opt")]
-    pub use_wasm_opt: Option<bool>,
+    /// Use `wasm-opt` to optimize the wasm binary
+    ///
+    /// Defaults to `true` for release builds.
+    /// Can be set to `false` to skip optimization.
+    /// You can also specify custom arguments to use.
+    #[arg(long = "wasm-opt", allow_hyphen_values = true)]
+    pub wasm_opt: Vec<String>,
 }

src/config.rs

@@ -7,6 +7,8 @@ use serde::Serialize;
 use serde_json::{Map, Value};
 use tracing::warn;
 
+use crate::external_cli::external_cli_args::ExternalCliArgs;
+
 /// Configuration for the `bevy_cli`.
 ///
 /// Allows customizing:
@@ -26,7 +28,7 @@ pub struct CliConfig {
     /// Additional flags for `rustc`
     rustflags: Vec<String>,
     /// Use `wasm-opt` to optimize wasm binaries.
-    wasm_opt: Option<bool>,
+    wasm_opt: Option<ExternalCliArgs>,
 }
 
 impl CliConfig {
@@ -73,10 +75,17 @@ impl CliConfig {
         Some(self.rustflags.clone().join(" "))
     }
 
-    /// Whether to use `wasm-opt`.
+    /// The `wasm-opt` configuration.
     #[cfg(feature = "web")]
-    pub fn wasm_opt(&self) -> Option<bool> {
-        self.wasm_opt
+    pub fn wasm_opt(&self, is_release: bool) -> ExternalCliArgs {
+        self.wasm_opt.clone().unwrap_or({
+            // Enable by default for release builds
+            if is_release {
+                ExternalCliArgs::Enabled(true)
+            } else {
+                ExternalCliArgs::Enabled(false)
+            }
+        })
     }
 
     /// Determine the Bevy CLI config as defined in the given package.
@@ -155,7 +164,7 @@ impl CliConfig {
             features: extract_features(metadata)?,
             default_features: extract_default_features(metadata)?,
             rustflags: extract_rustflags(metadata)?,
-            wasm_opt: extract_use_wasm_opt(metadata)?,
+            wasm_opt: extract_wasm_opt(metadata)?,
         })
     }
 
@@ -167,7 +176,7 @@ impl CliConfig {
         self.target = with.target.clone().or(self.target);
         self.default_features = with.default_features.or(self.default_features);
 
-        self.wasm_opt = with.wasm_opt.or(self.wasm_opt);
+        self.wasm_opt = with.wasm_opt.clone().or(self.wasm_opt);
 
         // Features and Rustflags are additive
         self.features.extend(with.features.iter().cloned());
@@ -254,12 +263,26 @@ fn extract_rustflags(cli_metadata: &Map<String, Value>) -> anyhow::Result<Vec<St
     }
 }
 
-fn extract_use_wasm_opt(cli_metadata: &Map<String, Value>) -> anyhow::Result<Option<bool>> {
-    if let Some(use_wasm_opt) = cli_metadata.get("wasm-opt") {
-        match use_wasm_opt {
-            Value::Bool(use_wasm_opt) => Ok(Some(use_wasm_opt).copied()),
+fn extract_wasm_opt(cli_metadata: &Map<String, Value>) -> anyhow::Result<Option<ExternalCliArgs>> {
+    if let Some(wasm_opt) = cli_metadata.get("wasm-opt") {
+        match wasm_opt {
+            Value::Bool(enabled) => Ok(Some(ExternalCliArgs::Enabled(*enabled))),
+            Value::Array(arr) => {
+                let args = arr
+                    .iter()
+                    .map(|value| {
+                        value
+                            .as_str()
+                            .map(std::string::ToString::to_string)
+                            .ok_or_else(|| {
+                                anyhow::anyhow!("each wasm-opt argument must be a string")
+                            })
+                    })
+                    .collect::<Result<Vec<String>, _>>()?;
+                Ok(Some(ExternalCliArgs::Args(args)))
+            }
             Value::Null => Ok(None),
-            _ => bail!("wasm-opt must be a boolean"),
+            _ => bail!("wasm-opt must be a boolean or an array of arguments to pass to wasm-opt"),
         }
     } else {
         Ok(None)
@@ -528,4 +551,54 @@ mod tests {
             assert!(extract_features(&cli_metadata).is_err());
         }
     }
+
+    mod extract_wasm_opt {
+        use super::*;
+
+        #[test]
+        fn should_return_none_if_no_wasm_opt_specified() -> anyhow::Result<()> {
+            let cli_metadata = Map::new();
+            assert_eq!(extract_wasm_opt(&cli_metadata)?, None);
+            Ok(())
+        }
+
+        #[test]
+        fn should_return_enabled_if_wasm_opt_is_true() -> anyhow::Result<()> {
+            let mut cli_metadata = Map::new();
+            cli_metadata.insert("wasm-opt".to_owned(), true.into());
+            assert_eq!(
+                extract_wasm_opt(&cli_metadata)?,
+                Some(ExternalCliArgs::Enabled(true))
+            );
+            Ok(())
+        }
+
+        #[test]
+        fn should_return_disabled_if_wasm_opt_is_false() -> anyhow::Result<()> {
+            let mut cli_metadata = Map::new();
+            cli_metadata.insert("wasm-opt".to_owned(), false.into());
+            assert_eq!(
+                extract_wasm_opt(&cli_metadata)?,
+                Some(ExternalCliArgs::Enabled(false))
+            );
+            Ok(())
+        }
+
+        #[test]
+        fn should_return_args_if_wasm_opt_is_array() -> anyhow::Result<()> {
+            let mut cli_metadata = Map::new();
+            cli_metadata.insert(
+                "wasm-opt".to_owned(),
+                vec!["-Oz".to_owned(), "--enable-bulk-memory".to_owned()].into(),
+            );
+            assert_eq!(
+                extract_wasm_opt(&cli_metadata)?,
+                Some(ExternalCliArgs::Args(vec![
+                    "-Oz".to_owned(),
+                    "--enable-bulk-memory".to_owned()
+                ]))
+            );
+            Ok(())
+        }
+    }
 }