gitea-docker/desktop/BUILD.md

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