From 3452781bf75ef21dd706f7700a48c1fed586e70f Mon Sep 17 00:00:00 2001 From: Ben Frankel Date: Sat, 6 Jul 2024 08:38:29 -0700 Subject: [PATCH] Deduplicate Wasm optimization instructions (#14173) See https://github.com/bevyengine/bevy-website/pull/1538 for context. --- docs-template/EXAMPLE_README.md.tpl | 58 ++++------------------------- examples/README.md | 58 ++++------------------------- 2 files changed, 16 insertions(+), 100 deletions(-) diff --git a/docs-template/EXAMPLE_README.md.tpl b/docs-template/EXAMPLE_README.md.tpl index 9d4a009d0e4d0..f173c67445b6d 100644 --- a/docs-template/EXAMPLE_README.md.tpl +++ b/docs-template/EXAMPLE_README.md.tpl @@ -256,61 +256,26 @@ In browsers, audio is not authorized to start without being triggered by an user ### Optimizing On the web, it's useful to reduce the size of the files that are distributed. -With rust, there are many ways to improve your executable sizes. -Here are some. +With rust, there are many ways to improve your executable sizes, starting with +the steps described in [the quick-start guide](https://bevyengine.org/learn/quick-start/getting-started/setup/#compile-with-performance-optimizations). -#### 1. Tweak your `Cargo.toml` - -Add a new [profile](https://doc.rust-lang.org/cargo/reference/profiles.html) -to your `Cargo.toml`: - -```toml -[profile.wasm-release] -# Use release profile as default values -inherits = "release" - -# Optimize with size in mind, also try "s", sometimes it is better. -# This doesn't increase compilation times compared to -O3, great improvements -opt-level = "z" - -# Do a second optimization pass removing duplicate or unused code from dependencies. -# Slows compile times, marginal improvements -lto = "fat" - -# When building crates, optimize larger chunks at a time -# Slows compile times, marginal improvements -codegen-units = 1 -``` - -Now, when building the final executable, use the `wasm-release` profile -by replacing `--release` by `--profile wasm-release` in the cargo command. +Now, when building the executable, use `--profile wasm-release` instead of `--release`: ```sh cargo build --profile wasm-release --example lighting --target wasm32-unknown-unknown ``` -Make sure your final executable size is smaller, some of those optimizations -may not be worth keeping, due to compilation time increases. - -#### 2. Use `wasm-opt` from the binaryen package - -Binaryen is a set of tools for working with wasm. It has a `wasm-opt` CLI tool. - -First download the `binaryen` package, -then locate the `.wasm` file generated by `wasm-bindgen`. -It should be in the `--out-dir` you specified in the command line, -the file name should end in `_bg.wasm`. - -Then run `wasm-opt` with the `-Oz` flag. Note that `wasm-opt` is _very slow_. - -Note that `wasm-opt` optimizations might not be as effective if you -didn't apply the optimizations from the previous section. +To apply `wasm-opt`, first locate the `.wasm` file generated in the `--out-dir` of the +earlier `wasm-bindgen-cli` command (the filename should end with `_bg.wasm`), then run: ```sh wasm-opt -Oz --output optimized.wasm examples/wasm/target/lighting_bg.wasm mv optimized.wasm examples/wasm/target/lighting_bg.wasm ``` +Make sure your final executable size is actually smaller. Some optimizations +may not be worth keeping due to compilation time increases. + For a small project with a basic 3d model and two lights, the generated file sizes are, as of July 2022, as follows: @@ -323,13 +288,6 @@ the generated file sizes are, as of July 2022, as follows: |"z" + "thin" + codegen-units = 1 | 5.3M | 11M | |"z" + "fat" + codegen-units = 1 | 4.8M | 8.5M | -There are more advanced optimization options available, -check the following pages for more info: - -- -- -- - ### Loading Assets To load assets, they need to be available in the folder examples/wasm/assets. Cloning this diff --git a/examples/README.md b/examples/README.md index 7681782792dfd..55e148e2360bf 100644 --- a/examples/README.md +++ b/examples/README.md @@ -664,61 +664,26 @@ In browsers, audio is not authorized to start without being triggered by an user ### Optimizing On the web, it's useful to reduce the size of the files that are distributed. -With rust, there are many ways to improve your executable sizes. -Here are some. +With rust, there are many ways to improve your executable sizes, starting with +the steps described in [the quick-start guide](https://bevyengine.org/learn/quick-start/getting-started/setup/#compile-with-performance-optimizations). -#### 1. Tweak your `Cargo.toml` - -Add a new [profile](https://doc.rust-lang.org/cargo/reference/profiles.html) -to your `Cargo.toml`: - -```toml -[profile.wasm-release] -# Use release profile as default values -inherits = "release" - -# Optimize with size in mind, also try "s", sometimes it is better. -# This doesn't increase compilation times compared to -O3, great improvements -opt-level = "z" - -# Do a second optimization pass removing duplicate or unused code from dependencies. -# Slows compile times, marginal improvements -lto = "fat" - -# When building crates, optimize larger chunks at a time -# Slows compile times, marginal improvements -codegen-units = 1 -``` - -Now, when building the final executable, use the `wasm-release` profile -by replacing `--release` by `--profile wasm-release` in the cargo command. +Now, when building the executable, use `--profile wasm-release` instead of `--release`: ```sh cargo build --profile wasm-release --example lighting --target wasm32-unknown-unknown ``` -Make sure your final executable size is smaller, some of those optimizations -may not be worth keeping, due to compilation time increases. - -#### 2. Use `wasm-opt` from the binaryen package - -Binaryen is a set of tools for working with wasm. It has a `wasm-opt` CLI tool. - -First download the `binaryen` package, -then locate the `.wasm` file generated by `wasm-bindgen`. -It should be in the `--out-dir` you specified in the command line, -the file name should end in `_bg.wasm`. - -Then run `wasm-opt` with the `-Oz` flag. Note that `wasm-opt` is _very slow_. - -Note that `wasm-opt` optimizations might not be as effective if you -didn't apply the optimizations from the previous section. +To apply `wasm-opt`, first locate the `.wasm` file generated in the `--out-dir` of the +earlier `wasm-bindgen-cli` command (the filename should end with `_bg.wasm`), then run: ```sh wasm-opt -Oz --output optimized.wasm examples/wasm/target/lighting_bg.wasm mv optimized.wasm examples/wasm/target/lighting_bg.wasm ``` +Make sure your final executable size is actually smaller. Some optimizations +may not be worth keeping due to compilation time increases. + For a small project with a basic 3d model and two lights, the generated file sizes are, as of July 2022, as follows: @@ -731,13 +696,6 @@ the generated file sizes are, as of July 2022, as follows: |"z" + "thin" + codegen-units = 1 | 5.3M | 11M | |"z" + "fat" + codegen-units = 1 | 4.8M | 8.5M | -There are more advanced optimization options available, -check the following pages for more info: - -- -- -- - ### Loading Assets To load assets, they need to be available in the folder examples/wasm/assets. Cloning this