ReadMe

README.md

@@ -1,3 +1,106 @@
 # ReactionSystemsGUI
 
 Repository for the GUI of [ReactionSystem](https://tautocrono.it/elvis/ReactionSystems).
+
+# Install Rust
+
+## Linux instructions
+
+Install either from the official site [rustup.rs](https://rustup.rs/) or via a package manager.
+
+```
+sudo apt install rustup # Ubuntu & Debian
+
+sudo dnf install rustup # Fedora
+
+sudo pacman -S rustup # Arch
+
+brew install rustup # MacOS
+```
+
+It is important to install `rustup` and not just the barebone `rust` utility in order to add the wasm32 target to compile for web.
+
+Then run `rustup default stable` to install a target. To install the wasm32 a script is provided at [`./reaction_systems_gui/setup_web.sh`](./reaction_systems_gui/setup_web.sh).
+
+# How to build and run
+
+A simple script is provided to check for errors during development at [`./reaction_systems_gui/check.sh`](./reaction_systems_gui/check.sh).
+
+In order to format the code in a uniform way run `cargo +nightly fmt`.
+
+## Native Application
+
+To build simply run `cargo build` or `cargo b`. To build and run `cargo run` or `cargo r`.
+This will build and run a debug version without additional features.
+
+The project has one feature flag: `persistence` that can be enabled when building with `cargo r --features "persistence"` or `cargo r --all-features`.
+
+## Web Application
+
+A script is provided to build wasm binary at [`./reaction_systems_gui/build_web.sh`](./reaction_systems_gui/build_web.sh). The binary generated by rust is then optimized by `wasm-opt`.
+Install it from [binaryen](https://github.com/WebAssembly/binaryen):
+
+```
+sudo apt install binaryen # Ubuntu & Debian
+
+sudo dnf install binaryen # Fedora
+
+sudo pacman -S binaryen # Arch
+
+brew install binaryen # MacOS
+
+```
+
+or skip the optimization with the flag `--fast`.
+
+To run locally serve the files in the `reaction_systems_gui/docs/` folder with a simple server. For example install `basic-http-server` with
+`cargo install basic-http-server` and run with the script [`./reaction_systems_gui/start_server.sh`](./reaction_systems_gui/start_server.sh).
+
+
+# Possible issues
+
+* Error running `cargo r`
+	
+	```
+	Running 'target/debug/reaction_systems_gui'
+	
+	thread 'main' panicked at reaction_systems_gui/src/main.rs:28:6:
+	Failed to run native example: WinitEventLoop(Os(OsError { line: 765, file: "/home/elvis/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/winit-0.30.12/src/platform_impl/linux/mod.rs", error: Misc("neither WAYLAND_DISPLAY nor WAYLAND_SOCKET nor DISPLAY is set.") }))
+	note: run with 'RUST_BACKTRACE=1' environment variable to display a backtrace
+	```
+	
+	To run you need to have a display server running so it's not possible to run as terminal utility.
+	
+* Error executing `setup_web.sh`
+	
+	```
+	error: rustup could not choose a version of rustup to run, because one wasn't specified explicitly, and no default is configured.
+	help: run 'rustup default stable' to download the latest stable release of Rust and set it as your default toolchain.
+	```
+	
+	No default target specified. Run `rustup-init` or `rustup default stable`.
+
+* Infinite loading on web page
+	
+	Check that `./build_web.sh` is succesful. Forcefully reaload the page in the browser to refresh the cache.
+
+
+* Error executing `build_web.sh`
+	
+	```
+	Building rust…
+	    Finished `release` profile [optimized] target(s) in 0.14s
+	./build_web.sh: line 49: jq: command not found
+	```
+	
+	The utility `jq` is needed to run `wasm-bindgen`. Install it with:
+	
+	```
+	sudo apt install jq # Ubuntu & Debian
+	
+	sudo dnf install jq # Fedora
+	
+	sudo pacman -S jq # Arch
+	
+	brew install jq # MacOS
+	```

reaction_systems_gui/build_web.sh

@@ -28,14 +28,9 @@ while test $# -gt 0; do
   esac
 done
 
-# ./setup_web.sh # <- call this first!
-
 CRATE_NAME="reaction_systems_gui"
-CRATE_NAME_SNAKE_CASE="${CRATE_NAME//-/_}" # for those who name crates with-kebab-case
+CRATE_NAME_SNAKE_CASE="${CRATE_NAME//-/_}"
 
-# This is required to enable the web_sys clipboard API which egui_web uses
-# https://rustwasm.github.io/wasm-bindgen/api/web_sys/struct.Clipboard.html
-# https://rustwasm.github.io/docs/wasm-bindgen/web-sys/unstable-apis.html
 export RUSTFLAGS='--cfg=web_sys_unstable_apis --cfg getrandom_backend="wasm_js"'
 
 # Clear output from old stuff:

reaction_systems_gui/check.sh

@@ -1,5 +1,4 @@
 #!/bin/bash
-# This scripts runs various CI-like checks in a convenient way.
 set -eux
 
 cargo check --workspace --all-targets

reaction_systems_gui/setup_web.sh

@@ -7,4 +7,4 @@ cargo install wasm-bindgen-cli
 cargo update -p wasm-bindgen
 
 # For local tests with `./start_server`:
-cargo install basic-http-server
+# cargo install basic-http-server