github/awesome-copilot / skills/vcpkg
vcpkg
UnverifiedGuide 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 runningvcpkg integrate installonce.
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:
- Create
vcpkg.jsonin your project root:
{
"name": "my-project",
"version": "1.0.0",
"dependencies": ["fmt"]
}
- Wire into CMakeLists.txt:
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)
- Configure with vcpkg toolchain:
cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake
Adding vcpkg to an Existing Visual Studio Solution
- Create
vcpkg.jsonin the solution directory - 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 - For user-wide integration with a standalone vcpkg installation, run
vcpkg integrate installonce - Or for per-project integration, add to
.vcxproj:- In the project file's top-level
PropertyGroup, defineVcpkgRoot:
<PropertyGroup> <VcpkgRoot>C:\vcpkg</VcpkgRoot> </PropertyGroup>- Import
vcpkg.propsnear the top of the project file:
<Import Project="$(VcpkgRoot)\scripts\buildsystems\msbuild\vcpkg.props" />- Import
vcpkg.targetsnear the end of the project file:
<Import Project="$(VcpkgRoot)\scripts\buildsystems\msbuild\vcpkg.targets" /> - In the project file's top-level
Classic-to-Manifest Migration
- List what's currently installed with
vcpkg list, then identify which packages the project uses directly (the output also includes transitive packages) - Create
vcpkg.jsonwith only those direct dependencies - Run
vcpkg installin your project directory — manifest mode uses its own project-specificvcpkg_installedtree, so leave the classic-mode installed tree in place during migration - Update your build system to use
CMAKE_TOOLCHAIN_FILEif not already - Optional: remove classic-mode packages later by name with
vcpkg remove <package> --recurseif 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:
{
"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 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:
{
"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
Place test-only dependencies under an opt-in feature. The "host" field is reserved for build tools that must run on the host architecture:
{
"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:
{
"dependencies": [{ "name": "fmt", "version>=": "10.2.0" }],
"builtin-baseline": "<commit-sha>"
}
Use overrides only when a hard pin is required:
{
"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:
overridestake precedence over all version constraints, including transitive ones.- The selected registry must have a baseline;
builtin-baselineis 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>.jsonin the vcpkg repository).
Cross-Platform
Cross-Compiling for arm64
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:
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:
vcpkg install <packages>:arm64-windows
Building for Android (NDK)
- Set
ANDROID_NDK_HOMEto your NDK path. - Install packages:
vcpkg install <packages>:arm64-android
Available Android triplets: arm-neon-android, arm64-android, x86-android, x64-android
- In CMake, use the vcpkg toolchain and set the triplet:
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 117k | Updated | Claude CodeCodex | Unverified | Install |