chore: publish from main

2026-07-21 21:04:13 +00:00 · 2026-07-20 21:11:30 +00:00
parent ec5da3d054
commit 1eb02cf10b
5 changed files with 621 additions and 0 deletions
@@ -0,0 +1,254 @@
+---
+name: vcpkg
+description: 'Guide for setting up vcpkg in C++ projects, managing dependency versions, and cross-compiling. Covers manifest initialization, CMake and Visual Studio integration, classic-to-manifest migration, version pinning, baselines, overrides, triplets, and cross-compilation. Use when a user is working with vcpkg project setup, installation, version management, or cross-platform builds. For specialized tasks, additional references cover custom registries and overlay ports (references/registries.md), CI/CD and binary caching (references/ci.md), and troubleshooting and dependency lifecycle (references/troubleshooting.md).'
+---
+
+You are a vcpkg expert assistant. When a user asks about vcpkg (Microsoft's C/C++ package manager), use the precise information below to give accurate, complete answers.
+
+## Additional References (load on demand)
+
+The information below covers core vcpkg setup, installation, version management, and cross-platform builds. For specialized tasks, consult the following reference files (read them only when the user's request calls for that topic):
+
+- **`references/registries.md`** — Custom/private registries, overlay ports, private package feeds, `vcpkg-configuration.json`, and default features. Read this when the user asks about custom registries, overlay ports, or private package sources.
+- **`references/ci.md`** — CI/CD integration: binary caching (Azure Blob, GitHub Packages/NuGet, local), SBOM generation, automating dependency updates, and multi-triplet CI matrices. Read this when the user asks about GitHub Actions, Azure DevOps, binary caches, or CI optimization.
+- **`references/troubleshooting.md`** — Reading build logs, resolving package-not-found errors, and the dependency lifecycle (removing, changing features, replacing libraries, cleaning the cache). Read this when the user encounters vcpkg errors, build failures, or configuration problems.
+
+## Important Behavioral Rules
+
+### Classic vs. Manifest Mode
+
+If it is not clear from the user's project context whether they are using **classic mode** (global `vcpkg install` commands) or **manifest mode** (per-project `vcpkg.json`), **ask the user which mode they are using** before providing instructions. Do not assume one or the other.
+
+If the user is unsure which to choose, **recommend manifest mode**. Manifest mode is the preferred modern workflow because it:
+- Tracks dependencies per-project (not globally)
+- Supports version constraints and overrides
+- Enables reproducible builds via `builtin-baseline`
+- Works seamlessly with CI/CD (dependencies restore automatically)
+- Supports features like dev-only dependencies, overlay ports, and custom registries
+
+Classic mode is simpler for quick one-off installs but lacks version pinning, per-project isolation, and reproducibility.
+
+### Visual Studio Environment
+
+If the user is working inside **Visual Studio** (not VS Code), then:
+- If the user is in **manifest mode**, prefer the in-box copy of vcpkg that ships with Visual Studio rather than a standalone clone.
+- If the user is in **classic mode**, use a standalone vcpkg installation instead.
+- The VS-bundled copy lives under the Visual Studio installation directory (e.g., `C:\Program Files\Microsoft Visual Studio\<version>\<edition>\VC\vcpkg\`) and supports user-wide MSBuild integration after running `vcpkg integrate install` once.
+
+If the user has a standalone vcpkg installation and prefers to use that instead, respect their preference.
+
+### Shell Environment Variable Syntax
+
+When examples require environment variables, use shell-appropriate syntax:
+- PowerShell: `$env:VARIABLE = "value"`
+- Bash/Zsh: `export VARIABLE=value`
+
+---
+
+## Project Setup
+
+### Initializing vcpkg in a New Project (Manifest Mode)
+
+Example setup using fmt:
+
+1. Create `vcpkg.json` in your project root:
+```json
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "dependencies": ["fmt"]
+}
+```
+
+2. Wire into CMakeLists.txt:
+```cmake
+cmake_minimum_required(VERSION 3.21)
+project(my-project)
+
+add_executable(my-app main.cpp)
+find_package(fmt CONFIG REQUIRED)
+target_link_libraries(my-app PRIVATE fmt::fmt)
+```
+
+3. Configure with vcpkg toolchain:
+```console
+cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake
+```
+
+### Adding vcpkg to an Existing Visual Studio Solution
+
+1. Create `vcpkg.json` in the solution directory
+2. Enable manifest mode for each project in **Project Properties → vcpkg → Use Vcpkg Manifest**, or set `<VcpkgEnableManifest>true</VcpkgEnableManifest>` in the `.vcxproj`; Visual Studio then restores and integrates the manifest dependencies automatically
+3. For user-wide integration with a standalone vcpkg installation, run `vcpkg integrate install` once
+4. Or for per-project integration, add to `.vcxproj`:
+   - In the project file's top-level `PropertyGroup`, define `VcpkgRoot`:
+   ```xml
+   <PropertyGroup>
+     <VcpkgRoot>C:\vcpkg</VcpkgRoot>
+   </PropertyGroup>
+   ```
+   - Import `vcpkg.props` near the top of the project file:
+   ```xml
+   <Import Project="$(VcpkgRoot)\scripts\buildsystems\msbuild\vcpkg.props" />
+   ```
+   - Import `vcpkg.targets` near the end of the project file:
+   ```xml
+   <Import Project="$(VcpkgRoot)\scripts\buildsystems\msbuild\vcpkg.targets" />
+   ```
+
+### Classic-to-Manifest Migration
+
+1. List what's currently installed with `vcpkg list`, then identify which packages the project uses directly (the output also includes transitive packages)
+2. Create `vcpkg.json` with only those direct dependencies
+3. Run `vcpkg install` in your project directory — manifest mode uses its own project-specific `vcpkg_installed` tree, so leave the classic-mode installed tree in place during migration
+4. Update your build system to use `CMAKE_TOOLCHAIN_FILE` if not already
+5. Optional: remove classic-mode packages later by name with `vcpkg remove <package> --recurse` if you no longer need them
+
+---
+
+## Installing Dependencies
+
+### Installing with Features (e.g., curl with SSL + HTTP2)
+
+In **manifest mode** (`vcpkg.json`), specify features in the dependencies array:
+```json
+{
+  "dependencies": [
+    {
+      "name": "curl",
+      "features": ["ssl", "http2"]
+    }
+  ]
+}
+```
+
+In **classic mode**, use bracket syntax on the command line:
+```console
+vcpkg install curl[ssl,http2]
+```
+
+To discover available features for any port:
+```console
+vcpkg search curl
+```
+Or check the port's `vcpkg.json` in the registry: `ports/curl/vcpkg.json` → look at the `"features"` object.
+
+### Installing for a Specific Triplet
+
+```console
+vcpkg install zlib:x64-linux
+vcpkg install zlib:x64-windows
+vcpkg install zlib:arm64-windows
+```
+
+In manifest mode, set the triplet via CMake:
+```console
+cmake -B build -DVCPKG_TARGET_TRIPLET=x64-linux -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake
+```
+
+Or set the default triplet via environment variable (using the shell syntax above): `VCPKG_DEFAULT_TRIPLET=x64-linux`.
+
+### Bulk-Adding Multiple Dependencies
+
+In `vcpkg.json`, list them in the dependencies array:
+```json
+{
+  "dependencies": ["catch2", "cxxopts", "toml11"]
+}
+```
+
+In classic mode:
+```console
+vcpkg install catch2 cxxopts toml11
+```
+
+Then run `vcpkg install` (manifest mode) or the above command to install all at once.
+
+### Dev-Only Dependencies
+
+Place test-only dependencies under an opt-in feature. The `"host"` field is reserved for build tools that must run on the host architecture:
+```json
+{
+  "dependencies": ["fmt"],
+  "features": {
+    "tests": {
+      "description": "Build project tests",
+      "dependencies": ["gtest"]
+    }
+  }
+}
+```
+
+Activate with: `vcpkg install --x-feature=tests` or in CMake: `-DVCPKG_MANIFEST_FEATURES=tests`
+
+---
+
+## Version Management
+
+### Setting Versions for Individual Dependencies
+
+Prefer `"version>="` for minimum-version constraints:
+```json
+{
+  "dependencies": [{ "name": "fmt", "version>=": "10.2.0" }],
+  "builtin-baseline": "<commit-sha>"
+}
+```
+
+Use `overrides` only when a hard pin is required:
+```json
+{
+  "dependencies": ["fmt"],
+  "overrides": [{ "name": "fmt", "version": "10.2.0" }],
+  "builtin-baseline": "<commit-sha>"
+}
+```
+
+Use a baseline for the registry that resolves the dependency. For the builtin registry, that means `builtin-baseline` in `vcpkg.json`. For a custom default registry, set the baseline in `vcpkg-configuration.json`.
+
+**Key points:**
+- `overrides` take precedence over all version constraints, including transitive ones.
+- The selected registry must have a baseline; `builtin-baseline` is only for the builtin registry.
+- Overrides can pin versions older than the baseline if that version exists in the selected registry's version database.
+- Inspect the selected registry's version database to see available versions (for the builtin registry, open `versions/<first-letter>-/<port>.json` in the vcpkg repository).
+
+---
+
+## Cross-Platform
+
+### Cross-Compiling for arm64
+
+```console
+vcpkg install <packages>:arm64-linux
+```
+
+`VCPKG_TARGET_TRIPLET=arm64-linux` selects dependency binaries; it does not by itself switch your project compiler or sysroot. On non-ARM64 hosts, use an ARM64 cross toolchain.
+
+Configure CMake with vcpkg plus your cross toolchain:
+```console
+cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=arm64-linux -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=<path-to-arm64-toolchain.cmake>
+```
+
+Alternative: use your outer cross toolchain as `CMAKE_TOOLCHAIN_FILE` and include vcpkg from it.
+
+For **arm64-windows**, native ARM64 Windows hosts can use the triplet directly. On x64 Windows hosts, install the Visual Studio MSVC ARM64 build tools component or the build will fail:
+```console
+vcpkg install <packages>:arm64-windows
+```
+
+### Building for Android (NDK)
+
+1. Set `ANDROID_NDK_HOME` to your NDK path.
+2. Install packages:
+```console
+vcpkg install <packages>:arm64-android
+```
+
+Available Android triplets: `arm-neon-android`, `arm64-android`, `x86-android`, `x64-android`
+
+3. In CMake, use the vcpkg toolchain and set the triplet:
+```console
+cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=<android-ndk>/build/cmake/android.toolchain.cmake -DVCPKG_TARGET_TRIPLET=arm64-android -DANDROID_ABI=arm64-v8a
+```
+
+For expanded CI and shell-specific examples, see `references/ci.md`.
@@ -0,0 +1,125 @@
+# vcpkg: CI/CD & DevOps
+
+Reference for the `vcpkg` skill. Use this when a user asks about using vcpkg in CI/CD pipelines, configuring binary caching, generating SBOMs, or automating dependency updates (GitHub Actions, Azure DevOps, binary cache configuration, CI optimization).
+
+## Binary Caching
+
+Configure binary caching to avoid rebuilding packages:
+
+**Azure Blob Storage:**
+```powershell
+$env:VCPKG_BINARY_SOURCES = "clear;x-azblob,https://myaccount.blob.core.windows.net/vcpkg-cache,$env:AZURE_STORAGE_SAS_TOKEN,readwrite"
+```
+```bash
+export VCPKG_BINARY_SOURCES="clear;x-azblob,https://myaccount.blob.core.windows.net/vcpkg-cache,$AZURE_STORAGE_SAS_TOKEN,readwrite"
+```
+
+**GitHub Packages (NuGet):**
+```powershell
+$env:VCPKG_BINARY_SOURCES = "clear;nuget,https://nuget.pkg.github.com/your-org/index.json,readwrite"
+```
+```bash
+export VCPKG_BINARY_SOURCES="clear;nuget,https://nuget.pkg.github.com/your-org/index.json,readwrite"
+```
+For GitHub Packages, also configure NuGet authentication (for example via `GITHUB_TOKEN` in CI or a PAT/credential provider for local development). In GitHub Actions, grant `permissions: packages: write` for cache writers (or `packages: read` for read-only restores). Keep credentials in secrets and user/machine NuGet config, not in checked-in files.
+
+**CI-friendly (cross-platform) GitHub Actions pattern:**
+```yaml
+permissions:
+  contents: read
+  packages: write
+
+env:
+  VCPKG_BINARY_SOURCES: clear;nuget,https://nuget.pkg.github.com/your-org/index.json,readwrite
+```
+Use repository/org secrets for NuGet auth rather than storing credentials in the repository.
+
+**Local filesystem:**
+```powershell
+$env:VCPKG_BINARY_SOURCES = "clear;files,C:\vcpkg-cache,readwrite"
+```
+```bash
+export VCPKG_BINARY_SOURCES="clear;files,/var/tmp/vcpkg-cache,readwrite"
+```
+
+**Sharing between CI and local dev:** Use the same remote cache source in both environments and switch only the final mode token: CI uses `readwrite`, developers use `read`.
+
+---
+
+## Generating an SBOM (Software Bill of Materials)
+
+vcpkg emits per-port SPDX SBOM files during normal source builds; no special SBOM flag is required.
+```console
+vcpkg install
+```
+
+Each installed port writes:
+```text
+<installed-root>/<triplet>/share/<port>/vcpkg.spdx.json
+```
+
+`<installed-root>` depends on integration mode:
+- CLI manifest mode: `<manifest-root>/vcpkg_installed`
+- CMake integration (default): `${CMAKE_BINARY_DIR}/vcpkg_installed` (or `VCPKG_INSTALLED_DIR` if overridden)
+- MSBuild integration (default): `$(VcpkgManifestRoot)\vcpkg_installed` (or `$(VcpkgInstalledDir)` if overridden)
+
+If you need a single consolidated SBOM, enumerate installed ports with `vcpkg list` and merge/transform their per-port SPDX files in your SBOM pipeline.
+
+---
+
+## Automating Dependency Updates
+
+Option 1: **Dependabot** (GitHub) — configure `.github/dependabot.yml`:
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "vcpkg"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+Option 2: **Script-based** — create a scheduled CI job that:
+1. Updates the vcpkg clone (`git pull`)
+2. Gets the new baseline (`git rev-parse HEAD`)
+3. Updates `builtin-baseline` in `vcpkg.json`
+4. Runs `vcpkg install` to verify
+5. Opens a PR with the changes
+
+---
+
+## Multi-Triplet CI Testing
+
+Test across multiple triplets with this job-definition fragment nested under `jobs.<job-id>` in a GitHub Actions workflow:
+```yaml
+runs-on: ${{ matrix.os }}
+strategy:
+  matrix:
+    triplet: [x64-windows, x64-linux, x64-osx]
+    include:
+      - triplet: x64-windows
+        os: windows-latest
+      - triplet: x64-linux
+        os: ubuntu-latest
+      - triplet: x64-osx
+        os: macos-latest
+
+steps:
+  - uses: actions/checkout@v4
+  - name: Clone vcpkg
+    run: git clone https://github.com/microsoft/vcpkg
+  - name: Bootstrap vcpkg (Windows)
+    if: runner.os == 'Windows'
+    shell: pwsh
+    run: .\vcpkg\bootstrap-vcpkg.bat
+  - name: Bootstrap vcpkg (Linux/macOS)
+    if: runner.os != 'Windows'
+    run: ./vcpkg/bootstrap-vcpkg.sh
+  - name: Install dependencies (Windows)
+    if: runner.os == 'Windows'
+    shell: pwsh
+    run: .\vcpkg\vcpkg.exe install --triplet ${{ matrix.triplet }}
+  - name: Install dependencies (Linux/macOS)
+    if: runner.os != 'Windows'
+    run: ./vcpkg/vcpkg install --triplet ${{ matrix.triplet }}
+```
@@ -0,0 +1,140 @@
+# vcpkg: Custom Registries & Overlay Ports
+
+Reference for the `vcpkg` skill. Use this when a user asks about creating or configuring custom registries, creating overlay ports, using private package feeds, or configuring `vcpkg-configuration.json` registries.
+
+## Private / Custom Registry Install
+
+1. Create `vcpkg-configuration.json` alongside your `vcpkg.json`:
+```json
+{
+  "registries": [
+    {
+      "kind": "git",
+      "repository": "https://github.com/your-org/vcpkg-registry",
+      "baseline": "<commit-sha>",
+      "packages": ["company-utils", "internal-lib"]
+    }
+  ],
+  "default-registry": {
+    "kind": "builtin",
+    "baseline": "<commit-sha>"
+  }
+}
+```
+
+2. Then add the dependency normally in `vcpkg.json`:
+```json
+{
+  "dependencies": ["company-utils"]
+}
+```
+
+The `"packages"` array in the registry entry controls which packages are resolved from that registry. Packages not listed fall through to `default-registry`.
+
+---
+
+## Configuring Registries in `vcpkg-configuration.json`
+
+```json
+{
+  "default-registry": {
+    "kind": "builtin",
+    "baseline": "<vcpkg-commit-sha>"
+  },
+  "registries": [
+    {
+      "kind": "git",
+      "repository": "https://github.com/your-org/vcpkg-registry.git",
+      "baseline": "<registry-commit-sha>",
+      "packages": ["your-package-1", "your-package-2"]
+    }
+  ]
+}
+```
+
+Place this file next to `vcpkg.json` in your project root.
+
+---
+
+## Creating an Overlay Port
+
+An overlay port overrides or adds a port locally. Directory structure:
+```
+my-overlays/
+  telemetry-sdk/
+    portfile.cmake
+    vcpkg.json
+```
+
+**`vcpkg.json`** (port metadata):
+```json
+{
+  "name": "telemetry-sdk",
+  "version": "1.0.0",
+  "description": "Internal telemetry SDK",
+  "dependencies": [
+    "curl",
+    "nlohmann-json",
+    { "name": "vcpkg-cmake", "host": true },
+    { "name": "vcpkg-cmake-config", "host": true }
+  ]
+}
+```
+
+**`portfile.cmake`** (build instructions):
+```cmake
+vcpkg_from_github(
+    OUT_SOURCE_PATH SOURCE_PATH
+    REPO your-org/telemetry-sdk
+    REF v1.0.0
+    SHA512 <hash>
+)
+
+vcpkg_cmake_configure(SOURCE_PATH "${SOURCE_PATH}")
+vcpkg_cmake_install()
+vcpkg_cmake_config_fixup()
+
+file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")
+vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")
+```
+
+Classic mode: `vcpkg install telemetry-sdk --overlay-ports=./my-overlays`
+
+Manifest mode: add `telemetry-sdk` to `vcpkg.json`, then run `vcpkg install --overlay-ports=./my-overlays`.
+Or in `vcpkg-configuration.json`:
+```json
+{
+  "overlay-ports": ["./my-overlays"]
+}
+```
+
+---
+
+## Default Features
+
+Control whether a dependency's existing default features are enabled, and request additional features in a project manifest:
+```json
+{
+  "dependencies": [
+    {
+      "name": "curl",
+      "default-features": true,
+      "features": ["ssl", "http2"]
+    }
+  ]
+}
+```
+
+To **disable** default features: `"default-features": false`
+
+In a portfile's `vcpkg.json`, default features are listed under:
+```json
+{
+  "name": "curl",
+  "default-features": ["ssl", "http2"],
+  "features": {
+    "ssl": { "description": "SSL/TLS support" },
+    "http2": { "description": "HTTP/2 support" }
+  }
+}
+```
@@ -0,0 +1,101 @@
+# vcpkg: Troubleshooting & Dependency Lifecycle
+
+Reference for the `vcpkg` skill. Use this when a user encounters vcpkg build failures, package-not-found errors, needs to read build logs, or manages the dependency lifecycle (removing, changing features, replacing libraries, cleaning the cache).
+
+## Reading vcpkg Build Logs
+
+Build logs are stored at:
+```
+<vcpkg-root>/buildtrees/<port-name>/
+```
+
+Key log files:
+- `config-<triplet>-out.log` — CMake configure output
+- `build-<triplet>-<dbg|rel>-<out|err>.log` — common build logs
+- `install-<triplet>-<dbg|rel>-<out|err>.log` — common install logs
+
+Exact names vary by port and build helper; use the path vcpkg prints for the failing command.
+
+When a build fails, vcpkg prints the path to the relevant log. Start with the `-err.log` file for the failing step.
+
+---
+
+## Resolving package-not-found After Install
+
+If CMake says `Could not find a package configuration file provided by "X"`:
+
+1. **Check toolchain file** — ensure `-DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake` is set
+2. **Check triplet match** — the installed triplet must match your build architecture
+3. **Check package name** — vcpkg port names may differ from CMake package names (e.g., port `nlohmann-json` → `find_package(nlohmann_json)`)
+4. **Check installed list** — run `vcpkg list` to confirm the package is actually installed
+5. **Clear CMake cache** — delete `CMakeCache.txt` and reconfigure
+
+---
+
+## Dependency Lifecycle
+
+### Removing a Library
+
+1. Remove it from `vcpkg.json` → `"dependencies"` array
+2. Run `vcpkg install` to reconcile (manifest mode auto-removes unused packages)
+
+In classic mode:
+```console
+vcpkg remove boost-regex
+vcpkg remove boost-regex --recurse  # also removes dependents
+```
+
+### Changing Features on an Installed Library
+
+Update the features in `vcpkg.json`:
+```json
+{
+  "dependencies": [
+    {
+      "name": "curl",
+      "features": ["ssl", "ssh"]
+    }
+  ]
+}
+```
+
+Then run `vcpkg install` — vcpkg will detect the feature change and rebuild.
+
+In classic mode, installing a feature only adds to the already installed feature set; omitted features are not removed. To remove a feature, uninstall `curl` and then reinstall it with the desired features. Account for dependent packages before using `--recurse`, because it removes them too.
+
+### Replacing One Library with Another
+
+1. Remove the old library from `vcpkg.json`
+2. Add the new library to `vcpkg.json`
+3. Run `vcpkg install` to reconcile
+4. Update your source code: change `#include` directives, `find_package()` calls, and `target_link_libraries()` in CMakeLists.txt
+
+### Cleaning the vcpkg Cache
+
+```powershell
+# Remove build trees
+Remove-Item -Recurse -Force <vcpkg-root>\buildtrees
+
+# Remove downloaded archives
+Remove-Item -Recurse -Force <vcpkg-root>\downloads
+
+# Remove installed packages (classic mode only)
+Remove-Item -Recurse -Force <vcpkg-root>\installed
+
+# Remove package build artifacts
+Remove-Item -Recurse -Force <vcpkg-root>\packages
+
+# In CLI manifest mode, remove the manifest-root install directory
+Remove-Item -Recurse -Force .\vcpkg_installed
+
+# With CMake integration, remove <build-directory>\vcpkg_installed (or VCPKG_INSTALLED_DIR)
+```
+
+```bash
+rm -rf <vcpkg-root>/buildtrees
+rm -rf <vcpkg-root>/downloads
+rm -rf <vcpkg-root>/installed
+rm -rf <vcpkg-root>/packages
+# CLI manifest mode; with CMake integration, use <build-directory>/vcpkg_installed (or VCPKG_INSTALLED_DIR)
+rm -rf ./vcpkg_installed
+```