docs: build system refactor design — dual-mode vcpkg + prebuild

[Copilot]

The build system has two divergent dependency paths (vcpkg and legacy 3RD_PATH/python/third_party.py) that can silently drift, incomplete triplet auto-detection, no prebuild download path, and a x64-windows vs x64-windows-static mismatch across CI and CMake. This document proposes a unified refactor to address all six requirements without requiring immediate implementation.

Document: docs/build-system-refactor.md

Dual-Mode Architecture

• Local build (SKY_PREBUILD_MODE=OFF, default): vcpkg installs from source; all existing 3rdParty:: alias targets unchanged.
• Prebuild mode (SKY_PREBUILD_MODE=ON): downloads a per-triplet archive from CI-published GitHub Releases, unpacks to ${CMAKE_BINARY_DIR}/_prebuilts/<triplet>/, sets CMAKE_PREFIX_PATH — then the same sky_packages.cmake resolves packages identically in both modes.

vcpkg Discovery Order

Checks VCPKG_ROOT → well-known system paths (%LOCALAPPDATA%\vcpkg, ~/.vcpkg, /opt/vcpkg) → local clone bootstrap. Network clone only as last resort.

Triplet Auto-Selection (sky_triplet.cmake)

Replaces the ad-hoc if(WIN32)/elseif(UNIX) block with a full dispatch on CMAKE_SYSTEM_NAME + CMAKE_SYSTEM_PROCESSOR, covering all six triplets. Unifies Windows to x64-windows-static everywhere. Flags required fixes to arm64-android.cmake (missing VCPKG_CHAINLOAD_TOOLCHAIN_FILE) and x64-linux.cmake.

Package × Triplet Compatibility Matrix

All 26 packages mapped against all 6 triplets (x64-windows-static, x64-linux, x64-osx, arm64-osx, arm64-ios, arm64-android) with ✅ / ⚠️ / ❌ status and notes for SDL2/iOS/Android exclusions.

Prebuild CI/CD Design

• Artifact naming: skyengine-prebuilts-<triplet>-<baseline_short>.tar.zst
• cmake/prebuild_manifest.json: maps triplet → URL + SHA256, committed to repo, updated by automation after each publish run.
• sky_prebuild.cmake: SHA256-stamped download + unpack via file(DOWNLOAD) + file(ARCHIVE_EXTRACT).

File Responsibility Map

Defines five new single-responsibility cmake files and retires cmake/thirdparty.cmake, cmake/vcpkg.cmake, cmake/vcpkg_bootstrap.cmake, python/third_party.py, and the legacy Find*.cmake modules.

Migration Checklist

Three phases: (1) vcpkg stabilization — triplet fixes, CI unification; (2) prebuild infrastructure — manifest schema, download logic, publish workflow; (3) cleanup — retire legacy files, update docs.

Original prompt

analysis the build system design, lets generate a refactor document(impl not required),

1. support both local build and prebuild mode
2. local build use vcpkg to manage the version, platform, etc.
3. prebuild libraries are built and published through cicd, and downloaded when build the engine.
4. the built system should be simple but full functional, easy to maintain.
5. use the global vcpkg with our cuastom regiatry, install a local vcpkg when global vcpkg not found.
6. review the triplet config, and the packages must be able to build for all triplets. add rules to select the proper triplet based on the platform.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.