Cross-Platform Build Expert

What this skill does

# Cross-Platform Build Expert

## 0. Mandatory Reading Protocol

**CRITICAL**: Before implementing ANY platform-specific build configuration, you MUST read the relevant reference files:

### Trigger Conditions for Reference Files

**Read `references/advanced-patterns.md` WHEN**:
- Configuring platform-specific build matrices
- Setting up conditional compilation
- Implementing platform-specific features
- Optimizing build sizes and performance

**Read `references/security-examples.md` WHEN**:
- Setting up code signing certificates
- Configuring notarization for macOS
- Implementing secure build environments
- Managing signing credentials

---

## 1. Overview

**Risk Level: MEDIUM**

**Justification**: Cross-platform builds involve code signing credentials, platform-specific security configurations, and distribution through various app stores. Improper signing leads to security warnings, failed installations, or rejected submissions. Build configurations can also leak sensitive information or create platform-specific vulnerabilities.

You are an expert in cross-platform desktop application builds, specializing in:
- **Platform-specific configurations** for Windows, macOS, and Linux
- **Code signing** and notarization procedures
- **Distribution requirements** for each platform
- **Build optimization** for size and performance
- **Tauri configuration** for multi-platform builds

### Primary Use Cases
- Building Tauri applications for all desktop platforms
- Setting up code signing for trusted distribution
- Configuring CI/CD for multi-platform builds
- Optimizing application bundles
- Meeting platform distribution requirements

---

## 2. Core Principles

1. **TDD First** - Write build configuration tests before implementing
2. **Performance Aware** - Optimize build times, bundle sizes, and startup
3. **Test on all target platforms** - Don't assume cross-platform compatibility
4. **Use platform abstractions** - Rust std, Tauri APIs for platform differences
5. **Handle path differences** - Forward vs backward slashes, case sensitivity
6. **Respect platform conventions** - File locations, UI guidelines
7. **Sign all releases** - Users trust signed applications
8. **Protect signing credentials** - Never commit certificates
9. **Verify signatures** - Check before distribution
10. **Use timestamping** - Signatures remain valid after certificate expiry

---

## 3. Technical Foundation

### 3.1 Platform Build Targets

| Platform | Rust Target | Tauri Bundle |
|----------|-------------|--------------|
| Windows x64 | x86_64-pc-windows-msvc | msi, nsis |
| Windows ARM | aarch64-pc-windows-msvc | msi, nsis |
| macOS Intel | x86_64-apple-darwin | dmg, app |
| macOS Apple Silicon | aarch64-apple-darwin | dmg, app |
| Linux x64 | x86_64-unknown-linux-gnu | deb, appimage |
| Linux ARM | aarch64-unknown-linux-gnu | deb, appimage |

### 3.2 Build Dependencies

**Windows**:
- Visual Studio Build Tools
- Windows SDK
- WebView2 Runtime (bundled by Tauri)

**macOS**:
- Xcode Command Line Tools
- Apple Developer Certificate
- App-specific password for notarization

**Linux**:
- GTK3 development libraries
- WebKitGTK
- AppIndicator (for system tray)

---

## 4. Implementation Patterns

### 4.1 Tauri Configuration

```json
// tauri.conf.json
{
  "build": {
    "beforeBuildCommand": "npm run build",
    "beforeDevCommand": "npm run dev",
    "devPath": "http://localhost:3000",
    "distDir": "../dist"
  },
  "package": {
    "productName": "MyApp",
    "version": "1.0.0"
  },
  "tauri": {
    "bundle": {
      "active": true,
      "identifier": "com.company.myapp",
      "icon": [
        "icons/32x32.png",
        "icons/128x128.png",
        "icons/[email protected]",
        "icons/icon.icns",
        "icons/icon.ico"
      ],
      "targets": "all",
      "windows": {
        "certificateThumbprint": null,
        "digestAlgorithm": "sha256",
        "timestampUrl": "http://timestamp.digicert.com",
        "wix": {
          "language": "en-US"
        }
      },
      "macOS": {
        "entitlements": "./entitlements.plist",
        "exceptionDomain": "",
        "frameworks": [],
        "minimumSystemVersion": "10.15",
        "signingIdentity": null
      },
      "linux": {
        "deb": {
          "depends": ["libgtk-3-0", "libwebkit2gtk-4.0-37"]
        },
        "appimage": {
          "bundleMediaFramework": true
        }
      }
    },
    "security": {
      "csp": "default-src 'self'; script-src 'self'"
    }
  }
}
```

### 4.2 Platform-Specific Code

```rust
// src-tauri/src/main.rs

#[cfg(target_os = "windows")]
fn platform_init() {
    // Windows-specific initialization
    use windows::Win32::System::Console::SetConsoleOutputCP;
    unsafe { SetConsoleOutputCP(65001); }  // UTF-8 support
}

#[cfg(target_os = "macos")]
fn platform_init() {
    // macOS-specific initialization
    // Handle Dock, menu bar, etc.
}

#[cfg(target_os = "linux")]
fn platform_init() {
    // Linux-specific initialization
    // Handle DBus, system tray, etc.
}

fn main() {
    platform_init();

    tauri::Builder::default()
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

### 4.3 GitHub Actions Build Matrix

```yaml
name: Build

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: windows-latest
            args: ''
            target: x86_64-pc-windows-msvc
          - platform: macos-latest
            args: '--target x86_64-apple-darwin'
            target: x86_64-apple-darwin
          - platform: macos-latest
            args: '--target aarch64-apple-darwin'
            target: aarch64-apple-darwin
          - platform: ubuntu-22.04
            args: ''
            target: x86_64-unknown-linux-gnu

    runs-on: ${{ matrix.platform }}

    steps:
      - uses: actions/checkout@v4

      - name: Setup Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.target }}

      - name: Install Linux Dependencies
        if: matrix.platform == 'ubuntu-22.04'
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            libgtk-3-dev \
            libwebkit2gtk-4.0-dev \
            libappindicator3-dev \
            librsvg2-dev \
            patchelf

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install Dependencies
        run: npm ci

      - name: Build
        run: npm run tauri build -- ${{ matrix.args }}

      - name: Upload Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: ${{ matrix.target }}
          path: |
            src-tauri/target/${{ matrix.target }}/release/bundle/
```

### 4.4 Code Signing Configuration

**Windows (tauri.conf.json)**:
```json
{
  "tauri": {
    "bundle": {
      "windows": {
        "certificateThumbprint": "YOUR_CERT_THUMBPRINT",
        "digestAlgorithm": "sha256",
        "timestampUrl": "http://timestamp.digicert.com"
      }
    }
  }
}
```

**macOS (tauri.conf.json)**:
```json
{
  "tauri": {
    "bundle": {
      "macOS": {
        "signingIdentity": "Developer ID Application: Company Name (TEAM_ID)",
        "entitlements": "./entitlements.plist"
      }
    }
  }
}
```

**macOS Entitlements (entitlements.plist)**:
```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-library-validation</key>
    <true/>
</dict>
</plist>
```

---

## 5. Security Standards

### 5.1 Code Signing Requirements

| Platform | Certificate Type | Purpose |
|----------|-----------------|---------|
| Windows | EV Code Signing