From e3fa3211f6e993f016eb327794c36b95a2ba7901 Mon Sep 17 00:00:00 2001 From: Augustin Popa Date: Wed, 15 Jul 2026 09:16:23 -0700 Subject: [PATCH 1/6] Added vcpkg skill --- skills/vcpkg/SKILL.md | 283 +++++++++++++++++++++ skills/vcpkg/references/ci.md | 96 +++++++ skills/vcpkg/references/registries.md | 133 ++++++++++ skills/vcpkg/references/troubleshooting.md | 94 +++++++ 4 files changed, 606 insertions(+) create mode 100644 skills/vcpkg/SKILL.md create mode 100644 skills/vcpkg/references/ci.md create mode 100644 skills/vcpkg/references/registries.md create mode 100644 skills/vcpkg/references/troubleshooting.md diff --git a/skills/vcpkg/SKILL.md b/skills/vcpkg/SKILL.md new file mode 100644 index 000000000..8fe2eaa46 --- /dev/null +++ b/skills/vcpkg/SKILL.md @@ -0,0 +1,283 @@ +--- +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), prefer using the **in-box copy of vcpkg that ships with Visual Studio** rather than a standalone vcpkg clone, unless the user indicates they want to use a different installation. The VS-bundled vcpkg: +- Is located under the Visual Studio installation directory (e.g., `C:\Program Files\Microsoft Visual Studio\\\VC\vcpkg\`) +- Is automatically integrated with MSBuild — no need to run `vcpkg integrate install` +- Stays up-to-date with Visual Studio updates +- Works out of the box with CMake projects opened via "Open Folder" or CMake presets + +If the user has a standalone vcpkg installation and prefers to use that instead, respect their preference. + +--- + +## Project Setup + +### Initializing vcpkg in a New Project (Manifest Mode) + +1. Create `vcpkg.json` in your project root: +```json +{ + "name": "my-project", + "version": "1.0.0", + "dependencies": [] +} +``` + +2. Wire into CMakeLists.txt: +```cmake +cmake_minimum_required(VERSION 3.21) +project(my-project) + +find_package(fmt CONFIG REQUIRED) +target_link_libraries(my-app PRIVATE fmt::fmt) +``` + +3. Configure with vcpkg toolchain: +``` +cmake -B build -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake +``` + +### Adding vcpkg to an Existing Visual Studio Solution + +1. Run `vcpkg integrate install` (one-time, system-wide) +2. Create `vcpkg.json` in the solution directory +3. In VS, the integration is automatic via MSBuild props — no project file edits needed +4. Or per-project: add to `.vcxproj`: +```xml + + +``` + +### Classic-to-Manifest Migration + +1. List what's currently installed: `vcpkg list` +2. Create `vcpkg.json` with those dependencies +3. Delete global installs: `vcpkg remove --outdated --recurse` +4. Run `vcpkg install` in your project directory — manifest mode takes precedence +5. Update your build system to use `CMAKE_TOOLCHAIN_FILE` if not already + +--- + +## 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: +``` +vcpkg install curl[ssl,http2] +``` + +To discover available features for any port: +``` +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 + +``` +vcpkg install zlib:x64-linux +vcpkg install zlib:x64-windows +vcpkg install zlib:arm64-windows +``` + +In manifest mode, set the triplet via CMake: +``` +cmake -B build -DVCPKG_TARGET_TRIPLET=x64-linux -DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake +``` + +Or set the environment variable: +``` +set 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: +``` +vcpkg install catch2 cxxopts toml11 +``` + +Then run `vcpkg install` (manifest mode) or the above command to install all at once. + +### Dev-Only Dependencies + +Use the `"host"` field or place test dependencies under a feature: +```json +{ + "dependencies": [ + "fmt", + "spdlog" + ], + "features": { + "tests": { + "description": "Build tests", + "dependencies": ["gtest"] + } + } +} +``` + +Activate with: `vcpkg install --x-feature=tests` or in CMake: `-DVCPKG_MANIFEST_FEATURES=tests` + +--- + +## Version Management + +### Pinning a Specific Version + +In `vcpkg.json`, use `"version>="` with overrides: +```json +{ + "dependencies": ["fmt"], + "overrides": [ + { + "name": "fmt", + "version": "10.2.0" + } + ], + "builtin-baseline": "" +} +``` + +The `builtin-baseline` is **required** when using versioning. Get the latest baseline: +``` +git -C rev-parse HEAD +``` + +### Version Overrides + +To force a specific version of a transitive dependency across your entire project, use `"overrides"` in `vcpkg.json`: +```json +{ + "dependencies": ["protobuf", "grpc"], + "overrides": [ + { + "name": "zlib", + "version": "1.3.1" + } + ], + "builtin-baseline": "" +} +``` + +**Key points:** +- `overrides` takes precedence over all version constraints, including transitive ones +- You **must** have a `builtin-baseline` set for overrides to work +- The version must exist in the vcpkg registry at or after the baseline commit +- Use `vcpkg x-history zlib` to see available versions + +### Updating the Baseline + +The baseline is a Git commit SHA in the vcpkg repository that pins all port versions: +```json +{ + "builtin-baseline": "a1b2c3d4e5f6..." +} +``` + +To update to the latest: +```bash +cd +git pull +git rev-parse HEAD +``` +Then paste the new SHA into `builtin-baseline`. + +**Important:** Updating the baseline may change versions of *all* dependencies. Use `overrides` to pin specific packages if needed. + +--- + +## Cross-Platform + +### Cross-Compiling for arm64 + +``` +vcpkg install :arm64-linux +``` + +Or set the triplet in CMake: +``` +cmake -B build -DVCPKG_TARGET_TRIPLET=arm64-linux -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake +``` + +You may need a cross-compilation toolchain installed (e.g., `aarch64-linux-gnu-gcc`). + +For **arm64-windows**, just use the triplet directly — no cross-compiler needed on ARM64 Windows or with MSVC: +``` +vcpkg install :arm64-windows +``` + +### Building for Android (NDK) + +1. Set environment variables: +```bash +export ANDROID_NDK_HOME=/path/to/ndk +export VCPKG_DEFAULT_TRIPLET=arm64-android +``` + +2. Install packages: +``` +vcpkg install :arm64-android +``` + +Available Android triplets: `arm-neon-android`, `arm64-android`, `x86-android`, `x64-android` + +3. In CMake: +``` +cmake -B build \ + -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \ + -DVCPKG_TARGET_TRIPLET=arm64-android \ + -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \ + -DANDROID_ABI=arm64-v8a \ + -DANDROID_PLATFORM=android-24 +``` diff --git a/skills/vcpkg/references/ci.md b/skills/vcpkg/references/ci.md new file mode 100644 index 000000000..39b24782e --- /dev/null +++ b/skills/vcpkg/references/ci.md @@ -0,0 +1,96 @@ +# 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, setting up devcontainers, 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:** +``` +set VCPKG_BINARY_SOURCES=clear;x-azblob,https://myaccount.blob.core.windows.net/vcpkg-cache,,readwrite +``` + +**GitHub Packages (NuGet):** +``` +set VCPKG_BINARY_SOURCES=clear;nuget,https://nuget.pkg.github.com/your-org/index.json,readwrite +``` + +**Local filesystem:** +``` +set VCPKG_BINARY_SOURCES=clear;files,C:/vcpkg-cache,readwrite +``` + +**Sharing between CI and local dev:** Use the same remote cache (Azure Blob or NuGet feed) in both environments. CI writes (`readwrite`), developers read (`read`): +``` +# CI (writes cache) +set VCPKG_BINARY_SOURCES=clear;x-azblob,https://myaccount.blob.core.windows.net/cache,,readwrite + +# Developer (reads cache) +set VCPKG_BINARY_SOURCES=clear;x-azblob,https://myaccount.blob.core.windows.net/cache,,read +``` + +--- + +## Generating an SBOM (Software Bill of Materials) + +vcpkg can generate an SBOM in SPDX format: +``` +vcpkg install --x-write-nuget-packages-config=packages.config +``` + +For manifest mode, after install check `vcpkg_installed//share/` for SPDX files. Each installed port generates an SPDX JSON document at: +``` +vcpkg_installed//share//sbom.spdx.json +``` + +To aggregate: use `vcpkg x-package-info --x-installed` to list all packages and versions, then feed into your SBOM toolchain (e.g., Microsoft SBOM Tool, CycloneDX). + +--- + +## 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 in a CI matrix: +```yaml +# GitHub Actions example +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: Install vcpkg + run: | + git clone https://github.com/microsoft/vcpkg + ./vcpkg/bootstrap-vcpkg.sh + - name: Install dependencies + run: vcpkg install --triplet ${{ matrix.triplet }} +``` diff --git a/skills/vcpkg/references/registries.md b/skills/vcpkg/references/registries.md new file mode 100644 index 000000000..61a5fa375 --- /dev/null +++ b/skills/vcpkg/references/registries.md @@ -0,0 +1,133 @@ +# 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": "", + "packages": ["company-utils", "internal-lib"] + } + ], + "default-registry": { + "kind": "builtin", + "baseline": "" + } +} +``` + +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": "" + }, + "registries": [ + { + "kind": "git", + "repository": "https://github.com/your-org/vcpkg-registry.git", + "baseline": "", + "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"] +} +``` + +**`portfile.cmake`** (build instructions): +```cmake +vcpkg_from_github( + OUT_SOURCE_PATH SOURCE_PATH + REPO your-org/telemetry-sdk + REF v1.0.0 + SHA512 +) + +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") +``` + +Use it: `vcpkg install telemetry-sdk --overlay-ports=./my-overlays` +Or in `vcpkg-configuration.json`: +```json +{ + "overlay-ports": ["./my-overlays"] +} +``` + +--- + +## Default Features + +Set default features in `vcpkg.json` for a port so they're always enabled: +```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" } + } +} +``` diff --git a/skills/vcpkg/references/troubleshooting.md b/skills/vcpkg/references/troubleshooting.md new file mode 100644 index 000000000..664eb8d01 --- /dev/null +++ b/skills/vcpkg/references/troubleshooting.md @@ -0,0 +1,94 @@ +# 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: +``` +/buildtrees// +``` + +Key log files: +- `config--out.log` — CMake configure output +- `build--out.log` — Build (compile) output +- `install--out.log` — Install step output +- `config--err.log` — CMake configure errors +- `build--err.log` — Build errors +- `package--out.log` — Packaging output + +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=/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: +``` +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: +``` +vcpkg install curl[ssl,ssh] # reinstalls with new features +``` + +### 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 + +```bash +# Remove build trees (intermediate build files) +rm -rf /buildtrees + +# Remove downloaded archives +rm -rf /downloads + +# Remove installed packages (classic mode only) +rm -rf /installed + +# Remove all package build artifacts +vcpkg x-clean + +# In manifest mode, remove the local vcpkg_installed directory +rm -rf vcpkg_installed/ +``` From 8fc954300620717dd5e30e095cdc5ee72c626113 Mon Sep 17 00:00:00 2001 From: Augustin Popa Date: Wed, 15 Jul 2026 09:20:10 -0700 Subject: [PATCH 2/6] vcpkg skill automated README update --- docs/README.skills.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/README.skills.md b/docs/README.skills.md index 63ddc1e51..0da5f9e53 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -390,6 +390,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [update-markdown-file-index](../skills/update-markdown-file-index/SKILL.md)
`gh skills install github/awesome-copilot update-markdown-file-index` | Update a markdown file section with an index/table of files from a specified folder. | None | | [update-specification](../skills/update-specification/SKILL.md)
`gh skills install github/awesome-copilot update-specification` | Update an existing specification file for the solution, optimized for Generative AI consumption based on new requirements or updates to any existing code. | None | | [vardoger-analyze](../skills/vardoger-analyze/SKILL.md)
`gh skills install github/awesome-copilot vardoger-analyze` | Use when the user asks to personalize the GitHub Copilot CLI assistant, adapt Copilot to their style, use vardoger, or analyze their Copilot CLI conversation history. Reads the local session directory at `~/.copilot/session-state/`, extracts recurring preferences and conventions, and writes a fenced personalization block into `~/.copilot/copilot-instructions.md`. Runs entirely on the user's machine via the local `vardoger` CLI (`pipx install vardoger`); no network calls and no uploads. Triggers: 'personalize my copilot', 'analyze my copilot history', 'tailor copilot to me', 'run vardoger', 'update my copilot instructions from history', 'make copilot learn my style'. | None | +| [vcpkg](../skills/vcpkg/SKILL.md)
`gh skills install github/awesome-copilot vcpkg` | 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). | `references/ci.md`
`references/registries.md`
`references/troubleshooting.md` | | [vscode-ext-commands](../skills/vscode-ext-commands/SKILL.md)
`gh skills install github/awesome-copilot vscode-ext-commands` | Guidelines for contributing commands in VS Code extensions. Indicates naming convention, visibility, localization and other relevant attributes, following VS Code extension development guidelines, libraries and good practices | None | | [vscode-ext-localization](../skills/vscode-ext-localization/SKILL.md)
`gh skills install github/awesome-copilot vscode-ext-localization` | Guidelines for proper localization of VS Code extensions, following VS Code extension development guidelines, libraries and good practices | None | | [web-design-reviewer](../skills/web-design-reviewer/SKILL.md)
`gh skills install github/awesome-copilot web-design-reviewer` | This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level. | `references/framework-fixes.md`
`references/visual-checklist.md` | From bd3e6493e9b115db713559cfe5dd95ae4bbd4680 Mon Sep 17 00:00:00 2001 From: Augustin Popa Date: Thu, 16 Jul 2026 23:37:35 -0700 Subject: [PATCH 3/6] Addressed PR review feedback --- skills/vcpkg/SKILL.md | 107 +++++++++++---------- skills/vcpkg/references/ci.md | 68 +++++++++---- skills/vcpkg/references/registries.md | 6 +- skills/vcpkg/references/troubleshooting.md | 32 ++++-- 4 files changed, 132 insertions(+), 81 deletions(-) diff --git a/skills/vcpkg/SKILL.md b/skills/vcpkg/SKILL.md index 8fe2eaa46..313a74533 100644 --- a/skills/vcpkg/SKILL.md +++ b/skills/vcpkg/SKILL.md @@ -1,6 +1,6 @@ --- 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). +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. @@ -32,9 +32,9 @@ Classic mode is simpler for quick one-off installs but lacks version pinning, pe If the user is working inside **Visual Studio** (not VS Code), prefer using the **in-box copy of vcpkg that ships with Visual Studio** rather than a standalone vcpkg clone, unless the user indicates they want to use a different installation. The VS-bundled vcpkg: - Is located under the Visual Studio installation directory (e.g., `C:\Program Files\Microsoft Visual Studio\\\VC\vcpkg\`) -- Is automatically integrated with MSBuild — no need to run `vcpkg integrate install` +- Supports user-wide MSBuild integration after running `vcpkg integrate install` once - Stays up-to-date with Visual Studio updates -- Works out of the box with CMake projects opened via "Open Folder" or CMake presets +- Can be used with Visual Studio Open Folder/CMake Presets projects, but CMake must still be configured to use the vcpkg toolchain (for example via `CMakePresets.json` or `-DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake`) If the user has a standalone vcpkg installation and prefers to use that instead, respect their preference. @@ -44,12 +44,14 @@ If the user has a standalone vcpkg installation and prefers to use that instead, ### 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": [] + "dependencies": ["fmt"] } ``` @@ -58,18 +60,19 @@ If the user has a standalone vcpkg installation and prefers to use that instead, 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=/scripts/buildsystems/vcpkg.cmake ``` ### Adding vcpkg to an Existing Visual Studio Solution -1. Run `vcpkg integrate install` (one-time, system-wide) +1. Run `vcpkg integrate install` (one-time, user-wide) 2. Create `vcpkg.json` in the solution directory 3. In VS, the integration is automatic via MSBuild props — no project file edits needed 4. Or per-project: add to `.vcxproj`: @@ -82,7 +85,7 @@ cmake -B build -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cm 1. List what's currently installed: `vcpkg list` 2. Create `vcpkg.json` with those dependencies -3. Delete global installs: `vcpkg remove --outdated --recurse` +3. Delete global installs: `vcpkg remove --recurse "*"` 4. Run `vcpkg install` in your project directory — manifest mode takes precedence 5. Update your build system to use `CMAKE_TOOLCHAIN_FILE` if not already @@ -105,32 +108,37 @@ In **manifest mode** (`vcpkg.json`), specify features in the dependencies array: ``` 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 environment variable: + +```powershell +$env:VCPKG_DEFAULT_TRIPLET = "x64-linux" ``` -set VCPKG_DEFAULT_TRIPLET=x64-linux + +```bash +export VCPKG_DEFAULT_TRIPLET=x64-linux ``` ### Bulk-Adding Multiple Dependencies @@ -143,7 +151,7 @@ In `vcpkg.json`, list them in the dependencies array: ``` In classic mode: -``` +```console vcpkg install catch2 cxxopts toml11 ``` @@ -151,7 +159,7 @@ Then run `vcpkg install` (manifest mode) or the above command to install all at ### Dev-Only Dependencies -Use the `"host"` field or place test dependencies under a feature: +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": [ @@ -173,107 +181,100 @@ Activate with: `vcpkg install --x-feature=tests` or in CMake: `-DVCPKG_MANIFEST_ ## Version Management -### Pinning a Specific Version +### Setting Versions for Individual Dependencies -In `vcpkg.json`, use `"version>="` with overrides: +In `vcpkg.json`, prefer using `"version>="` as a minimum version constraint over overrides. Example: ```json { - "dependencies": ["fmt"], - "overrides": [ + "dependencies": [ { "name": "fmt", - "version": "10.2.0" + "version>=": "10.2.0" } ], "builtin-baseline": "" } ``` -The `builtin-baseline` is **required** when using versioning. Get the latest baseline: -``` -git -C rev-parse HEAD -``` - -### Version Overrides - -To force a specific version of a transitive dependency across your entire project, use `"overrides"` in `vcpkg.json`: +If the user insists on hard-coding a version and is okay dealing with ABI compatibility issues manually, use overrides instead: ```json { - "dependencies": ["protobuf", "grpc"], + "dependencies": ["fmt"], "overrides": [ { - "name": "zlib", - "version": "1.3.1" + "name": "fmt", + "version": "10.2.0" } ], "builtin-baseline": "" } ``` +The `builtin-baseline` is **very important** when using versioning. Suggest baselines at minimum as a way to set all library versions to a known-good state, and use overrides only when necessary. + **Key points:** - `overrides` takes precedence over all version constraints, including transitive ones - You **must** have a `builtin-baseline` set for overrides to work -- The version must exist in the vcpkg registry at or after the baseline commit +- The version must exist in the selected vcpkg registry's version database; an override may select a version older than the baseline version - Use `vcpkg x-history zlib` to see available versions -### Updating the Baseline - -The baseline is a Git commit SHA in the vcpkg repository that pins all port versions: -```json -{ - "builtin-baseline": "a1b2c3d4e5f6..." -} -``` - -To update to the latest: -```bash -cd -git pull -git rev-parse HEAD -``` -Then paste the new SHA into `builtin-baseline`. - -**Important:** Updating the baseline may change versions of *all* dependencies. Use `overrides` to pin specific packages if needed. - --- ## Cross-Platform ### Cross-Compiling for arm64 -``` +```console vcpkg install :arm64-linux ``` Or set the triplet in CMake: +```powershell +cmake -B build -DVCPKG_TARGET_TRIPLET=arm64-linux -DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake ``` + +```bash cmake -B build -DVCPKG_TARGET_TRIPLET=arm64-linux -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake ``` You may need a cross-compilation toolchain installed (e.g., `aarch64-linux-gnu-gcc`). For **arm64-windows**, just use the triplet directly — no cross-compiler needed on ARM64 Windows or with MSVC: -``` +```console vcpkg install :arm64-windows ``` ### Building for Android (NDK) 1. Set environment variables: +```powershell +$env:ANDROID_NDK_HOME = "C:\path\to\ndk" +$env:VCPKG_DEFAULT_TRIPLET = "arm64-android" +``` + ```bash export ANDROID_NDK_HOME=/path/to/ndk export VCPKG_DEFAULT_TRIPLET=arm64-android ``` 2. Install packages: -``` +```console vcpkg install :arm64-android ``` Available Android triplets: `arm-neon-android`, `arm64-android`, `x86-android`, `x64-android` 3. In CMake: +```powershell +cmake -B build ` + -DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake ` + -DVCPKG_TARGET_TRIPLET=arm64-android ` + -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$env:ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake ` + -DANDROID_ABI=arm64-v8a ` + -DANDROID_PLATFORM=android-24 ``` + +```bash cmake -B build \ -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \ -DVCPKG_TARGET_TRIPLET=arm64-android \ diff --git a/skills/vcpkg/references/ci.md b/skills/vcpkg/references/ci.md index 39b24782e..403ad4d01 100644 --- a/skills/vcpkg/references/ci.md +++ b/skills/vcpkg/references/ci.md @@ -7,44 +7,65 @@ Reference for the `vcpkg` skill. Use this when a user asks about using vcpkg in 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" ``` -set VCPKG_BINARY_SOURCES=clear;x-azblob,https://myaccount.blob.core.windows.net/vcpkg-cache,,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" ``` -set 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" ``` **Local filesystem:** +```powershell +$env:VCPKG_BINARY_SOURCES = "clear;files,C:\vcpkg-cache,readwrite" ``` -set 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 (Azure Blob or NuGet feed) in both environments. CI writes (`readwrite`), developers read (`read`): +```powershell +# CI (writes cache) +$env:VCPKG_BINARY_SOURCES = "clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$env:AZURE_STORAGE_SAS_TOKEN,readwrite" + +# Developer (reads cache) +$env:VCPKG_BINARY_SOURCES = "clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$env:AZURE_STORAGE_SAS_TOKEN,read" ``` +```bash # CI (writes cache) -set VCPKG_BINARY_SOURCES=clear;x-azblob,https://myaccount.blob.core.windows.net/cache,,readwrite +export VCPKG_BINARY_SOURCES="clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$AZURE_STORAGE_SAS_TOKEN,readwrite" # Developer (reads cache) -set VCPKG_BINARY_SOURCES=clear;x-azblob,https://myaccount.blob.core.windows.net/cache,,read +export VCPKG_BINARY_SOURCES="clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$AZURE_STORAGE_SAS_TOKEN,read" ``` --- ## Generating an SBOM (Software Bill of Materials) -vcpkg can generate an SBOM in SPDX format: -``` -vcpkg install --x-write-nuget-packages-config=packages.config +vcpkg emits per-port SPDX SBOM files during normal source builds; no special SBOM flag is required. +```console +vcpkg install ``` -For manifest mode, after install check `vcpkg_installed//share/` for SPDX files. Each installed port generates an SPDX JSON document at: -``` -vcpkg_installed//share//sbom.spdx.json +Each installed port writes: +```text +//share//vcpkg.spdx.json ``` -To aggregate: use `vcpkg x-package-info --x-installed` to list all packages and versions, then feed into your SBOM toolchain (e.g., Microsoft SBOM Tool, CycloneDX). +`` depends on integration mode: +- CLI manifest mode: `/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 (for example with `vcpkg x-package-info --x-installed`) and merge/transform the per-port SPDX files in your SBOM pipeline. --- @@ -74,6 +95,7 @@ Option 2: **Script-based** — create a scheduled CI job that: Test across multiple triplets in a CI matrix: ```yaml # GitHub Actions example +runs-on: ${{ matrix.os }} strategy: matrix: triplet: [x64-windows, x64-linux, x64-osx] @@ -87,10 +109,20 @@ strategy: steps: - uses: actions/checkout@v4 - - name: Install vcpkg - run: | - git clone https://github.com/microsoft/vcpkg - ./vcpkg/bootstrap-vcpkg.sh - - name: Install dependencies - run: vcpkg install --triplet ${{ matrix.triplet }} + - 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 }} ``` diff --git a/skills/vcpkg/references/registries.md b/skills/vcpkg/references/registries.md index 61a5fa375..a42d67c92 100644 --- a/skills/vcpkg/references/registries.md +++ b/skills/vcpkg/references/registries.md @@ -93,7 +93,9 @@ file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include") vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE") ``` -Use it: `vcpkg install telemetry-sdk --overlay-ports=./my-overlays` +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 { @@ -105,7 +107,7 @@ Or in `vcpkg-configuration.json`: ## Default Features -Set default features in `vcpkg.json` for a port so they're always enabled: +Control whether a dependency's existing default features are enabled, and request additional features in a project manifest: ```json { "dependencies": [ diff --git a/skills/vcpkg/references/troubleshooting.md b/skills/vcpkg/references/troubleshooting.md index 664eb8d01..497669cd3 100644 --- a/skills/vcpkg/references/troubleshooting.md +++ b/skills/vcpkg/references/troubleshooting.md @@ -11,11 +11,10 @@ Build logs are stored at: Key log files: - `config--out.log` — CMake configure output -- `build--out.log` — Build (compile) output -- `install--out.log` — Install step output -- `config--err.log` — CMake configure errors -- `build--err.log` — Build errors -- `package--out.log` — Packaging output +- `build---.log` — common build logs +- `install---.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. @@ -41,7 +40,7 @@ If CMake says `Could not find a package configuration file provided by "X"`: 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 ``` @@ -63,8 +62,8 @@ Update the features in `vcpkg.json`: Then run `vcpkg install` — vcpkg will detect the feature change and rebuild. In classic mode: -``` -vcpkg install curl[ssl,ssh] # reinstalls with new features +```console +vcpkg install curl[ssl,ssh] --recurse # permits rebuilding with the new feature set ``` ### Replacing One Library with Another @@ -76,6 +75,23 @@ vcpkg install curl[ssl,ssh] # reinstalls with new features ### Cleaning the vcpkg Cache +```powershell +# Remove build trees (intermediate build files) +Remove-Item -Recurse -Force \buildtrees + +# Remove downloaded archives +Remove-Item -Recurse -Force \downloads + +# Remove installed packages (classic mode only) +Remove-Item -Recurse -Force \installed + +# Remove all package build artifacts +vcpkg x-clean + +# In manifest mode, remove the local vcpkg_installed directory +Remove-Item -Recurse -Force .\vcpkg_installed +``` + ```bash # Remove build trees (intermediate build files) rm -rf /buildtrees From a5f0c6cff155f4e7638e945b2cab5cf6e49e9685 Mon Sep 17 00:00:00 2001 From: Augustin Popa Date: Thu, 16 Jul 2026 23:51:46 -0700 Subject: [PATCH 4/6] Completed another review pass, making more improvements --- skills/vcpkg/SKILL.md | 93 ++++++---------------- skills/vcpkg/references/ci.md | 28 +++---- skills/vcpkg/references/troubleshooting.md | 26 +----- 3 files changed, 42 insertions(+), 105 deletions(-) diff --git a/skills/vcpkg/SKILL.md b/skills/vcpkg/SKILL.md index 313a74533..606e86eb2 100644 --- a/skills/vcpkg/SKILL.md +++ b/skills/vcpkg/SKILL.md @@ -38,6 +38,12 @@ If the user is working inside **Visual Studio** (not VS Code), prefer using the 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 @@ -128,18 +134,10 @@ 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 environment variable: - -```powershell -$env:VCPKG_DEFAULT_TRIPLET = "x64-linux" +cmake -B build -DVCPKG_TARGET_TRIPLET=x64-linux -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake ``` -```bash -export VCPKG_DEFAULT_TRIPLET=x64-linux -``` +Or set the default triplet via environment variable (using the shell syntax above): `VCPKG_DEFAULT_TRIPLET=x64-linux`. ### Bulk-Adding Multiple Dependencies @@ -162,13 +160,9 @@ Then run `vcpkg install` (manifest mode) or the above command to install all at 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", - "spdlog" - ], + "dependencies": ["fmt"], "features": { "tests": { - "description": "Build tests", "dependencies": ["gtest"] } } @@ -183,40 +177,30 @@ Activate with: `vcpkg install --x-feature=tests` or in CMake: `-DVCPKG_MANIFEST_ ### Setting Versions for Individual Dependencies -In `vcpkg.json`, prefer using `"version>="` as a minimum version constraint over overrides. Example: +Prefer `"version>="` for minimum-version constraints: ```json { - "dependencies": [ - { - "name": "fmt", - "version>=": "10.2.0" - } - ], + "dependencies": [{ "name": "fmt", "version>=": "10.2.0" }], "builtin-baseline": "" } ``` -If the user insists on hard-coding a version and is okay dealing with ABI compatibility issues manually, use overrides instead: +Use `overrides` only when a hard pin is required: ```json { "dependencies": ["fmt"], - "overrides": [ - { - "name": "fmt", - "version": "10.2.0" - } - ], + "overrides": [{ "name": "fmt", "version": "10.2.0" }], "builtin-baseline": "" } ``` -The `builtin-baseline` is **very important** when using versioning. Suggest baselines at minimum as a way to set all library versions to a known-good state, and use overrides only when necessary. +Always include `builtin-baseline` when using versioning. **Key points:** -- `overrides` takes precedence over all version constraints, including transitive ones -- You **must** have a `builtin-baseline` set for overrides to work -- The version must exist in the selected vcpkg registry's version database; an override may select a version older than the baseline version -- Use `vcpkg x-history zlib` to see available versions +- `overrides` take precedence over all version constraints, including transitive ones. +- `builtin-baseline` is required for overrides. +- Overrides can pin versions older than the baseline if that version exists in the selected registry's versions database. +- Use `vcpkg x-history ` to inspect available versions. --- @@ -229,12 +213,8 @@ vcpkg install :arm64-linux ``` Or set the triplet in CMake: -```powershell -cmake -B build -DVCPKG_TARGET_TRIPLET=arm64-linux -DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -``` - -```bash -cmake -B build -DVCPKG_TARGET_TRIPLET=arm64-linux -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake +```console +cmake -B build -DVCPKG_TARGET_TRIPLET=arm64-linux -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake ``` You may need a cross-compilation toolchain installed (e.g., `aarch64-linux-gnu-gcc`). @@ -246,39 +226,16 @@ vcpkg install :arm64-windows ### Building for Android (NDK) -1. Set environment variables: -```powershell -$env:ANDROID_NDK_HOME = "C:\path\to\ndk" -$env:VCPKG_DEFAULT_TRIPLET = "arm64-android" -``` - -```bash -export ANDROID_NDK_HOME=/path/to/ndk -export VCPKG_DEFAULT_TRIPLET=arm64-android -``` - -2. Install packages: +1. Install packages: ```console vcpkg install :arm64-android ``` Available Android triplets: `arm-neon-android`, `arm64-android`, `x86-android`, `x64-android` -3. In CMake: -```powershell -cmake -B build ` - -DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake ` - -DVCPKG_TARGET_TRIPLET=arm64-android ` - -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$env:ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake ` - -DANDROID_ABI=arm64-v8a ` - -DANDROID_PLATFORM=android-24 +2. In CMake: +```console +cmake -B build -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=arm64-android -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=/build/cmake/android.toolchain.cmake -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-24 ``` -```bash -cmake -B build \ - -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \ - -DVCPKG_TARGET_TRIPLET=arm64-android \ - -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \ - -DANDROID_ABI=arm64-v8a \ - -DANDROID_PLATFORM=android-24 -``` +For expanded CI and shell-specific examples, see `references/ci.md`. diff --git a/skills/vcpkg/references/ci.md b/skills/vcpkg/references/ci.md index 403ad4d01..b997c44cf 100644 --- a/skills/vcpkg/references/ci.md +++ b/skills/vcpkg/references/ci.md @@ -21,6 +21,18 @@ $env:VCPKG_BINARY_SOURCES = "clear;nuget,https://nuget.pkg.github.com/your-org/i ```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 @@ -30,21 +42,7 @@ $env:VCPKG_BINARY_SOURCES = "clear;files,C:\vcpkg-cache,readwrite" export VCPKG_BINARY_SOURCES="clear;files,/var/tmp/vcpkg-cache,readwrite" ``` -**Sharing between CI and local dev:** Use the same remote cache (Azure Blob or NuGet feed) in both environments. CI writes (`readwrite`), developers read (`read`): -```powershell -# CI (writes cache) -$env:VCPKG_BINARY_SOURCES = "clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$env:AZURE_STORAGE_SAS_TOKEN,readwrite" - -# Developer (reads cache) -$env:VCPKG_BINARY_SOURCES = "clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$env:AZURE_STORAGE_SAS_TOKEN,read" -``` -```bash -# CI (writes cache) -export VCPKG_BINARY_SOURCES="clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$AZURE_STORAGE_SAS_TOKEN,readwrite" - -# Developer (reads cache) -export VCPKG_BINARY_SOURCES="clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$AZURE_STORAGE_SAS_TOKEN,read" -``` +**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`. --- diff --git a/skills/vcpkg/references/troubleshooting.md b/skills/vcpkg/references/troubleshooting.md index 497669cd3..3e70ba40c 100644 --- a/skills/vcpkg/references/troubleshooting.md +++ b/skills/vcpkg/references/troubleshooting.md @@ -76,35 +76,17 @@ vcpkg install curl[ssl,ssh] --recurse # permits rebuilding with the new featur ### Cleaning the vcpkg Cache ```powershell -# Remove build trees (intermediate build files) -Remove-Item -Recurse -Force \buildtrees - -# Remove downloaded archives -Remove-Item -Recurse -Force \downloads - -# Remove installed packages (classic mode only) -Remove-Item -Recurse -Force \installed - # Remove all package build artifacts vcpkg x-clean -# In manifest mode, remove the local vcpkg_installed directory -Remove-Item -Recurse -Force .\vcpkg_installed +# Optional: remove local cache/install directories +Remove-Item -Recurse -Force \buildtrees,\downloads,\installed,.\vcpkg_installed ``` ```bash -# Remove build trees (intermediate build files) -rm -rf /buildtrees - -# Remove downloaded archives -rm -rf /downloads - -# Remove installed packages (classic mode only) -rm -rf /installed - # Remove all package build artifacts vcpkg x-clean -# In manifest mode, remove the local vcpkg_installed directory -rm -rf vcpkg_installed/ +# Optional: remove local cache/install directories +rm -rf /buildtrees /downloads /installed ./vcpkg_installed ``` From ca6de3fc482a5c70ab8a9bd4c036dc05c5f89c74 Mon Sep 17 00:00:00 2001 From: Augustin Popa Date: Fri, 17 Jul 2026 01:07:54 -0700 Subject: [PATCH 5/6] Addressed more PR review feedback --- skills/vcpkg/SKILL.md | 48 +++++++++++++--------- skills/vcpkg/references/registries.md | 7 +++- skills/vcpkg/references/troubleshooting.md | 27 ++++++++---- 3 files changed, 53 insertions(+), 29 deletions(-) diff --git a/skills/vcpkg/SKILL.md b/skills/vcpkg/SKILL.md index 606e86eb2..e69095441 100644 --- a/skills/vcpkg/SKILL.md +++ b/skills/vcpkg/SKILL.md @@ -30,11 +30,10 @@ Classic mode is simpler for quick one-off installs but lacks version pinning, pe ### Visual Studio Environment -If the user is working inside **Visual Studio** (not VS Code), prefer using the **in-box copy of vcpkg that ships with Visual Studio** rather than a standalone vcpkg clone, unless the user indicates they want to use a different installation. The VS-bundled vcpkg: -- Is located under the Visual Studio installation directory (e.g., `C:\Program Files\Microsoft Visual Studio\\\VC\vcpkg\`) -- Supports user-wide MSBuild integration after running `vcpkg integrate install` once -- Stays up-to-date with Visual Studio updates -- Can be used with Visual Studio Open Folder/CMake Presets projects, but CMake must still be configured to use the vcpkg toolchain (for example via `CMakePresets.json` or `-DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake`) +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\\\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. @@ -82,18 +81,28 @@ cmake -B build -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cm 2. Create `vcpkg.json` in the solution directory 3. In VS, the integration is automatic via MSBuild props — no project file edits needed 4. Or per-project: add to `.vcxproj`: -```xml - - -``` + - In the project file's top-level `PropertyGroup`, define `VcpkgRoot`: + ```xml + + C:\vcpkg + + ``` + - Import `vcpkg.props` near the top of the project file: + ```xml + + ``` + - Import `vcpkg.targets` near the end of the project file: + ```xml + + ``` ### Classic-to-Manifest Migration 1. List what's currently installed: `vcpkg list` 2. Create `vcpkg.json` with those dependencies -3. Delete global installs: `vcpkg remove --recurse "*"` -4. Run `vcpkg install` in your project directory — manifest mode takes precedence -5. Update your build system to use `CMAKE_TOOLCHAIN_FILE` if not already +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 --recurse` if you no longer need them --- @@ -194,12 +203,12 @@ Use `overrides` only when a hard pin is required: } ``` -Always include `builtin-baseline` when using versioning. +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. -- `builtin-baseline` is required for overrides. -- Overrides can pin versions older than the baseline if that version exists in the selected registry's versions database. +- 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. - Use `vcpkg x-history ` to inspect available versions. --- @@ -219,23 +228,24 @@ cmake -B build -DVCPKG_TARGET_TRIPLET=arm64-linux -DCMAKE_TOOLCHAIN_FILE=:arm64-windows ``` ### Building for Android (NDK) -1. Install packages: +1. Set `ANDROID_NDK_HOME` to your NDK path. +2. Install packages: ```console vcpkg install :arm64-android ``` Available Android triplets: `arm-neon-android`, `arm64-android`, `x86-android`, `x64-android` -2. In CMake: +3. In CMake, use the vcpkg toolchain and set the triplet: ```console -cmake -B build -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=arm64-android -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=/build/cmake/android.toolchain.cmake -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-24 +cmake -B build -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=arm64-android ``` For expanded CI and shell-specific examples, see `references/ci.md`. diff --git a/skills/vcpkg/references/registries.md b/skills/vcpkg/references/registries.md index a42d67c92..180eda6b3 100644 --- a/skills/vcpkg/references/registries.md +++ b/skills/vcpkg/references/registries.md @@ -72,7 +72,12 @@ my-overlays/ "name": "telemetry-sdk", "version": "1.0.0", "description": "Internal telemetry SDK", - "dependencies": ["curl", "nlohmann-json"] + "dependencies": [ + "curl", + "nlohmann-json", + { "name": "vcpkg-cmake", "host": true }, + { "name": "vcpkg-cmake-config", "host": true } + ] } ``` diff --git a/skills/vcpkg/references/troubleshooting.md b/skills/vcpkg/references/troubleshooting.md index 3e70ba40c..49400e359 100644 --- a/skills/vcpkg/references/troubleshooting.md +++ b/skills/vcpkg/references/troubleshooting.md @@ -76,17 +76,26 @@ vcpkg install curl[ssl,ssh] --recurse # permits rebuilding with the new featur ### Cleaning the vcpkg Cache ```powershell -# Remove all package build artifacts -vcpkg x-clean +# Remove build trees +Remove-Item -Recurse -Force \buildtrees -# Optional: remove local cache/install directories -Remove-Item -Recurse -Force \buildtrees,\downloads,\installed,.\vcpkg_installed +# Remove downloaded archives +Remove-Item -Recurse -Force \downloads + +# Remove installed packages (classic mode only) +Remove-Item -Recurse -Force \installed + +# Remove package build artifacts +Remove-Item -Recurse -Force \packages + +# In manifest mode, remove the local vcpkg_installed directory +Remove-Item -Recurse -Force .\vcpkg_installed ``` ```bash -# Remove all package build artifacts -vcpkg x-clean - -# Optional: remove local cache/install directories -rm -rf /buildtrees /downloads /installed ./vcpkg_installed +rm -rf /buildtrees +rm -rf /downloads +rm -rf /installed +rm -rf /packages +rm -rf ./vcpkg_installed ``` From 38cf671439287f09d09431385709783db1500c03 Mon Sep 17 00:00:00 2001 From: Augustin Popa Date: Fri, 17 Jul 2026 01:19:54 -0700 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- skills/vcpkg/SKILL.md | 6 +++--- skills/vcpkg/references/troubleshooting.md | 10 +++++----- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/skills/vcpkg/SKILL.md b/skills/vcpkg/SKILL.md index e69095441..cb8a45035 100644 --- a/skills/vcpkg/SKILL.md +++ b/skills/vcpkg/SKILL.md @@ -98,8 +98,8 @@ cmake -B build -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cm ### Classic-to-Manifest Migration -1. List what's currently installed: `vcpkg list` -2. Create `vcpkg.json` with those dependencies +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 --recurse` if you no longer need them @@ -209,7 +209,7 @@ Use a baseline for the registry that resolves the dependency. For the builtin re - `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. -- Use `vcpkg x-history ` to inspect available versions. +- Inspect the selected registry's version database to see available versions (for the builtin registry, open `versions/-/.json` in the vcpkg repository). --- diff --git a/skills/vcpkg/references/troubleshooting.md b/skills/vcpkg/references/troubleshooting.md index 49400e359..a8a531add 100644 --- a/skills/vcpkg/references/troubleshooting.md +++ b/skills/vcpkg/references/troubleshooting.md @@ -61,10 +61,7 @@ Update the features in `vcpkg.json`: Then run `vcpkg install` — vcpkg will detect the feature change and rebuild. -In classic mode: -```console -vcpkg install curl[ssl,ssh] --recurse # permits rebuilding with the new feature set -``` +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 @@ -88,8 +85,10 @@ Remove-Item -Recurse -Force \installed # Remove package build artifacts Remove-Item -Recurse -Force \packages -# In manifest mode, remove the local vcpkg_installed directory +# In CLI manifest mode, remove the manifest-root install directory Remove-Item -Recurse -Force .\vcpkg_installed + +# With CMake integration, remove \vcpkg_installed (or VCPKG_INSTALLED_DIR) ``` ```bash @@ -97,5 +96,6 @@ rm -rf /buildtrees rm -rf /downloads rm -rf /installed rm -rf /packages +# CLI manifest mode; with CMake integration, use /vcpkg_installed (or VCPKG_INSTALLED_DIR) rm -rf ./vcpkg_installed ```