From c0294123d8ec2a117baa97acf7f0b9557043b462 Mon Sep 17 00:00:00 2001 From: Aaron Fenyes Date: Thu, 7 Aug 2025 17:23:46 -0700 Subject: [PATCH 1/8] Write a deployment packaging script The packaging script and the configuration files around it are based on the ones from the `Vectornaut/dyna3:demo-summer-2025` branch. --- README.md | 14 ++++++++++++++ app-proto/Trunk.toml | 2 ++ deploy/.gitignore | 5 +++++ tools/package-for-deployment.bash | 16 ++++++++++++++++ 4 files changed, 37 insertions(+) create mode 100644 app-proto/Trunk.toml create mode 100644 deploy/.gitignore create mode 100644 tools/package-for-deployment.bash diff --git a/README.md b/README.md index 3a29eb0..a085682 100644 --- a/README.md +++ b/README.md @@ -65,3 +65,17 @@ The latest prototype is in the folder `app-proto`. It includes both a user inter 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. +2. Use `bash` to run the packaging script `tools/package-for-deployment.bash`. + - 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 + bash tools/package-for-deployment.bash + ``` + - 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. \ No newline at end of file diff --git a/app-proto/Trunk.toml b/app-proto/Trunk.toml new file mode 100644 index 0000000..017deba --- /dev/null +++ b/app-proto/Trunk.toml @@ -0,0 +1,2 @@ +[build] +public_url = "./" \ No newline at end of file diff --git a/deploy/.gitignore b/deploy/.gitignore new file mode 100644 index 0000000..192f529 --- /dev/null +++ b/deploy/.gitignore @@ -0,0 +1,5 @@ +/dyna3.zip +/dyna3/index.html +/dyna3/dyna3-*.js +/dyna3/dyna3-*.wasm +/dyna3/main-*.css \ No newline at end of file diff --git a/tools/package-for-deployment.bash b/tools/package-for-deployment.bash new file mode 100644 index 0000000..743a508 --- /dev/null +++ b/tools/package-for-deployment.bash @@ -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 -- "$(readlink -f -- "$BASH_SOURCE")") +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" From 203e47397db962610daf7e0d61b462e7e78cdef7 Mon Sep 17 00:00:00 2001 From: Aaron Fenyes Date: Thu, 7 Aug 2025 18:06:26 -0700 Subject: [PATCH 2/8] Move `run-examples.sh` into the tools folder --- {app-proto => tools}/run-examples.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename {app-proto => tools}/run-examples.sh (89%) diff --git a/app-proto/run-examples.sh b/tools/run-examples.sh similarity index 89% rename from app-proto/run-examples.sh rename to tools/run-examples.sh index 861addf..0946d92 100644 --- a/app-proto/run-examples.sh +++ b/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" From b1d5db2dc2f52b4af56fa3e9fc95c5a6c89942e3 Mon Sep 17 00:00:00 2001 From: Aaron Fenyes Date: Thu, 7 Aug 2025 18:59:18 -0700 Subject: [PATCH 3/8] Make deployment script more like examples script --- README.md | 4 ++-- tools/package-for-deployment.bash | 16 ---------------- tools/package-for-deployment.sh | 16 ++++++++++++++++ 3 files changed, 18 insertions(+), 18 deletions(-) delete mode 100644 tools/package-for-deployment.bash create mode 100644 tools/package-for-deployment.sh diff --git a/README.md b/README.md index a085682..d77eef3 100644 --- a/README.md +++ b/README.md @@ -70,11 +70,11 @@ The latest prototype is in the folder `app-proto`. It includes both a user inter 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. -2. Use `bash` to run the packaging script `tools/package-for-deployment.bash`. +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 - bash tools/package-for-deployment.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. diff --git a/tools/package-for-deployment.bash b/tools/package-for-deployment.bash deleted file mode 100644 index 743a508..0000000 --- a/tools/package-for-deployment.bash +++ /dev/null @@ -1,16 +0,0 @@ -# set paths. this technique for getting the script location comes from -# `mklement0` on Stack Overflow -# -# https://stackoverflow.com/a/24114056 -# -tools=$(dirname -- "$(readlink -f -- "$BASH_SOURCE")") -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" diff --git a/tools/package-for-deployment.sh b/tools/package-for-deployment.sh new file mode 100644 index 0000000..fdda434 --- /dev/null +++ b/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" From 707b5bf52f27dc69e29e1dc2fd9e30ab379aed3d Mon Sep 17 00:00:00 2001 From: Aaron Fenyes Date: Thu, 7 Aug 2025 20:36:43 -0700 Subject: [PATCH 4/8] Update the instructions for running the examples --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d77eef3..cbc20aa 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,13 @@ The latest prototype is in the folder `app-proto`. It includes both a user inter ### Run the engine on some example problems 1. Go into the `app-proto` folder -2. Call `./run-examples` +2. 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* From d14c3031610b30367878673be7c30583e3c425a1 Mon Sep 17 00:00:00 2001 From: Aaron Fenyes Date: Thu, 7 Aug 2025 20:43:15 -0700 Subject: [PATCH 5/8] Make the instructions less location-dependent --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cbc20aa..30ca538 100644 --- a/README.md +++ b/README.md @@ -47,8 +47,7 @@ The latest prototype is in the folder `app-proto`. It includes both a user inter ### Run the engine on some example problems -1. Go into the `app-proto` folder -2. Use `sh` to run the script `tools/run-examples.sh` +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:* @@ -76,6 +75,7 @@ The latest prototype is in the folder `app-proto`. It includes both a user inter 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 serve --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: From 737e7252907f47b5970a7e80a0360227ef7e7aa5 Mon Sep 17 00:00:00 2001 From: Aaron Fenyes Date: Thu, 7 Aug 2025 20:47:22 -0700 Subject: [PATCH 6/8] Format the README instructions more consistently --- README.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 30ca538..13e9be1 100644 --- a/README.md +++ b/README.md @@ -25,37 +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. 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:* + - *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* + - *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") @@ -73,15 +73,15 @@ The latest prototype is in the folder `app-proto`. It includes both a user inter ### 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 serve --config app-proto --release` from there instead. +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 serve --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: + - *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`. + - *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. \ No newline at end of file + - *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* \ No newline at end of file From f979e2cbb3b24cc8ed8dbdb4daa92e1f048361c7 Mon Sep 17 00:00:00 2001 From: Aaron Fenyes Date: Fri, 8 Aug 2025 12:36:48 -0700 Subject: [PATCH 7/8] Switch README step notes from italic to roman --- README.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 13e9be1..72f2a3c 100644 --- a/README.md +++ b/README.md @@ -25,37 +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. 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:* + - 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* + - 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") @@ -64,7 +64,7 @@ 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 @@ -74,14 +74,14 @@ The latest prototype is in the folder `app-proto`. It includes both a user inter ### 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 serve --config app-proto --release` from there instead* + - 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 serve --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:* + - 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`* + - 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* \ No newline at end of file + - 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 \ No newline at end of file From ef9055e2b83fd913022ac8aa68f21e17e1865d02 Mon Sep 17 00:00:00 2001 From: Aaron Fenyes Date: Fri, 8 Aug 2025 12:53:58 -0700 Subject: [PATCH 8/8] Correct a copying error --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 72f2a3c..cf3e589 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ The latest prototype is in the folder `app-proto`. It includes both a user inter 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 serve --config app-proto --release` from there instead + - 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: