Write a deployment packaging script (#113)

Adds a packaging script to help automate deployment. Documents the deployment process in `README.md`.

Also, moves `run-examples.sh` into the tools folder that we created for the packaging script.

Co-authored-by: Aaron Fenyes <aaron.fenyes@fareycircles.ooo>
Reviewed-on: StudioInfinity/dyna3#113
Co-authored-by: Vectornaut <vectornaut@nobody@nowhere.net>
Co-committed-by: Vectornaut <vectornaut@nobody@nowhere.net>

README.md

@@ -25,32 +25,37 @@ The latest prototype is in the folder `app-proto`. It includes both a user inter
 ### Install the prerequisites
 
 1. Install [`rustup`](https://rust-lang.github.io/rustup/): the officially recommended Rust toolchain manager
-   * It's available on Ubuntu as a [Snap](https://snapcraft.io/rustup)
+   - It's available on Ubuntu as a [Snap](https://snapcraft.io/rustup)
 2. Call `rustup default stable` to "download the latest stable release of Rust and set it as your default toolchain"
-   * If you forget, the `rustup` [help system](https://github.com/rust-lang/rustup/blob/d9b3601c3feb2e88cf3f8ca4f7ab4fdad71441fd/src/errors.rs#L109-L112) will remind you
+   - If you forget, the `rustup` [help system](https://github.com/rust-lang/rustup/blob/d9b3601c3feb2e88cf3f8ca4f7ab4fdad71441fd/src/errors.rs#L109-L112) will remind you
 3. Call `rustup target add wasm32-unknown-unknown` to add the [most generic 32-bit WebAssembly target](https://doc.rust-lang.org/nightly/rustc/platform-support/wasm32-unknown-unknown.html)
 4. Call `cargo install wasm-pack` to install the [WebAssembly toolchain](https://rustwasm.github.io/docs/wasm-pack/)
 5. Call `cargo install trunk` to install the [Trunk](https://trunkrs.dev/) web-build tool
 6. Add the `.cargo/bin` folder in your home directory to your executable search path
-   * This lets you call Trunk, and other tools installed by Cargo, without specifying their paths
-   * On POSIX systems, the search path is stored in the `PATH` environment variable
+   - This lets you call Trunk, and other tools installed by Cargo, without specifying their paths
+   - On POSIX systems, the search path is stored in the `PATH` environment variable
 
 ### Play with the prototype
 
 1. From the `app-proto` folder, call `trunk serve --release` to build and serve the prototype
-   * *The crates the prototype depends on will be downloaded and served automatically*
-   * *For a faster build, at the expense of a much slower prototype, you can call `trunk serve` without the `--release` flag*
-   * *If you want to stay in the top-level folder, you can call `trunk serve --config app-proto [--release]`* from there instead.
+   - The crates the prototype depends on will be downloaded and served automatically
+   - For a faster build, at the expense of a much slower prototype, you can call `trunk serve` without the `--release` flag
+   - If you want to stay in the top-level folder, you can call `trunk serve --config app-proto [--release]` from there instead.
 3. In a web browser, visit one of the URLs listed under the message `INFO 📡 server listening at:`
-   * *Touching any file in the `app-proto` folder will make Trunk rebuild and live-reload the prototype*
+   - Touching any file in the `app-proto` folder will make Trunk rebuild and live-reload the prototype
 4. Press *ctrl+C* in the shell where Trunk is running to stop serving the prototype
 
 ### Run the engine on some example problems
 
-1. Go into the `app-proto` folder
-2. Call `./run-examples`
-   * *For each example problem, the engine will print the value of the loss function at each optimization step*
-   * *The first example that prints is the same as the Irisawa hexlet example from the Julia version of the engine prototype. If you go into `engine-proto/gram-test`, launch Julia, and then*
+1. Use `sh` to run the script `tools/run-examples.sh`
+   - The script is location-independent, so you can do this from anywhere in the dyna3 repository
+   - The call from the top level of the repository is:
+     
+     ```bash
+     sh tools/run-examples.sh
+     ```
+   - For each example problem, the engine will print the value of the loss function at each optimization step
+   - The first example that prints is the same as the Irisawa hexlet example from the Julia version of the engine prototype. If you go into `engine-proto/gram-test`, launch Julia, and then
      
      ```julia
      include("irisawa-hexlet.jl")
@@ -59,9 +64,24 @@ The latest prototype is in the folder `app-proto`. It includes both a user inter
      end
      ```
      
-     *you should see that it prints basically the same loss history until the last few steps, when the lower default precision of the Rust engine really starts to show*
+     you should see that it prints basically the same loss history until the last few steps, when the lower default precision of the Rust engine really starts to show
 
 ### Run the automated tests
 
 1. Go into the `app-proto` folder
 2. Call `cargo test`
+
+### Deploy the prototype
+
+1. From the `app-proto` folder, call `trunk build --release`
+   - Building in [release mode](https://doc.rust-lang.org/cargo/reference/profiles.html#release) produces an executable which is smaller and often much faster, but harder to debug and more time-consuming to build
+   - If you want to stay in the top-level folder, you can call `trunk build --config app-proto --release` from there instead
+2. Use `sh` to run the packaging script `tools/package-for-deployment.sh`.
+   - The script is location-independent, so you can do this from anywhere in the dyna3 repository
+   - The call from the top level of the repository is:
+     ```bash
+     sh tools/package-for-deployment.sh
+     ```
+   - This will overwrite or replace the files in `deploy/dyna3`
+3. Put the contents of `deploy/dyna3` in the folder on your server that the prototype will be served from.
+   - To simplify uploading, you might want to combine these files into an archive called `deploy/dyna3.zip`. Git has been set to ignore this path

app-proto/Trunk.toml

@@ -0,0 +1,2 @@
+[build]
+public_url = "./"

deploy/.gitignore

@@ -0,0 +1,5 @@
+/dyna3.zip
+/dyna3/index.html
+/dyna3/dyna3-*.js
+/dyna3/dyna3-*.wasm
+/dyna3/main-*.css

tools/package-for-deployment.sh

@@ -0,0 +1,16 @@
+# set paths. this technique for getting the script location comes from
+# `mklement0` on Stack Overflow
+#
+#   https://stackoverflow.com/a/24114056
+#
+TOOLS=$(dirname -- $0)
+SRC="$TOOLS/../app-proto/dist"
+DEST="$TOOLS/../deploy/dyna3"
+
+# remove the old hash-named files
+[ -e "$DEST"/dyna3-*.js ] && rm "$DEST"/dyna3-*.js
+[ -e "$DEST"/dyna3-*.wasm ] && rm "$DEST"/dyna3-*.wasm
+[ -e "$DEST"/main-*.css ] && rm "$DEST"/main-*.css
+
+# copy the distribution
+cp -r "$SRC/." "$DEST"

tools/run-examples.sh

@@ -8,7 +8,7 @@
 # the application prototype
 
 # find the manifest file for the application prototype
-MANIFEST="$(dirname -- $0)/Cargo.toml"
+MANIFEST="$(dirname -- $0)/../app-proto/Cargo.toml"
 
 # set up the command that runs each example
 RUN_EXAMPLE="cargo run --manifest-path $MANIFEST --example"