Update README.md
This commit is contained in:
parent
8b178a992d
commit
40e3e8f7b8
391
README.md
391
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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue