run-vcpkg GitHub Action

The run-vcpkg@v11 action sets up (and optionally runs) vcpkg to install packages specified in a vcpkg.json manifest file.

Key features include:

• Automatic Binary Caching: Leverages vcpkg's Binary Caching to store artifacts in the GitHub Action cache, ensuring packages are built only once. You can customize this via the VCPKG_BINARY_SOURCES environment variable.
• Log Collection: Automatically dumps CMake (e.g., CMakeOutput.log) and vcpkg logs into the workflow output. Use the logCollectionRegExps input to customize which logs are collected.
• Error Annotation: Automatically parses and reports errors from CMake, vcpkg, gcc, clang, and msvc as contextual annotations in the GitHub workflow summary.
• Executable Caching: Can cache the vcpkg executable and data files (disabled by default via doNotCache) to speed up runs, which is particularly useful on platforms like ARM where prebuilt binaries might not be served.

The run-vcpkg action follows a specific execution logic that can be customized via inputs. The flow generally follows these stages:

1. Environment Setup: Sets VCPKG_BINARY_SOURCES. If already defined, it is not overridden.
2. Caching (Optional): Computes a cache key from the vcpkg Git commit and platform/OS. If doNotCache is false, it attempts to restore vcpkg from GitHub cache.
3. vcpkg Fetching/Syncing: If vcpkg is not a submodule, it fetches it using vcpkgGitURL or the registry baseline in vcpkg-configuration.json/vcpkg.json. It then rebuilds the executable if out of sync.
4. Installation Logic:
   • If runVcpkgInstall: true: The action locates vcpkg.json (using vcpkgJsonGlob and vcpkgJsonIgnores) and explicitly launches vcpkg install.
   • If runVcpkgInstall: false: The action skips explicit installation and instead sets VCPKG_ROOT and VCPKG_DEFAULT_TRIPLET so that subsequent steps (like run-cmake) can trigger vcpkg via the CMake toolchain.
5. Post-Execution Caching: If no cache hit occurred, it stores vcpkg onto the GitHub cache (if doNotCache is false).

To use run-vcpkg effectively, it is highly recommended to use vcpkg as a Git submodule, use a vcpkg.json manifest file for dependencies, and use CMakePresets.json for project configuration.

Note that run-vcpkg is typically used to set up the environment, while run-cmake (a companion action) is used to actually trigger the build and dependency installation via the vcpkg toolchain.

jobs:
  build:
    steps:
      # 1. Install CMake and Ninja
      - uses: lukka/get-cmake@latest

      # 2. Setup vcpkg (does not build packages yet)
      - name: Setup vcpkg
        uses: lukka/run-vcpkg@v11
        # with:
        #   vcpkgDirectory: '${{ github.workspace }}/vcpkg'
        #   vcpkgGitCommitId: '...' # Only if NOT using a submodule

      # 3. Run CMake (this triggers vcpkg installation via toolchain)
      - name: Run CMake
        uses: lukka/run-cmake@v10
        with:
          configurePreset: 'ninja-multi-vcpkg'
          buildPreset: 'ninja-multi-vcpkg'
          testPreset: 'ninja-multi-vcpkg'

The following inputs and environment variables control the behavior of the run-vcpkg action logic.

Key Inputs:

• runVcpkgInstall: Boolean. If true, the action explicitly runs vcpkg install.
• vcpkgGitCommitId: The specific Git commit ID for vcpkg.
• vcpkgGitURL: The URL to fetch vcpkg from.
• vcpkgDirectory: The directory where vcpkg is located.
• vcpkgJsonGlob: Pattern to locate vcpkg.json.
• vcpkgJsonIgnores: Patterns to ignore when searching for vcpkg.json.
• doNotCache: If set to true, skips cache computation and storage.

Key Environment Variables:

• VCPKG_BINARY_SOURCES: Used for binary caching. If not set, it defaults to leveraging GitHub Action cache storage.
• VCPKG_DEFAULT_TRIPLET: If not set, it defaults to the current platform.
• VCPKG_INSTALLED_DIR: Used as the value for --x-install-root during vcpkg install.
• VCPKG_CONFIGURATION_JSON_IGNORE_PATTERNS: Semicolon-separated list of patterns to ignore for configuration files.

The run-vcpkg action accepts several inputs to control how vcpkg is installed, updated, and cached. Use these inputs in your GitHub Actions workflow file to customize the environment.

Core Configuration

• vcpkgDirectory: The root directory where vcpkg will be installed. If not provided, a default directory is used.
• vcpkgGitUrl: The URL of the vcpkg git repository. Defaults to https://github.com/microsoft/vcpkg.git.
• vcpkgGitCommitId: The specific git commit ID of vcpkg to use.
• doNotUpdateVcpkg: If set to true, the action will not attempt to update the vcpkg repository.
• runVcpkgInstall: If set to true, the action will run vcpkg install (useful when using vcpkg.json).

Caching and Binary Caching

• doNotCache: If set to true, the action will skip restoring and saving the vcpkg installation to the GitHub Actions cache. Set to false to enable caching.
• binaryCachePath: The path where vcpkg binary caching artifacts are stored. If not provided, a default directory is used. The action sets the environment variable VCPKG_DEFAULT_BINARY_CACHE to this path.
• additionalCachedPaths: Additional paths to include in the GitHub Actions cache.

Manifest and Globbing

• vcpkgJsonGlob: Glob pattern to find vcpkg.json files. Defaults to **/vcpkg.json.
• vcpkgJsonIgnores: A JSON-formatted array of glob patterns to ignore when searching for vcpkg.json (e.g., ['**/vcpkg/**']).
• vcpkgConfigurationJsonGlob: Glob pattern for vcpkg-configuration.json files.

Logging

• runVcpkgFormatString: A format string used during the vcpkg run.
• logCollectionRegExps: A delimited list (using ;) of regular expressions used to collect logs.