Allow building examples locally using helper script and zola config

README.md

@@ -21,3 +21,5 @@ A local server should start and you should be able to access a local version of
 ### Assets, Errors, and Examples pages
 
 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/).
+
+By default, the examples will load the same pre-built Wasm binaries also used for https://bevy.org/examples. If you want to build examples locally instead, for example to include debug info, have a look at `generate-wasm-examples/build_wasm_examples_debug.sh`. After its finished, you can start zola with `zola --config config.local.toml serve` to use the locally built examples.

config.local.toml

@@ -0,0 +1,34 @@
+# Zola config for compiling examples locally
+
+# The URL the site will be built for
+base_url = "http://127.0.0.1:1111"
+
+# Used for the Atom feed
+title = "Bevy Engine"
+
+# Whether to automatically compile all Sass files in the sass directory
+compile_sass = true
+
+# When set to "true", the generated HTML files are minified.
+minify_html = true
+
+# Whether to build a search index to be used later on by a JavaScript library
+build_search_index = true
+
+generate_feeds = true
+feed_limit = 1000
+
+taxonomies = [{ name = "news", feed = true }]
+
+[markdown]
+# Whether to do syntax highlighting
+# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
+highlight_code = true
+highlight_theme = "css"
+
+# Load extra syntaxes (e.g. WGSL) for syntax highlighting
+extra_syntaxes_and_themes = ["syntaxes"]
+
+[extra]
+wasm_webgl2_base_url = "http://127.0.0.1:1111/assets/examples/wasm_webgl2"
+wasm_webgpu_base_url = "http://127.0.0.1:1111/assets/examples/wasm_webgpu"

config.toml

@@ -29,3 +29,5 @@ extra_syntaxes_and_themes = ["syntaxes"]
 
 [extra]
 # Put all your custom variables here
+wasm_webgl2_base_url = "https://bevy-webgl2-examples.pages.dev"
+wasm_webgpu_base_url = "https://bevy-webgpu-examples.pages.dev"

generate-wasm-examples/build_wasm_examples_debug.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+
+# locally build wasm examples for testing
+# usage:
+#   ./build_wasm-examples_debug.sh 6 # builds the first 6 examples
+
+if ! command -v wasm-bindgen >/dev/null 2>&1
+then
+    echo "wasm-bindgen could not be found - install it using: cargo install wasm-bindgen-cli"
+    exit 1
+fi
+
+if [ -z "$1" ]
+  then
+    echo "Missing example amount, use: './build_wasm_examples_debug.sh 5' to build the first 5 examples"
+    exit 1
+fi
+
+# Switch to script's directory, letting it be called from any folder.
+cd $(dirname $0)
+
+# generate_wasm_examples will clone the bevy repo to ./generate-wasm-examples/bevy by default.
+# If you want to use your fork or local changes, clone, symlink or copy your own bevy repo/folder
+# to ./generate-wasm-examples/bevy:
+# 1. $ cd ./generate-wasm-examples
+# 2. $ git clone https://github.com/<username>/bevy
+# OR
+# 1. $ cp ~/projects/my-bevy-fork ./generate-wasm-examples/bevy
+./generate_wasm_examples.sh --no-pull
+
+cd bevy
+
+git reset HEAD --hard
+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
+
+# remove the examples which this did not build, to make it easier to find which is which
+remove_missing() {
+    for d in "$1"/*; do
+        [[ -d "$d" ]] || continue
+        local base=$(basename "$d")
+        local match=$(find "$2" -maxdepth 1 -type d -iname "${base/-/?}" | head -n1)
+        if [[ -z "$match" ]]; then
+            rm -rf "$d"
+        else
+            remove_missing "$d" "$match"
+        fi
+    done
+}
+cd ..
+remove_missing "../content/examples" "../static/assets/examples/wasm_webgl2"

generate-wasm-examples/generate_wasm_examples.sh

@@ -7,13 +7,19 @@ cd $(dirname $0)
 
 # If Bevy folder already exists, pull the latest changes.
 if [[ -d bevy ]]; then
-    echo Bevy folder already exists, attempting to fetch latest changes.
+    echo Bevy folder already exists.
 
     cd bevy
 
-    # Attempts to fetch the latest commits, which should only happen every Bevy release.
-    git pull --depth=1
+    if [[ $* != *--no-pull* ]]; then
+        # Attempts to fetch the latest commits, which should only happen every Bevy release.
+        git pull --depth=1
+    fi
 else
+    if [[ $* == *--no-pull* ]]; then
+        echo "--no-pull was specified, but Bevy folder doesn't exist"
+        exit 1
+    fi
     echo Bevy folder does not exist, cloning repository.
 
     # Clone Bevy's latest branch from scratch, only downloading the latest commit.

templates/example-webgpu.html

@@ -1,7 +1,7 @@
 {% extends "layouts/example.html" %}
 
 {% block examples_url %}/examples-webgpu{% endblock examples_url %}
-{% block wasm_base_url %}https://bevy-webgpu-examples.pages.dev{% endblock wasm_base_url %}
+{% block wasm_base_url %}{{ config.extra.wasm_webgpu_base_url | safe }}{% endblock wasm_base_url %}
 {% block callout_modifier %}warning{% endblock callout_modifier %}
 {% block callout %}
 <strong>Support Warning.</strong>

templates/example.html

@@ -1,7 +1,7 @@
 {% extends "layouts/example.html" %}
 
 {% block examples_url %}/examples{% endblock examples_url %}
-{% block wasm_base_url %}https://bevy-webgl2-examples.pages.dev{% endblock wasm_base_url %}
+{% block wasm_base_url %}{{ config.extra.wasm_webgl2_base_url | safe }}{% endblock wasm_base_url %}
 {% block callout_modifier %}info{% endblock callout_modifier %}
 {% block callout %}
 This example is running in WebGL2 and should work in most browsers.