README.md

The run-vcpkg action for caching artifacts and using vcpkg on GitHub

The run-vcpkg action restores from cache vcpkg along with the previously installed ports. Briefly:

• If there is a cache miss, vpckg is fetched and installed; the cache's key is composed by hashing the hosting OS name, the command line arguments and the vcpkg's commit id.
  • Restoring from cache can be skipped with doNotCache:true.
• Then vcpkg is run to install the desired ports. This is a no-op if artifacts are already restored.
  • This step can be skipped with setupOnly:true.
• Artifacts and vcpkg are then saved in cache (if it was a 'cache miss').
  • Saving to cache can be skipped with doNotCache:true.

The provided samples use GitHub hosted runners.

Good companions are the run-cmake action and the get-cmake actions.

User Manual

• Contributing
• Quickstart
  • Restore cache/install/create cache
  • Restore cache/do not install/create cache
  • Flowchart
• Best practices
  • Use vcpkg as a submodule of your repository
  • Use vcpkg's response file as an argument
• Action reference: all input/output parameters
• Samples
• Projects

Contributing

Read CONTRIBUTING.md

Quickstart

Setup vcpkg and install ports

It is highly recommended to use vcpkg as a submodule. Here below the sample where vcpkg is a Git submodule:

  # Sample when vcpkg is a submodule of your repository (highly recommended!)

    #-uses: actions/cache@v1   <===== YOU DO NOT NEED THIS!

    # Install latest CMake.
    - uses: lukka/get-cmake@latest

    # Restore from cache the previously built ports. If "cache miss", then provision vcpkg, install desired ports, finally cache everything for the next run.
    - name: Restore from cache and run vcpkg
      uses: lukka/run-vcpkg@v5
      with:
        # Response file stored in source control, it provides the list of ports and triplet(s).
        vcpkgArguments: '@${{ env.vcpkgResponseFile }}'
        # Location of the vcpkg as submodule of the repository.
        vcpkgDirectory: '${{ github.workspace }}/vcpkg'
        # Since the cache must be invalidated when content of the response file changes, let's
        # compute its hash and append this to the computed cache's key.
        appendedCacheKey: ${{ hashFiles(env.vcpkgResponseFile) }}

    - name: 'Build with CMake and Ninja'
      uses: lukka/run-cmake@v3
      with:
        cmakeListsOrSettingsJson: CMakeListsTxtAdvanced
        cmakeListsTxtPath: '${{ github.workspace }}/cmakesettings.json/CMakeLists.txt'
        useVcpkgToolchainFile: true
        buildDirectory: '${{ runner.workspace }}/b/ninja'
        cmakeAppendedArgs: '-GNinja Multi-Config'
        # Or build multiple configurations out of a CMakeSettings.json file created with Visual Studio.
        # cmakeListsOrSettingsJson: CMakeSettingsJson
        # cmakeSettingsJsonPath: '${{ github.workspace }}/cmakesettings.json/CMakeSettings.json'
        # configurationRegexFilter: '${{ matrix.configuration }}'

Setup vcpkg only

When setupOnly: true, it only setups vcpkg and set VCPKG_ROOT environment variable without installing any port. The provisioned vcpkg can then be used as follows in a subsequent step:

    # Restore from cache the previously built ports. If cache-miss, download, build vcpkg.
    - name: Restore from cache and install vcpkg
      # Download and build vcpkg, without installing any port. If content is cached already, it is a no-op.
      uses: lukka/run-vcpkg@v5
      with:
        setupOnly: true
    # Now that vcpkg is installed, it is being used to run desired arguments.
    - run: |
        $VCPKG_ROOT/vcpkg @$vcpkgResponseFile
        $VCPKG_ROOT/vcpkg install boost:linux-x64
      shell: bash

Flowchart

Action reference: all input/output parameters

action.yml

Best practices

Use vcpkg as a submodule of your repository

When using vcpkg, be aware of how it works, specifically:

• a specific version of vcpkg must be used either locally and on build servers;
• a specific version of vcpkg is identified by the commit id of the used vcpkg repository;
• it not possible to choose which version of a port to install, instead it is the used version of vcpkg that establishes which version (just one) of a port is available;

To sum up, you need to pin the specific version of vcpkg you want to use to keep a consistent development experience between local and remote build environments. This is accomplished by using vcpkg as submodule of your Git repository; this way the version of vcpkg used is implied by the commit id specified by the submodule for vcpkg.

Use vcpkg's response file as an argument

vcpkg accepts a response file that contains the arguments, suitable to store the list of ports to be installed. It is useful to store the response file under source control, this helps to run vcpkg the same exact way locally and remotely on the build servers. For example if you want to run:

vcpkg install boost zlib:x64 libmodbus --triplet x64

it is instead possible to run

vcpkg install @response_file.txt

where response_file.txt contains (with no trailing whitespaces allowed):

   boost
   zlib:x64
   libmodbus
   --triplet
   x64

Samples

View the workflows based on the run-cmake and run-vcpkg actions.

CMakeLists.txt samples
Linux/macOS/Windows, hosted runner, basic
Linux/macOS/Windows, hosted runner, advanced
Linux/macOS/Windows, hosted runner, vcpkg as submodule
Linux/macOS/Windows, hosted runner, setup only and vcpkg as submodule

CMakeSettings.json samples
Linux/macOS/Windows, hosted runner, with vcpkg as submodule

Real world project samples

Project	Platform(s)
CppOpenGLWebAssemblyCMake	WASM/Linux/macOS
codehz/wine-bdlauncher	Windows
OPM/ResInsight	Windows/Linux
Mudlet/Mudlet	Linux/macOS
otland/forgottenserver	Linux/macOS/Windows
Element-0/ElementZero	Windows
zealdocs/zeal	Linux/Windows
libevent/libevent	Windows/macos/Linux
marian-nmt/marian-dev	Windows/Linux/macOS
GrinPlusPlus	Linux/Windows/macOS

License

All the content in this repository is licensed under the MIT License.

Copyright (c) 2019-2020 Luca Cappa

Donating

Other than submitting a pull request, donating is another way to contribute to this project.