DOCSEARCHbyAlgolia
Submit Docs

vcpkg C/C++ Package Manager

repository·master·Indexed 12 days ago

https://github.com/microsoft/vcpkg

A cross-platform, open-source C/C++ package manager maintained by Microsoft and the community. It simplifies dependency management for Windows, macOS, and Linux, integrating with build systems like CMake and MSBuild. Supports both Manifest mode for reproducible builds and Classic mode for global package management.

Tokens
5.1K
Snippets
16
Records
27
Agent score
97%

What's inside vcpkg

  1. Overview of vcpkg

    master
    vcpkg is a free and open-source C/C++ package manager maintained by Microsoft and the C++ community. It is a cross-platform tool designed for Windows, macOS, and Linux that supports various build and project systems. It is written in C++ and uses CMake for scripting.

  2. How the ANGLE vcpkg port buildsystem works

    master
    The ANGLE port uses a buildsystem derived from WebKit's approach to converting ANGLE's buildsystem to CMake. It consists of an augmented version of WebKit's CMakeLists.txt and customized configuration files located in cmake-buildsystem/. These configuration files are adapted for vcpkg and use PlatformLinux instead of PlatformGTK.

  3. Understand the Owners DB output file formats

    master

    Both file_script.ts and file_script_from_cache.ts produce two specific plain-text database files in the specified --out-dir (default scripts/list_files).

    VCPKGDatabase.txt

    A newline-separated list of all files in the packages.

    • Format: <port>:<triplet>:<filepath>
    • Example: zlib:x64-windows:/share/zlib/include/zlib.h
    • Note: <filepath> always begins with a leading /.

    VCPKGHeadersDatabase.txt

    A filtered list containing only header files.

    • Format: <port>:<triplet>:<relative/header/path>
    • Filtering Logic: Only files whose path starts with /include/ are recorded. The /include/ prefix is stripped from the resulting path.
    • Example: An entry for /include/zlib.h becomes zlib:x64-windows:zlib.h.

  4. Update the ANGLE vcpkg port

    master

    To update the ANGLE port to a new version, follow these steps:

    1. Select a new ANGLE version: Follow the libANGLE guide for matching a branch to the current Chromium Stable.
    2. Update version metadata: Find the branch (typically chromium/<version>) and the latest commit. Update ANGLE_COMMIT, ANGLE_VERSION, and ANGLE_SHA512 in portfile.cmake.
    3. Sync third-party dependencies: Check the DEPS file at the selected ANGLE commit for the third_party/zlib commit. Update ANGLE_THIRDPARTY_ZLIB_COMMIT in portfile.cmake if it has changed.
    4. Build and adjust: Attempt a build. You may need to modify CMakeLists.txt or Platform*.cmake files. Compare these with the latest files in the WebKit repository to port any necessary updates. You may also need to update ANGLE_WEBKIT_BUILDSYSTEM_COMMIT in the portfile.cmake.
    5. Verify headers: Compare ANGLE headers against opengl-registry to ensure similarity. Note that ANGLE defines some additional entrypoints. Ensure opengl-registry is updated to the latest version before updating ANGLE.
    6. Finalize: Complete the standard maintenance steps defined in the vcpkg Maintainer Guide.

  5. Guidelines for contributing new packages

    master

    When creating a new port file for a package, follow these best practices to ensure maintainability:

    • Minimize Patches: Avoid using patches to add features. Patches should only be used as a last resort to ensure compatibility.
    • Preserve Default Behavior: If a patch is unavoidable, do not modify the library's default behavior. The goal is for the patch to eventually be merged upstream so it is no longer needed in vcpkg.
    • Use vcpkg Helper Functions: Prefer using built-in vcpkg_xyz functions over raw execute_command calls. This makes it easier to maintain the port when new features (like custom compiler flags or generators) are added to vcpkg.

  8. Configure guest environment and Xcode for macOS VMs

    master

    Once the macOS VM is running, you must configure the vcpkg user to allow seamless automation. This includes setting up passwordless sudo, installing Xcode, and preparing the Azure Agent.

    Steps to configure the guest:

    1. Passwordless Sudo: Create a sudoers file for the vcpkg user.
    2. Xcode Installation: Expand the .xip and move Xcode.app to /Applications.
    3. Azure Agent Setup: Update setup-box.sh with the correct Azure Agent URI and run the setup scripts (setup-guest.sh and setup-box.sh) using clt.dmg (renamed from tools.dmg).

    Note: When opening Xcode for the first time, uncheck the "code completion model" and accept the EULA.

    # Configure passwordless sudo
printf 'vcpkg\tALL=(ALL)\tNOPASSWD:\tALL\n' | sudo tee -a '/etc/sudoers.d/vcpkg'
sudo chmod 0440 '/etc/sudoers.d/vcpkg'

# Expand and install Xcode
sudo mdutil -ad
xip --expand Xcode.xip
sudo mv Xcode.app /Applications/Xcode.app
rm Xcode.xip

  9. Create new vcpkg-eg-mac ARM64 base images

    master

    Use this checklist to update or create new macOS ARM64 base images for the vcpkg agent pool. This process involves preparing a host machine, minting a new VM using macosvm with a macOS .ipsw file, configuring the guest environment (Xcode, sudo permissions, Azure Agent URI), and uploading the resulting archive to blob storage.

    Prerequisites

    • macosvm allow-listed by macOS for arm64.
    • Xcode .xip and Xcode Command Line Tools installer.
    • PowerShell 7.x, Azure CLI, and az login with Microsoft credentials.

    High-level Workflow

    1. Prepare Host: Delete an idle agent from the Azure DevOps OSX queue and access the machine via KVM.
    2. Install macosvm: Install the macosvm tool to the home directory.
    3. Initialize VM: Create a directory in ~/Parallels/vcpkg-osx-<date>-arm64 and use macosvm to create the disk and restore from a .ipsw file.
    4. Configure Guest: Follow macOS setup prompts (Account: vcpkg), disable automatic updates, enable Remote Login, and configure passwordless sudo for the vcpkg user.
    5. Install Tooling: Install Xcode via .xip expansion and update setup-box.sh with the current Azure Agent URI.
    6. Package & Upload: Archive the VM using aa archive and upload the .aar file to the vcpkgimageminting storage account using azcopy.
    # Create the VM directory and run macosvm
mkdir -p ~/Parallels/vcpkg-osx-2026-01-12-arm64
cd ~/Parallels/vcpkg-osx-2026-01-12-arm64
~/macosvm --disk disk.img,size=500g --aux aux.img -c 8 -r 12g --restore ~/UniversalMac_26.4.1_25E253_Restore.ipsw ./vm.json
~/macosvm -g ./vm.json

  11. Perform Patch Tuesday maintenance tasks

    master

    During each Patch Tuesday cycle, follow these steps to maintain the Windows and macOS images used for validation:

    Windows Image Maintenance

    1. Check Dependencies: Review depends:vm-update Pull Requests and apply necessary changes.
    2. Monitor Security Alerts: Check Service 360 alerts (e.g., at https://aka.ms/s360) for the service "C++ VCPKG Validation" to identify vulnerable software (often requiring PowerShell updates).
    3. Update Software: Check for any other software updates required for Windows images and apply edits in scripts/azure-pipelines/windows.
    4. Update Tools: Check for available updates to vcpkg-tools.json.
    5. Create Image: Run the image creation script:
      windows/create-image.ps1
    6. Finalize: Submit and merge a PR with your changes, then mark the newly created image as 'latest' in the Azure portal.

    macOS Image Maintenance

    1. Mint Base Box: Mint a new macOS base box by following the instructions in scripts/azure-pipelines/osx/README.md.
    2. Deploy: Deploy the new base box to all hosts.
    windows/create-image.ps1

  12. First time machine setup for vcpkg validation

    master

    To set up a machine for the first time to perform vcpkg validation tasks, complete the following steps:

    1. Install Azure PowerShell: Follow the official Microsoft documentation to install the Azure PowerShell module.
    2. Authenticate with Azure: Run the connection command to authenticate against the specific subscription.
    3. Install Docker: Ensure Docker is installed on the machine to support containerized workflows.
    Connect-AzAccount -Subscription CPP_GITHUB