Deduplicate Wasm optimization instructions (#14173)

See https://github.com/bevyengine/bevy-website/pull/1538 for context.
This commit is contained in:
Ben Frankel 2024-07-06 08:38:29 -07:00 committed by GitHub
parent ea2a7e5552
commit 3452781bf7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 16 additions and 100 deletions

View file

@ -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:
- <https://rustwasm.github.io/book/reference/code-size.html>
- <https://rustwasm.github.io/docs/wasm-bindgen/reference/optimize-size.html>
- <https://rustwasm.github.io/book/game-of-life/code-size.html>
### Loading Assets
To load assets, they need to be available in the folder examples/wasm/assets. Cloning this

View file

@ -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:
- <https://rustwasm.github.io/book/reference/code-size.html>
- <https://rustwasm.github.io/docs/wasm-bindgen/reference/optimize-size.html>
- <https://rustwasm.github.io/book/game-of-life/code-size.html>
### Loading Assets
To load assets, they need to be available in the folder examples/wasm/assets. Cloning this