mirror of
https://github.com/github/awesome-copilot.git
synced 2026-08-13 20:59:12 +00:00
Added vcpkg skill
This commit is contained in:
Augustin Popa
@@ -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
|
||||
```
|
||||
|
||||
**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,<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 }}
|
||||
```
|
||||
@@ -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": "<commit-sha>",
|
||||
"packages": ["company-utils", "internal-lib"]
|
||||
}
|
||||
],
|
||||
"default-registry": {
|
||||
"kind": "builtin",
|
||||
"baseline": "<commit-sha>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. Then add the dependency normally in `vcpkg.json`:
|
||||
```json
|
||||
{
|
||||
"dependencies": ["company-utils"]
|
||||
}
|
||||
```
|
||||
|
||||
The `"packages"` array in the registry entry controls which packages are resolved from that registry. Packages not listed fall through to `default-registry`.
|
||||
|
||||
---
|
||||
|
||||
## Configuring Registries in `vcpkg-configuration.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"default-registry": {
|
||||
"kind": "builtin",
|
||||
"baseline": "<vcpkg-commit-sha>"
|
||||
},
|
||||
"registries": [
|
||||
{
|
||||
"kind": "git",
|
||||
"repository": "https://github.com/your-org/vcpkg-registry.git",
|
||||
"baseline": "<registry-commit-sha>",
|
||||
"packages": ["your-package-1", "your-package-2"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Place this file next to `vcpkg.json` in your project root.
|
||||
|
||||
---
|
||||
|
||||
## Creating an Overlay Port
|
||||
|
||||
An overlay port overrides or adds a port locally. Directory structure:
|
||||
```
|
||||
my-overlays/
|
||||
telemetry-sdk/
|
||||
portfile.cmake
|
||||
vcpkg.json
|
||||
```
|
||||
|
||||
**`vcpkg.json`** (port metadata):
|
||||
```json
|
||||
{
|
||||
"name": "telemetry-sdk",
|
||||
"version": "1.0.0",
|
||||
"description": "Internal telemetry SDK",
|
||||
"dependencies": ["curl", "nlohmann-json"]
|
||||
}
|
||||
```
|
||||
|
||||
**`portfile.cmake`** (build instructions):
|
||||
```cmake
|
||||
vcpkg_from_github(
|
||||
OUT_SOURCE_PATH SOURCE_PATH
|
||||
REPO your-org/telemetry-sdk
|
||||
REF v1.0.0
|
||||
SHA512 <hash>
|
||||
)
|
||||
|
||||
vcpkg_cmake_configure(SOURCE_PATH "${SOURCE_PATH}")
|
||||
vcpkg_cmake_install()
|
||||
vcpkg_cmake_config_fixup()
|
||||
|
||||
file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")
|
||||
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")
|
||||
```
|
||||
|
||||
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" }
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -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:
|
||||
```
|
||||
<vcpkg-root>/buildtrees/<port-name>/
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
When a build fails, vcpkg prints the path to the relevant log. Start with the `-err.log` file for the failing step.
|
||||
|
||||
---
|
||||
|
||||
## Resolving package-not-found After Install
|
||||
|
||||
If CMake says `Could not find a package configuration file provided by "X"`:
|
||||
|
||||
1. **Check toolchain file** — ensure `-DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake` is set
|
||||
2. **Check triplet match** — the installed triplet must match your build architecture
|
||||
3. **Check package name** — vcpkg port names may differ from CMake package names (e.g., port `nlohmann-json` → `find_package(nlohmann_json)`)
|
||||
4. **Check installed list** — run `vcpkg list` to confirm the package is actually installed
|
||||
5. **Clear CMake cache** — delete `CMakeCache.txt` and reconfigure
|
||||
|
||||
---
|
||||
|
||||
## Dependency Lifecycle
|
||||
|
||||
### Removing a Library
|
||||
|
||||
1. Remove it from `vcpkg.json` → `"dependencies"` array
|
||||
2. Run `vcpkg install` to reconcile (manifest mode auto-removes unused packages)
|
||||
|
||||
In classic mode:
|
||||
```
|
||||
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 <vcpkg-root>/buildtrees
|
||||
|
||||
# Remove downloaded archives
|
||||
rm -rf <vcpkg-root>/downloads
|
||||
|
||||
# Remove installed packages (classic mode only)
|
||||
rm -rf <vcpkg-root>/installed
|
||||
|
||||
# Remove all package build artifacts
|
||||
vcpkg x-clean
|
||||
|
||||
# In manifest mode, remove the local vcpkg_installed directory
|
||||
rm -rf vcpkg_installed/
|
||||
```
|
||||
Reference in New Issue
Block a user