From 9a14d849c66d1691ff98fb7ef80bd93008ae9677 Mon Sep 17 00:00:00 2001 From: Bryce Date: Sun, 22 Mar 2026 18:38:48 -0700 Subject: [PATCH] Add BUILD.md with comprehensive build and release documentation --- desktop/BUILD.md | 192 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 desktop/BUILD.md diff --git a/desktop/BUILD.md b/desktop/BUILD.md new file mode 100644 index 00000000..3499c6ec --- /dev/null +++ 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 + + + + + com.apple.security.cs.allow-jit + + com.apple.security.cs.allow-unsigned-executable-memory + + com.apple.security.cs.disable-executable-page-protection + + com.apple.security.cs.disable-library-validation + + + +``` + +### 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. \ No newline at end of file