Avida-ED-App-Builder/README.md

# 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](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.

---