Avida-ED-App-Builder

Purpose: This project builds self-contained, per-platform executables for Avida-ED, including embedded web assets and an integrated browser window.

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

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
├── tools/
│   ├── Dockerfile.fetch     # Pulls known-good Avida-ED builds (from aed-docker or web)
│   ├── fetch_assets.sh
│   └── inject_webroot.rs
├── packaging/
│   ├── linux/               # AppImage build scripts
│   ├── mac/                 # macOS .app bundler
│   └── windows/             # Windows SFX packager (WebView2 Fixed)
├── docker-compose.yml
├── Makefile
└── 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
• 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)

# 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:

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:

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

make VER=v4 build-linux   # or build-mac

Windows (PowerShell)

make VER=v4 build-win

Output:

server-ui/target/release/avidaed_onefile[.exe]

You can test-run it directly:

./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.

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:

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

2. Extract it somewhere, e.g. C:\SDKs\WebView2.FixedRuntime.

3. Run:

   make VER=v4 winexe
   

   or manually:

   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.

make VER=v4 macapp

Output:

Avida-ED-v4.app/
└── Contents/
    ├── MacOS/Avida-ED
    └── Info.plist

You can optionally package as a .dmg:

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):

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:

   image: welsberr/aed-docker:v5
   

2. Run:

   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

• This Builder: MIT License © 2025 W.R. Elsberry and contributors.

• Includes open-source components:

  • wry
  • tiny-http
  • 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.

---