Skip to content

Added vcpkg skill #2300

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
AugP wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Added vcpkg skill #2300

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e3fa321
Added vcpkg skill
AugP Jul 15, 2026
8fc9543
vcpkg skill automated README update
AugP Jul 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/README.skills.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)<br />`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)<br />`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)<br />`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)<br />`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`<br />`references/registries.md`<br />`references/troubleshooting.md` |
| [vscode-ext-commands](../skills/vscode-ext-commands/SKILL.md)<br />`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)<br />`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)<br />`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`<br />`references/visual-checklist.md` |
Expand Down
283 changes: 283 additions & 0 deletions skills/vcpkg/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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\<version>\<edition>\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)
Comment on lines +61 to +62
```

3. Configure with vcpkg toolchain:
```
cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/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
<Import Project="<vcpkg-root>\scripts\buildsystems\msbuild\vcpkg.props" />
<Import Project="<vcpkg-root>\scripts\buildsystems\msbuild\vcpkg.targets" />
```

### 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": "<commit-sha>"
}
```

The `builtin-baseline` is **required** when using versioning. Get the latest baseline:
```
git -C <vcpkg-root> rev-parse HEAD
```
Comment on lines +192 to +195

### 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": "<commit-sha>"
}
```

**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 <vcpkg-root>
git pull
git rev-parse HEAD
Comment on lines +230 to +232
```
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 <packages>: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 <packages>: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 <packages>: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
```
96 changes: 96 additions & 0 deletions skills/vcpkg/references/ci.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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,<sas-token>,readwrite
Comment on lines +9 to +11
```

**GitHub Packages (NuGet):**
```
set VCPKG_BINARY_SOURCES=clear;nuget,https://nuget.pkg.github.com/your-org/index.json,readwrite
Comment on lines +14 to +16
```

**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,<sas>,readwrite

# Developer (reads cache)
set VCPKG_BINARY_SOURCES=clear;x-azblob,https://myaccount.blob.core.windows.net/cache,<sas>,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/<triplet>/share/` for SPDX files. Each installed port generates an SPDX JSON document at:
```
vcpkg_installed/<triplet>/share/<port>/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 }}
Comment on lines +90 to +95
```
Loading
Loading