Skip to content

Allow building examples locally using helper script and zola config #2275

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Allow building examples locally using helper script and zola config #2275

wants to merge 4 commits into from
+97 −5

Conversation

laundmo
Copy link
Contributor

@laundmo laundmo commented Oct 1, 2025

The intention behind this PR is to allow contributors to easily build wasm examples locally, useful for example to include debug info.

For contributors, that means they now have access to:

  • A script to build a number of examples, and generate the examples pages only for those built.
  • A separate Zola config for serving the local assets, to be used after the above script.

There are a number of things about this (and the current setup as a whole) that I feel are not ideal:

  • Mixture of bash scripts and multiple small rust CLIs, spread across both repos. This means theres no central place for some kinds of modifications to go, and some changes I would think are useful will require PRs against both repos. Thats enough of a hurdle I don't want to attempt those.
  • The new script can only limit the amount of examples built, theres no way to choose a sepecific example. This is a limitation of tools/example-showcase in the bevy repo, which I did not want to touche. See first point.
  • I had to write code to compare the different structures for example betweeen the paths example-showcase build-wasm-examples generates: 2D Rendering/Bloom 2D and the ones example-showcase build-website-list generates: 2d-rendering/bloom-2d

@alice-i-cecile alice-i-cecile added C-Usability A-Examples X-Contentious There are nontrivial implications that should be thought through labels Oct 1, 2025
rparrett
rparrett reviewed Oct 1, 2025
View reviewed changes
config.local.toml
@@ -0,0 +1,34 @@
# Zola config for compiling examples locally
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO we shouldn't maintain a separate nearly identical copy of this file just for this purpose. I would move the local versions of wasm_webgl2_base_url to comments in config.toml.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally, i'd love to not need either, but Zola is limited in this regard. Maybe comments can work, but my goal was that there won't be a need to edit a git tracked file for at least the basic usecases.

generate-wasm-examples/build_wasm_examples_debug.sh
Comment on lines +31 to +32
CARGO_PROFILE_RELEASE_OPT_LEVEL='z' CARGO_PROFILE_RELEASE_DEBUG="true" cargo run -p example-showcase -- --per-page $1 --page 0 build-wasm-examples --content-folder ../../static/assets/examples/wasm_webgl2 --api webgl2 --website-hacks
CARGO_PROFILE_RELEASE_OPT_LEVEL='z' CARGO_PROFILE_RELEASE_DEBUG="true" cargo run -p example-showcase -- --per-page $1 --page 0 build-wasm-examples --content-folder ../../static/assets/examples/wasm_webgpu --api webgpu
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, it's a bit unfortunate to repeat these invocations here in this new script. Would prefer that generate_wasm_example.sh handle the limiting.

Also, I think I or someone may have added a --debug option to example-showcase.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but generate_wasm_examples.sh never calls example-showcase build-wasm-example? only the CI yaml has another version of this.

Copy link
Contributor Author

@laundmo laundmo Oct 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I think I or someone may have added a --debug option to example-showcase.

Just tried this: the option does exist, but its not implemented for the build-wasm-example command and silently gets ignored. Its only applied for the run command as far as I can tell: https://github.com/bevyengine/bevy/blob/0b8844a3a060b2a5b7c3302bd951e39fbf6aa1c3/tools/example-showcase/src/main.rs#L723

Copy link
Contributor

@rparrett rparrett Oct 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah right, sorry!

And yeah, looks like the new debug option isn't piped through from example-showcase.

README.md Outdated

These pages need to be generated in a separate step by running the shell scripts in the `generate-assets`, `generate-errors`, and `generate-wasm-examples` directories. On Windows, you can use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) or [git bash](https://gitforwindows.org/).

The Examples page uses the same WASM binaries as https://bevy.org/examples by default. To build examples locally, have a look at `generate-wasm-examples/build_wasm_examples_debug.sh`. After running it, start zola with `zola --config config.local.toml serve` to use the locally built examples.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first sentence is slightly confusing for me. I would suggest something like "uses the same pre-built Wasm binaries" to clarify a tiny bit.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've just pushed a re-wording

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@mockersf mockersf Awaiting requested review from mockersf

1 more reviewer

@rparrett rparrett rparrett left review comments

Reviewers whose approvals may not affect merge requirements
Assignees
No one assigned
Labels
A-Examples C-Usability S-Needs-Review X-Contentious There are nontrivial implications that should be thought through
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@laundmo @rparrett @alice-i-cecile