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
+	```