Context

Current CI/CD pipeline is limited to single-platform Docker builds. We need a comprehensive multi-platform build matrix that:

• Builds both Generals Base and GeneralsXZH variants
• Targets Linux (current), macOS, and Windows (future)
• Runs replay validation to ensure determinism across platforms
• Captures build artifacts and logs for debugging

Goal

Implement a robust GitHub Actions workflow with:

1. Path-based filtering — conditional builds based on changed files (Generals/ vs GeneralsMD/ vs Core/)
2. Matrix strategy — build all platform/variant combinations efficiently
3. Conditional execution — exclude combinations not yet supported (e.g., Windows, Generals on macOS)
4. Artifact management — capture binaries and logs for debugging
5. Determinism validation — replay checks after successful builds
6. Smoke tests — basic validation (menu launch, skirmish load)

Architecture (RFC)

Check Changed Files (path-filter)
├─ Generals/ changed?
│  └─ Build Matrix [linux, macos/TBD, windows/TBD]
│     └─ Replay Check
│        └─ Smoke Tests
│
└─ GeneralsMD/ changed?
   └─ Build Matrix [linux, macos, windows/TBD]
      └─ Replay Check
         └─ Smoke Tests

Core/ changed?
├─ Affects all builds (runs full matrix)
└─ Propagate to both Generals and GeneralsMD paths

Acceptance Criteria

• GitHub Actions workflow created at .github/workflows/build.yml
• Path-filter used to detect changed files (dorny/paths-filter)
• Build matrix for platform x game variant combinations
• Proper conditional exclusions documented (use exclude array with task references)
• Linux builds working (docker-based, both Generals + ZH)
• macOS builds included (native, ZH only for now; Generals gated with commented-out step)
• Windows builds included as TBD (continue-on-error with issue reference)
• Replay check runs after successful builds
• Smoke tests defined (menu launch, skirmish load)
• Build artifacts uploaded (binaries + logs)
• Cache strategy configured (ccache or sccache)
• Build logs always captured (on failure and success)
• Documentation updated (.github/workflows/README.md)

Mocks/TBD Items

Currently, use GitHub Actions features to properly indicate incomplete features:

For unsupported combinations:

exclude:
  - platform: windows        # See: https://github.com/fbraz3/GeneralsX/issues/29
  - platform: macos
    game: Generals           # See: https://github.com/fbraz3/GeneralsX/issues/28

For incomplete steps:

- name: Smoke Tests (TBD)
  if: success()  # Only run if build succeeded
  continue-on-error: true
  run: |
    # TODO: Implement comprehensive smoke tests
    # See: https://github.com/fbraz3/GeneralsX/issues/XXX
    echo "Smoke tests framework TBD"

CI Responsibilities (Scope)

Per-Build Steps

1. Checkout code
2. Run docker-configure if Linux
3. Run docker-build or native build per platform
4. Upload binary artifact
5. On Linux: run replay check

Per-Platform Smoke Tests (TBD)

• Menu launch (verify window appears)
• Skirmish map load (verify no immediate crash)
• Asset loading validation
• Determinism validation (replays from main should still work)

Logging & Artifacts

• Capture CMake configure logs
• Capture build output logs
• Capture replay check results
• Upload logs on failure (mandatory)
• Upload logs on success (optional, last N builds)

References

• Current build scripts: scripts/build/linux/, scripts/build/macos/
• Related issues:
  • Port Generals Base (non-expansion) to macOS #28: Port Generals Base to macOS
  • Create Windows x64 build (SDL3 + DXVK + OpenAL + FFMPEG) #29: Create Windows x64 build
  • Integrate Generals Base into CI/CD pipeline #30: Integrate Generals Base into CI/CD pipeline
• Workflow patterns: GitHub Actions docs + existing open-source Generals projects

Implementation Strategy

Phase 1 (Skeleton):

• Create workflow file with matrix and path-filter
• Linux builds wired (using existing docker scripts)
• Replay checks integrated
• Artifact upload working

Phase 2 (Enhancement):

• macOS builds integrated (after Port Generals Base (non-expansion) to macOS #28 complete)
• Windows build framework (after Create Windows x64 build (SDL3 + DXVK + OpenAL + FFMPEG) #29 complete)
• Smoke tests framework implemented
• Cache optimization (ccache)

Phase 3 (Polish):

• CI performance optimization
• Report generation (build times, artifact sizes)
• Slack/Discord notifications (optional)