mirror of
https://github.com/github/awesome-copilot.git
synced 2026-07-22 05:14:15 +00:00
chore: publish from main
This commit is contained in:
github-actions[bot]
@@ -0,0 +1,125 @@
|
||||
# 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, 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:**
|
||||
```powershell
|
||||
$env:VCPKG_BINARY_SOURCES = "clear;x-azblob,https://myaccount.blob.core.windows.net/vcpkg-cache,$env:AZURE_STORAGE_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"
|
||||
```
|
||||
```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
|
||||
$env: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 source in both environments and switch only the final mode token: CI uses `readwrite`, developers use `read`.
|
||||
|
||||
---
|
||||
|
||||
## Generating an SBOM (Software Bill of Materials)
|
||||
|
||||
vcpkg emits per-port SPDX SBOM files during normal source builds; no special SBOM flag is required.
|
||||
```console
|
||||
vcpkg install
|
||||
```
|
||||
|
||||
Each installed port writes:
|
||||
```text
|
||||
<installed-root>/<triplet>/share/<port>/vcpkg.spdx.json
|
||||
```
|
||||
|
||||
`<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 with `vcpkg list` and merge/transform their per-port SPDX files in your SBOM pipeline.
|
||||
|
||||
---
|
||||
|
||||
## 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 with this job-definition fragment nested under `jobs.<job-id>` in a GitHub Actions workflow:
|
||||
```yaml
|
||||
runs-on: ${{ matrix.os }}
|
||||
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: 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 }}
|
||||
```
|
||||
@@ -0,0 +1,140 @@
|
||||
# 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",
|
||||
{ "name": "vcpkg-cmake", "host": true },
|
||||
{ "name": "vcpkg-cmake-config", "host": true }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**`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")
|
||||
```
|
||||
|
||||
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
|
||||
{
|
||||
"overlay-ports": ["./my-overlays"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Default Features
|
||||
|
||||
Control whether a dependency's existing default features are enabled, and request additional features in a project manifest:
|
||||
```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,101 @@
|
||||
# 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>-<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.
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
```console
|
||||
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, 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
|
||||
|
||||
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
|
||||
|
||||
```powershell
|
||||
# Remove build trees
|
||||
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 package build artifacts
|
||||
Remove-Item -Recurse -Force <vcpkg-root>\packages
|
||||
|
||||
# In CLI manifest mode, remove the manifest-root install directory
|
||||
Remove-Item -Recurse -Force .\vcpkg_installed
|
||||
|
||||
# With CMake integration, remove <build-directory>\vcpkg_installed (or VCPKG_INSTALLED_DIR)
|
||||
```
|
||||
|
||||
```bash
|
||||
rm -rf <vcpkg-root>/buildtrees
|
||||
rm -rf <vcpkg-root>/downloads
|
||||
rm -rf <vcpkg-root>/installed
|
||||
rm -rf <vcpkg-root>/packages
|
||||
# CLI manifest mode; with CMake integration, use <build-directory>/vcpkg_installed (or VCPKG_INSTALLED_DIR)
|
||||
rm -rf ./vcpkg_installed
|
||||
```
|
||||
Reference in New Issue
Block a user