From dc5020752b62505d355d0f54e4e2ca9d8d6cd316 Mon Sep 17 00:00:00 2001
From: Aaron Fenyes <aaron.fenyes@fareycircles.ooo>
Date: Mon, 25 Nov 2024 01:37:48 -0800
Subject: [PATCH] Say how to run the prototype, examples, and tests

---
 README.md              | 48 ++++++++++++++++++++++++++++++++++++++++++
 app-proto/run-examples |  2 ++
 2 files changed, 50 insertions(+)

diff --git a/README.md b/README.md
index 9ea9cbf..1ea3302 100644
--- a/README.md
+++ b/README.md
@@ -17,3 +17,51 @@ Note that currently this is just the barest beginnings of the project, more of a
 * Able to run in browser (so implemented in WASM-compatible language)
 
 * Produce scalable graphics of 3D diagrams, and maybe STL files (or other fabricatable file format) as well.
+
+## Prototype
+
+The latest prototype is in the folder `app-proto`. It includes both a user interface and a numerical constraint-solving engine.
+
+### 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)
+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
+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
+
+### Play with the prototype
+
+1. Go into the `app-proto` folder
+2. 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*
+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*
+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*
+     
+     ```julia
+     include("irisawa-hexlet.jl")
+     for (step, scaled_loss) in enumerate(history_alt.scaled_loss)
+       println(rpad(step-1, 4), " | ", scaled_loss)
+     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*
+
+### Run the automated tests
+
+1. Go into the `app-proto` folder
+2. Call `cargo test`
diff --git a/app-proto/run-examples b/app-proto/run-examples
index 9791a9d..e079089 100755
--- a/app-proto/run-examples
+++ b/app-proto/run-examples
@@ -1,3 +1,5 @@
+#!/bin/bash
+
 # run all Cargo examples, as described here:
 #
 #   Karol Kuczmarski. "Add examples to your Rust libraries"