Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-08-01 23:12:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Addressed PR review feedback

Browse Source
This commit is contained in:
Augustin Popa
2026-07-16 23:37:35 -07:00
parent 8fc9543006
commit bd3e6493e9
4 changed files with 139 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/vcpkg/SKILL.md
+60 -59
View File
@@ -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\<version>\<edition>\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=<vcpkg-root>/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=<vcpkg-root>/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=<vcpkg-root>/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,9 +181,22 @@ 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": [
{
"name": "fmt",
"version>=": "10.2.0"
}
],
"builtin-baseline": "<commit-sha>"
}
```
If the user insists on hard-coding a version and is okay dealing with ABI compatibility issues manually, use overrides instead:
```json
{
"dependencies": ["fmt"],
@@ -189,91 +210,71 @@ In `vcpkg.json`, use `"version>="` with overrides:
}
```
The `builtin-baseline` is **required** when using versioning. Get the latest baseline:
```
git -C <vcpkg-root> 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": "<commit-sha>"
}
```
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 <vcpkg-root>
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 <packages>: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 <packages>: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 <packages>: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 \
skills/vcpkg/references/ci.md
+51 -19
View File
@@ -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,<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"
```
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)
set VCPKG_BINARY_SOURCES=clear;x-azblob,https://myaccount.blob.core.windows.net/cache,<sas>,readwrite
$env:VCPKG_BINARY_SOURCES = "clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$env:AZURE_STORAGE_SAS_TOKEN,readwrite"
# Developer (reads cache)
set VCPKG_BINARY_SOURCES=clear;x-azblob,https://myaccount.blob.core.windows.net/cache,<sas>,read
$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"
```
---
## 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/<triplet>/share/` for SPDX files. Each installed port generates an SPDX JSON document at:
```
vcpkg_installed/<triplet>/share/<port>/sbom.spdx.json
Each installed port writes:
```text
<installed-root>/<triplet>/share/<port>/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).
`<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 (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 }}
```
skills/vcpkg/references/registries.md
+4 -2
View File
@@ -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": [
skills/vcpkg/references/troubleshooting.md
+24 -8
View File
@@ -11,11 +11,10 @@ Build logs are stored at:
Key log files:
- `config-<triplet>-out.log` — CMake configure output
- `build-<triplet>-out.log` — Build (compile) output
- `install-<triplet>-out.log` — Install step output
- `config-<triplet>-err.log` — CMake configure errors
- `build-<triplet>-err.log` — Build errors
- `package-<triplet>-out.log` — Packaging 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.
@@ -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 <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 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 <vcpkg-root>/buildtrees