Add BUILD.md with comprehensive build and release documentation

2026-03-22 18:38:48 -07:00
parent 03d70388d5
commit 9a14d849c6
1 changed files with 192 additions and 0 deletions
--- a/desktop/BUILD.md
+++ b/desktop/BUILD.md
@@ -0,0 +1,192 @@
+# Build & Release Checklist
+
+## Quick Start
+
+```bash
+# Build minimal JREs (run once or when Java version changes)
+./build-jres.sh 11
+
+# Build all platforms
+./build-all.sh
+```
+
+## Build Artifacts
+
+| Platform | Location | Size |
+|----------|----------|------|
+| Windows x64 | `target/windows/TicksTales.exe` | ~121MB |
+| Linux x64 | `target/linux/amd64/Tick's Tales` | ~132MB |
+| macOS x64 | `target/osx/Tick's Tales.app` | ~121MB |
+| macOS ARM64 | `target/osx-arm64/Tick's Tales.app` | ~120MB |
+
+## Remaining Production Tasks
+
+### 1. Windows Icon Embedding
+
+The `icons.ico` file exists but packr doesn't embed it into the .exe. This requires `rcedit`:
+
+**Option A: On Windows**
+```powershell
+# Install rcedit via chocolatey
+choco install rcedit
+
+# Embed icon
+rcedit "target/windows/TicksTales.exe" --set-icon "icons.ico"
+```
+
+**Option B: On Linux with Wine**
+```bash
+# Install wine and rcedit
+sudo apt install wine64
+
+# Download rcedit from https://github.com/electron/rcedit/releases
+wget https://github.com/electron/rcedit/releases/download/v2.0.0/rcedit-x64.exe
+
+# Embed icon
+wine rcedit-x64.exe "target/windows/TicksTales.exe" --set-icon "icons.ico"
+```
+
+### 2. macOS Code Signing
+
+Required for macOS 10.15+ and notarization:
+
+```bash
+# Requirements:
+# - Apple Developer account
+# - Developer ID Application certificate installed in Keychain
+
+# Sign the app bundle
+codesign --sign "Developer ID Application: Your Name (TEAMID)" \
+  --verbose=10 \
+  --timestamp \
+  --force \
+  --options runtime \
+  --entitlements entitlements.plist \
+  --deep \
+  "target/osx/Tick's Tales.app"
+
+# Verify signature
+codesign --verify --deep --strict --verbose=2 "target/osx/Tick's Tales.app"
+```
+
+**entitlements.plist** (required for Java apps):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.cs.allow-jit</key>
+    <true/>
+    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+    <true/>
+    <key>com.apple.security.cs.disable-executable-page-protection</key>
+    <true/>
+    <key>com.apple.security.cs.disable-library-validation</key>
+    <true/>
+</dict>
+</plist>
+```
+
+### 3. macOS Notarization
+
+Required for distribution outside Mac App Store:
+
+```bash
+# Requirements:
+# - Apple Developer account with app-specific password
+# - Store password in Keychain: xcrun notarytool store-credentials "TICKSTALES"
+
+# Create zip for notarization
+ditto -c -k --keepParent "target/osx/Tick's Tales.app" "TicksTales-macos.zip"
+
+# Submit for notarization
+xcrun notarytool submit "TicksTales-macos.zip" --keychain-profile "TICKSTALES" --wait
+
+# Staple the ticket
+xcrun stapler staple "target/osx/Tick's Tales.app"
+
+# Verify
+spctl --assess --verbose=4 --type execute "target/osx/Tick's Tales.app"
+```
+
+### 4. Steam Distribution
+
+**Prepare content for Steam:**
+
+```bash
+# Create Steam build directory structure
+mkdir -p steam-build/windows
+mkdir -p steam-build/linux
+mkdir -p steam-build/osx
+
+# Copy Windows build
+cp -r target/windows/* steam-build/windows/
+
+# Copy Linux build
+cp -r target/linux/amd64/* steam-build/linux/
+
+# Copy macOS builds (after signing)
+cp -r "target/osx/Tick's Tales.app" steam-build/osx/
+cp -r "target/osx-arm64/Tick's Tales.app" steam-build/osx-arm64/
+```
+
+**Steam depot splits (recommended):**
+- Depot 1: Windows x64
+- Depot 2: Linux x64
+- Depot 3: macOS x64
+- Depot 4: macOS ARM64
+
+Users only download the depot for their platform.
+
+## Build Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `build-jres.sh` | Downloads Corretto JDKs and creates minimal JREs |
+| `build-all.sh` | Main build script for all platforms |
+| `build-windows.json` | Packr config for Windows |
+| `build-linux-64.json` | Packr config for Linux |
+| `build-osx.json` | Packr config for macOS x64 |
+| `build-osx-arm64.json` | Packr config for macOS ARM64 |
+| `*-steam.json` | Steam-enabled variants |
+| `icons.ico` | Windows icon (needs embedding) |
+| `icons.icns` | macOS icon |
+| `tickstales.desktop` | Linux menu entry |
+
+## Version Management
+
+Version is read from `last-release` file:
+```bash
+# Update version
+echo "31" > last-release
+./build-all.sh  # Will build v2.0.31
+```
+
+## JVM Arguments (in packr configs)
+
+Current configuration:
+```
+-Duse-repl=false           # Disable REPL
+-Dui_scale=1.0             # UI scaling
+-Dclojure.compiler.direct-linking=true  # Performance optimization
+-Dis-desktop=true          # Platform detection
+-Dplatform=desktop         # Platform detection
+-XstartOnFirstThread       # macOS only (required for LWJGL)
+```
+
+Consider adding for production:
+```
+-Xmx2G                     # Max heap size
+-XX:+UseG1GC              # Garbage collector
+-Dfile.encoding=UTF-8     # File encoding
+```
+
+## Troubleshooting
+
+**"GLFW_PLATFORM_UNAVAILABLE"** - No display available (headless environment), normal for CI/build servers.
+
+**"Unable to initialize GLFW"** - Same as above, test on actual desktop.
+
+**Windows missing icon** - Run rcedit step.
+
+**macOS "app is damaged"** - App not signed/notarized, run signing steps.