diff --git a/skills/vcpkg/SKILL.md b/skills/vcpkg/SKILL.md index 313a7453..606e86eb 100644 --- a/skills/vcpkg/SKILL.md +++ b/skills/vcpkg/SKILL.md @@ -38,6 +38,12 @@ If the user is working inside **Visual Studio** (not VS Code), prefer using the 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 @@ -128,18 +134,10 @@ 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 +cmake -B build -DVCPKG_TARGET_TRIPLET=x64-linux -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake ``` -Or set the environment variable: - -```powershell -$env:VCPKG_DEFAULT_TRIPLET = "x64-linux" -``` - -```bash -export VCPKG_DEFAULT_TRIPLET=x64-linux -``` +Or set the default triplet via environment variable (using the shell syntax above): `VCPKG_DEFAULT_TRIPLET=x64-linux`. ### Bulk-Adding Multiple Dependencies @@ -162,13 +160,9 @@ Then run `vcpkg install` (manifest mode) or the above command to install all at 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": [ - "fmt", - "spdlog" - ], + "dependencies": ["fmt"], "features": { "tests": { - "description": "Build tests", "dependencies": ["gtest"] } } @@ -183,40 +177,30 @@ Activate with: `vcpkg install --x-feature=tests` or in CMake: `-DVCPKG_MANIFEST_ ### Setting Versions for Individual Dependencies -In `vcpkg.json`, prefer using `"version>="` as a minimum version constraint over overrides. Example: +Prefer `"version>="` for minimum-version constraints: ```json { - "dependencies": [ - { - "name": "fmt", - "version>=": "10.2.0" - } - ], + "dependencies": [{ "name": "fmt", "version>=": "10.2.0" }], "builtin-baseline": "" } ``` -If the user insists on hard-coding a version and is okay dealing with ABI compatibility issues manually, use overrides instead: +Use `overrides` only when a hard pin is required: ```json { "dependencies": ["fmt"], - "overrides": [ - { - "name": "fmt", - "version": "10.2.0" - } - ], + "overrides": [{ "name": "fmt", "version": "10.2.0" }], "builtin-baseline": "" } ``` -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. +Always include `builtin-baseline` when using versioning. **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 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 +- `overrides` take precedence over all version constraints, including transitive ones. +- `builtin-baseline` is required for overrides. +- Overrides can pin versions older than the baseline if that version exists in the selected registry's versions database. +- Use `vcpkg x-history ` to inspect available versions. --- @@ -229,12 +213,8 @@ vcpkg install :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 +```console +cmake -B build -DVCPKG_TARGET_TRIPLET=arm64-linux -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake ``` You may need a cross-compilation toolchain installed (e.g., `aarch64-linux-gnu-gcc`). @@ -246,39 +226,16 @@ vcpkg install :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: +1. Install packages: ```console vcpkg install :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 +2. In CMake: +```console +cmake -B build -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=arm64-android -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=/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 \ - -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \ - -DANDROID_ABI=arm64-v8a \ - -DANDROID_PLATFORM=android-24 -``` +For expanded CI and shell-specific examples, see `references/ci.md`. diff --git a/skills/vcpkg/references/ci.md b/skills/vcpkg/references/ci.md index 403ad4d0..b997c44c 100644 --- a/skills/vcpkg/references/ci.md +++ b/skills/vcpkg/references/ci.md @@ -21,6 +21,18 @@ $env:VCPKG_BINARY_SOURCES = "clear;nuget,https://nuget.pkg.github.com/your-org/i ```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 @@ -30,21 +42,7 @@ $env:VCPKG_BINARY_SOURCES = "clear;files,C:\vcpkg-cache,readwrite" 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) -$env:VCPKG_BINARY_SOURCES = "clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$env:AZURE_STORAGE_SAS_TOKEN,readwrite" - -# Developer (reads cache) -$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" -``` +**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`. --- diff --git a/skills/vcpkg/references/troubleshooting.md b/skills/vcpkg/references/troubleshooting.md index 497669cd..3e70ba40 100644 --- a/skills/vcpkg/references/troubleshooting.md +++ b/skills/vcpkg/references/troubleshooting.md @@ -76,35 +76,17 @@ vcpkg install curl[ssl,ssh] --recurse # permits rebuilding with the new featur ### Cleaning the vcpkg Cache ```powershell -# Remove build trees (intermediate build files) -Remove-Item -Recurse -Force \buildtrees - -# Remove downloaded archives -Remove-Item -Recurse -Force \downloads - -# Remove installed packages (classic mode only) -Remove-Item -Recurse -Force \installed - # Remove all package build artifacts vcpkg x-clean -# In manifest mode, remove the local vcpkg_installed directory -Remove-Item -Recurse -Force .\vcpkg_installed +# Optional: remove local cache/install directories +Remove-Item -Recurse -Force \buildtrees,\downloads,\installed,.\vcpkg_installed ``` ```bash -# Remove build trees (intermediate build files) -rm -rf /buildtrees - -# Remove downloaded archives -rm -rf /downloads - -# Remove installed packages (classic mode only) -rm -rf /installed - # Remove all package build artifacts vcpkg x-clean -# In manifest mode, remove the local vcpkg_installed directory -rm -rf vcpkg_installed/ +# Optional: remove local cache/install directories +rm -rf /buildtrees /downloads /installed ./vcpkg_installed ```