2026 Remote Mac CI Matrix: vcpkg + CMake FetchContent

Treat environment variables as part of your pipeline contract. The snippets below assume a bootstrapped vcpkg checkout at VCPKG_ROOT, manifest mode enabled by the presence of vcpkg.json, and CMake 3.24 or newer for modern FetchContent controls.

vcpkg cache layout: separate source downloads from binary artifacts. Downloads land under VCPKG_DOWNLOADS; binary caches are expressed through VCPKG_BINARY_SOURCES using semicolon-separated segments (clear resets inherited values in the same process).

export VCPKG_ROOT="${HOME}/vcpkg"
export VCPKG_DOWNLOADS="${CI_PROJECT_DIR}/.cache/vcpkg-downloads"
export VCPKG_FEATURE_FLAGS="binarycaching,manifests"
export VCPKG_MAX_CONCURRENCY="6"
# Local read/write binary cache (per-runner or shared NAS)
export VCPKG_DEFAULT_BINARY_CACHE="${CI_PROJECT_DIR}/.cache/vcpkg-bin"
export VCPKG_BINARY_SOURCES="clear;files,${VCPKG_DEFAULT_BINARY_CACHE},readwrite"

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE="${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake" \
  -DVCPKG_INSTALL_OPTIONS="--clean-after-build" \
  -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 4

Asset mirrors (optional): when policy blocks direct access to third-party archives consumed by portfiles, set X_VCPKG_ASSET_SOURCES to your mirror or caching proxy using the syntax documented for your vcpkg revision—keep the string next to VCPKG_BINARY_SOURCES in runbooks because both affect outbound URLs.

Registries and overlays: if you adopt vcpkg-configuration.json with private registries, pin registry baselines the same way you pin the builtin registry. CI should print both the tool commit and the resolved registry metadata so support teams can diff a failing job against a known-good laptop without re-running the entire configure graph.

CMake presets: store toolchain and cache variables in CMakePresets.json so local engineers and remote runners share one entry point. Passing -DVCPKG_INSTALL_OPTIONS=--debug during one-off investigations is fine, but strip verbose flags from default CI presets to keep logs readable when multiple jobs interleave on the same host.

FetchContent defaults in CMake: pin every external with a full commit SHA, turn on shallow clones where history is irrelevant, and stop redundant updates after the first successful population.

set(FETCHCONTENT_BASE_DIR "${CMAKE_BINARY_DIR}/_deps" CACHE PATH "")
set(FETCHCONTENT_QUIET OFF)
set(FETCHCONTENT_UPDATES_DISCONNECTED ON)
include(FetchContent)
FetchContent_Declare(
  coollib
  GIT_REPOSITORY https://example.com/coollib.git
  GIT_TAG 7b3f2c9d4e1a8f0c6d5b4a3210fedcba98765432
  GIT_SHALLOW TRUE
)
set(FETCHCONTENT_UPDATES_DISCONNECTED_COOLLIB ON)
FetchContent_MakeAvailable(coollib)

Resilience wrapper: wrap the configure line in a bounded shell retry (2s / 4s / 8s sleeps) when transient TLS resets appear on long-haul routes; log attempt numbers without printing secrets.

On remote Mac pools, start with deterministic baselines plus a warm VCPKG_DOWNLOADS directory, then add binary caching once you can prove triplet stability (AppleClang version, deployment target, and vcpkg commit hash). Treat each triplet as a separate product: arm64-osx binaries built on macOS 15 are not interchangeable with older SDK assumptions even when the CPU matches.

When several services consume the same C++ static libraries, align strip flags and visibility settings before trusting binary cache hits—otherwise you may deserialize ABI-compatible yet link-incompatible objects. For another hermetic-build perspective on external graphs, compare notes with the Bazel external-deps cache matrix.

1. Pin the vcpkg tool commit in CI (bootstrap script or submodule) and print git -C "$VCPKG_ROOT" rev-parse HEAD into logs.
2. Commit vcpkg.json with a builtin-baseline that resolves against that tool commit; fail PRs that change baseline without release notes.
3. Route downloads to NVMe with VCPKG_DOWNLOADS; key CI restores using sha256sum vcpkg.json plus the vcpkg commit.
4. Set VCPKG_MAX_CONCURRENCY per runner tier; pair with cmake --build --parallel caps so link jobs do not contend with concurrent vcpkg builds on the same host.
5. Configure VCPKG_BINARY_SOURCES: read-only for PRs from forks, read/write only on protected branches or scheduled warmers.
6. Replace branch pins in FetchContent with SHAs; enable FETCHCONTENT_UPDATES_DISCONNECTED_* after the first green populate.
7. Add a CI gate that fails when FETCHCONTENT_FULLY_DISCONNECTED ON is requested but _deps content is missing—this emulates offline reproducibility.
8. Document triplet choice (VCPKG_DEFAULT_TRIPLET or -DVCPKG_TARGET_TRIPLET) next to macOS deployment targets for Apple Silicon farms.

How is this different from package managers we already documented? vcpkg owns curated C++ ports and ABI hashing for binaries; CMake FetchContent orchestrates arbitrary upstream repos. This article stays on that pair so you are not re-reading npm or CocoaPods playbooks—use the dependency acceleration hub when you need a wider stack map.

Should FetchContent and vcpkg both vend the same library? Pick one source of truth. Double definitions explode at configure time or, worse, link time. Prefer vcpkg for broad ecosystems and reserve FetchContent for libraries not yet ported—or wrap vcpkg-only consumers with find_package after FetchContent_MakeAvailable exports consistent targets.

What concurrency should I try first on a shared M4 Mac mini? Start VCPKG_MAX_CONCURRENCY=6 with two concurrent CI jobs maximum, watch diskutil apfs listVolumeGroups pressure and compile link phases, then adjust. Cross-border networks rarely saturate CPU; local contention does.

Can I skip binary caching entirely? Yes, if builds are infrequent and manifests are small—focus on baseline discipline and download directory reuse first, then measure whether compile hours justify cache governance.