diff --git a/README.md b/README.md index 4e684ac..f4a796b 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,378 @@ # Avida-ED-App-Builder -A repository for tooling to make single-file executables or installers for Windows/MacOS/Linux for Avida-ED versions 3 and 4. +**Purpose:** +This project builds self-contained, per-platform executables for **Avida-ED**, including embedded web assets and an integrated browser window. -## Layout +Each artifact requires **no installation** β€” one file per OS: + +| Platform | Artifact Type | Browser Runtime | Example Output | +| ----------- | ---------------------------- | ------------------------------ | ----------------------------------- | +| **Linux** | `.AppImage` | Bundled WebKitGTK | `Avida-ED-v4-Linux-x86_64.AppImage` | +| **Windows** | `.exe` (SFX self-extracting) | Bundled WebView2 Fixed Runtime | `Avida-ED-v4-Windows.exe` | +| **macOS** | `.app` bundle | Built-in WKWebView | `Avida-ED-v4.app` | + +All artifacts embed the same core Rust binary (`avidaed_onefile`) that: + +* Serves the **Avida-ED web app** over a local HTTP server, +* Opens an integrated browser window (WebView) displaying the app, +* Requires **no external browser** or dependencies. + +--- + +## πŸ“ Repository Layout ``` -Avida-ED-App-Builder/ -β”œβ”€β”€ apps/ -β”‚ β”œβ”€β”€ v3/ # holds fetched Avida-ED 3 webroot (via compose target) -β”‚ └── v4/ # holds fetched Avida-ED 4 webroot (via compose target) -β”œβ”€β”€ packaging/ -β”‚ β”œβ”€β”€ linux/ -β”‚ β”‚ β”œβ”€β”€ Dockerfile.appimage -β”‚ β”‚ β”œβ”€β”€ AppRun -β”‚ β”‚ β”œβ”€β”€ make_appimage.sh -β”‚ β”‚ └── desktop/avidaed.desktop -β”‚ β”œβ”€β”€ mac/ -β”‚ β”‚ β”œβ”€β”€ make_macos_bundle.sh -β”‚ β”‚ └── Info.plist.tmpl -β”‚ └── windows/ -β”‚ β”œβ”€β”€ make_windows_sfx.ps1 -β”‚ β”œβ”€β”€ 7z.sfx # 7-Zip SFX module (binary, small) -β”‚ └── config.txt # SFX config for silent extract+run -β”œβ”€β”€ server-ui/ # Rust (wry + tiny-http) single-binary app +avidaed-onefile/ +β”œβ”€β”€ apps/ # Populated automatically by docker-compose (v3/v4 web assets) +β”‚ β”œβ”€β”€ v3/ +β”‚ └── v4/ +β”œβ”€β”€ server-ui/ # Rust application (HTTP server + embedded webview) +β”‚ β”œβ”€β”€ src/main.rs β”‚ β”œβ”€β”€ Cargo.toml -β”‚ β”œβ”€β”€ build.rs -β”‚ └── src/main.rs +β”‚ └── build.rs β”œβ”€β”€ tools/ -β”‚ β”œβ”€β”€ Dockerfile.fetch # pulls known-good assets (from aed-docker or URL) +β”‚ β”œβ”€β”€ Dockerfile.fetch # Pulls known-good Avida-ED builds (from aed-docker or web) β”‚ β”œβ”€β”€ fetch_assets.sh -β”‚ └── inject_webroot.rs # tiny helper to copy chosen webroot into ./server-ui/webroot/ +β”‚ └── inject_webroot.rs +β”œβ”€β”€ packaging/ +β”‚ β”œβ”€β”€ linux/ # AppImage build scripts +β”‚ β”œβ”€β”€ mac/ # macOS .app bundler +β”‚ └── windows/ # Windows SFX packager (WebView2 Fixed) β”œβ”€β”€ docker-compose.yml β”œβ”€β”€ Makefile -└── README.md +└── README.md ← (this file) ``` +--- + +## βš™οΈ System Requirements + +### Common tools (all OSes) + +* **Docker** β‰₯ 24.0 (for reproducible fetch stage) +* **Rust toolchain** (`cargo`, `rustc`) β‰₯ 1.75 + Install via [rustup.rs](https://rustup.rs/) +* **rsync**, **zip**, and a POSIX shell (`bash`, `make`) + +### Platform-specific + +| OS | Additional Requirements | +| ----------- | ----------------------------------------------------------------- | +| **Linux** | `libgtk-3-dev`, `libwebkit2gtk-4.0-dev`, `appimagetool` | +| **Windows** | PowerShell 5+, 7-Zip installed in `C:\Program Files\7-Zip\7z.exe` | +| **macOS** | Xcode command-line tools, optionally `create-dmg` | + +--- + +## 🧱 Step 1. Fetch the Avida-ED Web Assets + +Avida-ED web builds are pulled either: + +* from **a known-good Docker image** (`welsberr/aed-docker`), or +* from a **public URL** (fallback). + +### Option A β€” Using Docker (preferred) + +```bash +# Pull version 3 and version 4 assets +docker compose run --rm fetch-v3 +docker compose run --rm fetch-v4 +``` + +This: + +* spins up the minimal Alpine container in `tools/Dockerfile.fetch`, +* extracts the Avida-ED webroot from the container’s Nginx image, and +* deposits the result under `apps/v3/` and `apps/v4/`. + +You should see: + +``` +apps/ +β”œβ”€β”€ v3/Avida-ED/index.html +└── v4/Avida-ED-Eco/index.html +``` + +### Option B β€” Fetch via HTTPS (fallback) + +If Docker is unavailable: + +```bash +MODE=url URL=https://avida-ed.msu.edu/app4/ OUTDIR=./apps/v4 bash tools/fetch_assets.sh +``` + +--- + +## πŸͺ£ Step 2. Inject the Webroot into the Rust Project + +Before compiling, copy the correct web version into the `server-ui/webroot/` folder: + +```bash +make VER=v4 inject-v4 +# or for version 3: +make VER=v3 inject-v3 +``` + +This ensures the Rust compiler embeds the right `Avida-ED*` directory into the binary. + +--- + +## πŸ”§ Step 3. Build the Core Binary + +The binary (`avidaed_onefile`) runs both the HTTP server and browser window. + +### Linux / macOS + +```bash +make VER=v4 build-linux # or build-mac +``` + +### Windows (PowerShell) + +```powershell +make VER=v4 build-win +``` + +Output: + +``` +server-ui/target/release/avidaed_onefile[.exe] +``` + +You can test-run it directly: + +```bash +./server-ui/target/release/avidaed_onefile +``` + +It should open a browser window showing Avida-ED. + +--- + +## πŸ“¦ Step 4. Package Per Platform + +### 🐧 Linux β€” AppImage + +**Purpose:** single file runnable on most distros. + +```bash +make VER=v4 appimage +``` + +* Script: `packaging/linux/make_appimage.sh` +* Output: `Avida-ED-v4-Linux-x86_64.AppImage` +* Contains GTK, WebKitGTK, desktop entry, and icon. + +Run it: + +```bash +chmod +x Avida-ED-v4-Linux-x86_64.AppImage +./Avida-ED-v4-Linux-x86_64.AppImage +``` + +--- + +### πŸͺŸ Windows β€” Self-Extracting EXE + +**Purpose:** one `.exe` that includes: + +* the app binary, +* the WebView2 Fixed Runtime, +* a batch launcher. + +Steps: + +1. Download the **WebView2 Fixed Version Runtime** (x64) from Microsoft: + [https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section](https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section) +2. Extract it somewhere, e.g. `C:\SDKs\WebView2.FixedRuntime`. +3. Run: + + ```powershell + make VER=v4 winexe + ``` + + or manually: + + ```powershell + powershell -ExecutionPolicy Bypass -File packaging/windows/make_windows_sfx.ps1 ` + -Version v4 ` + -BinPath server-ui/target/release/avidaed_onefile.exe ` + -WV2Fixed C:\SDKs\WebView2.FixedRuntime + ``` + +Result: + +``` +Avida-ED-v4-Windows.exe +``` + +When run: + +* Extracts to `%TEMP%\Avida-ED-*`, +* Sets `WEBVIEW2_BROWSER_EXECUTABLE_FOLDER`, +* Launches immediately. + +--- + +### 🍎 macOS β€” .app Bundle + +**Purpose:** native macOS app bundle using built-in WKWebView. + +```bash +make VER=v4 macapp +``` + +Output: + +``` +Avida-ED-v4.app/ +└── Contents/ + β”œβ”€β”€ MacOS/Avida-ED + └── Info.plist +``` + +You can optionally package as a `.dmg`: + +```bash +brew install create-dmg +create-dmg Avida-ED-v4.app +``` + +--- + +## πŸ§ͺ Step 5. Test All Artifacts + +| Platform | Test Command | Expected Behavior | +| -------- | ------------------------------------- | ------------------------------------------ | +| Linux | `./Avida-ED-v4-Linux-x86_64.AppImage` | Opens a window running Avida-ED | +| Windows | `Avida-ED-v4-Windows.exe` | Self-extracts, runs, opens Avida-ED window | +| macOS | `open Avida-ED-v4.app` | Opens Avida-ED window | + +If you get a blank window: + +* Check that the embedded files exist in `server-ui/webroot/Avida-ED-Eco/`. +* Confirm MIME type for `.wasm` is `application/wasm` (already handled in code). + +--- + +## 🧰 Step 6. Build Everything Automatically + +To build all platforms and versions (assuming proper host environments): + +```bash +make fetch-v3 fetch-v4 +make all +``` + +On CI (GitHub Actions), artifacts are built via matrix: + +* OS: `ubuntu`, `windows`, `macos` +* Version: `v3`, `v4` + +Resulting artifacts are automatically uploaded. + +--- + +## πŸ” Updating Avida-ED Versions + +When a new Avida-ED version is released: + +1. Edit `docker-compose.yml` β†’ point the `fetch-*` service to the new tag: + + ```yaml + image: welsberr/aed-docker:v5 + ``` +2. Run: + + ```bash + docker compose run --rm fetch-v5 + make VER=v5 inject-v5 + make VER=v5 all + ``` +3. New artifacts: + + ``` + Avida-ED-v5-Windows.exe + Avida-ED-v5-Linux-x86_64.AppImage + Avida-ED-v5.app + ``` + +--- + +## πŸ” Verification Checklist + +βœ… **Inputs:** + +* `apps/v3/Avida-ED-Eco` and/or `apps/v4/Avida-ED-Eco` exist. +* Rust `cargo build --release` completes with no errors. + +βœ… **Outputs:** + +* Linux: `.AppImage` executes and opens Avida-ED window. +* Windows: `.exe` self-extracts and runs. +* macOS: `.app` bundle launches via `open`. + +βœ… **Network behavior:** + +* Runs only on `127.0.0.1` (loopback). +* No external calls except optional `LaunchBrowser()` telemetry if user enables. + +--- + +## 🧩 Design Notes + +* The Rust binary uses `tiny-http` (local server) + `wry` (embedded WebView) to eliminate dependency on the user’s browser. +* Web assets (HTML/JS/WASM/CSS) are embedded at compile time via `include_dir!`, ensuring deterministic, offline-safe execution. +* All build steps (fetch β†’ build β†’ package) are containerized or scripted to eliminate undocumented dependencies. + +--- + +## 🧭 Recovery Plan (if maintainer unavailable) + +If the primary maintainer is unavailable: + +1. Clone this repo. +2. Verify Docker, Rust, and system prerequisites. +3. Run `make fetch-v4` to repopulate the web assets. +4. Run `make VER=v4 all`. +5. Upload artifacts from the `packaging/` or root directory to release storage. +6. Test on each OS using a clean virtual machine. + +This process recreates all deliverables from scratch. + +--- + +## πŸͺͺ License & Credits + +* **Avida-ED** Β© Michigan State University. + Source: [https://github.com/DBlackwood/AvidaED_user_interface](https://github.com/DBlackwood/AvidaED_user_interface) +* **This Builder**: MIT License Β© 2025 W.R. Elsberry and contributors. +* Includes open-source components: + + * [`wry`](https://github.com/tauri-apps/wry) + * [`tiny-http`](https://github.com/tiny-http/tiny-http) + * [`AppImageKit`](https://github.com/AppImage/AppImageKit) + * Microsoft Edge **WebView2 Fixed Runtime** (redistributable license) + +--- + +### 🏁 Summary + +| Task | Command | +| ------------------------- | ------------------------- | +| Fetch all assets | `make fetch-v3 fetch-v4` | +| Build & test local binary | `make VER=v4 build-linux` | +| Produce Linux AppImage | `make VER=v4 appimage` | +| Produce Windows EXE | `make VER=v4 winexe` | +| Produce macOS app | `make VER=v4 macapp` | +| Build everything | `make all` | + + +## AI Disclosure + +This repository's content was largely derived from prompting +OpenAI's ChatGPT with GPT 5. + +--- + +