- Quickstart with a C++ project template
- run-cmake@v10 runs CMake with CMakePresets.json
- License
- Disclaimer
- Contributing
Take a look at this C++ project template that applies all the following instructions and also shows how to create a pure workflow without using special GitHub action that you cannot run locally on your development machine, but directly using the tools (CMake, Ninja, vcpkg, C++ compilers) you already use daily.
The run-cmake action runs CMake on GitHub workflows leveraging CMakePresets.json.
Good companions are the run-vcpkg action and the get-cmake action.
Special features which provide added value over a pure workflow are:
- annotations for
CMakeerrors/warnings and for build (gcc/msvc/clang) errors/warnings are created inline in the changed source files the build run for, e.g.:
- when necessary, it sets up the environment to build with the
MSVCtoolset. - automatic dump of log files created by
CMake(e.g.,CMakeOutput.log) andvcpkg. The content of those files flow into the workflow output log. The regex is customizable by the user.
The provided samples use GitHub hosted runners.
It is highly recommended to use:
- a vcpkg.json manifest file to declaratively specify the dependencies.
- a CMakePresets.json file.
- vcpkg as a submodule of your repository.
jobs:
build:
steps:
#-uses: actions/cache@v3 <===== YOU DO NOT NEED THIS!
# Install latest CMake and Ninja.
- uses: lukka/get-cmake@latest
# Or pin to a specific CMake version:
# lukka/get-cmake@v3.21.2
# Restore from cache the previously built ports. If a "cache miss" occurs,
# then vcpkg is bootstrapped. Since a the vcpkg.json is being used later on
# to install the packages when `run-cmake` runs, no packages are installed at
# this time.
- name: Restore artifacts, or setup vcpkg (do not install any package)
uses: lukka/run-vcpkg@v10 # Always specify the specific _version_ of the
# action you need, `v10` in this case to stay up
# to date with fixes on the v10 branch.
#with:
# This is the default location of the directory containing vcpkg sources.
# Change it to the right location if needed.
# vcpkgDirectory: '${{ github.workspace }}/vcpkg'
# If not using a submodule for vcpkg sources, this specifies which commit
# id must be checkout from a Git repo. It must not set if using a submodule
# for vcpkg.
# vcpkgGitCommitId: '${{ matrix.vcpkgCommitId }}'
# This is the glob expression used to locate the vpkg.json and add its
# hash to the cache key. Change it to match a single manifest file you want
# to use.
# vcpkgJsonGlob: '**/vcpkg.json'
# This is needed to run `vcpkg install` command (after vcpkg is built) in
# the directory where vcpkg.json has been located. Default is false,
# It is highly suggested to let `run-cmake` to run vcpkg (i.e. `false`)
# (i.e. let CMake run `vcpkg install`) using the vcpkg.cmake toolchain.
# runVcpkgInstall: true
- name: Run CMake consuming CMakePresets.json and vcpkg.json by mean of vcpkg.
uses: lukka/run-cmake@v10
with:
# This is the default path to the CMakeLists.txt along side the
# CMakePresets.json. Change if you need have CMakeLists.txt and CMakePresets.json
# located elsewhere.
# cmakeListsTxtPath: '${{ github.workspace }}/CMakeLists.txt'
# This is the name of the CMakePresets.json's configuration to use to generate
# the project files. This configuration leverages the vcpkg.cmake toolchain file to
# run vcpkg and install all dependencies specified in vcpkg.json.
configurePreset: 'ninja-multi-vcpkg'
# Additional arguments can be appended to the cmake command.
# This is useful to reduce the number of CMake's Presets since you can reuse
# an existing preset with different variables.
configurePresetAdditionalArgs: ['-DENABLE_YOUR_FEATURE=1']
# This is the name of the CMakePresets.json's configuration to build the project.
buildPreset: 'ninja-multi-vcpkg'
# Additional arguments can be appended when building, for example to specify the
# configuration to build.
# This is useful to reduce the number of CMake's Presets you need in CMakePresets.json.
buildPresetAdditionalArgs: ['--config Release']
# This is the name of the CMakePresets.json's configuration to test the project with.
testPreset: 'ninja-multi-vcpkg'
# Additional arguments can be appended when testing, for example to specify the config
# to test.
# This is useful to reduce the number of CMake's Presets you need in CMakePresets.json.
testPresetAdditionalArgs: ['--config Release']
#env:
# VCPKG_DEFAULT_TRIPLET: ${{ matrix.triplet }} # [OPTIONAL] Define the vcpkg's triplet
# you want to enforce, otherwise the default one for the hosting system will be
# automatically choosen (x64 is the default on all platforms, e.g. x64-osx).Description of all input parameters: action.yml
Flowchart with related input in action.yml which let customize the flow.
┌───────────────────────────┐ ┌───────────────────────────┐
│ <if configurePreset │ Yes │ <if VCPKG_ROOT defined │ Inputs:
│ provided> ├─────►│ and CC and CXX undefined> │ - `runVcpkgEnvFormatString`
└─────────────┬─────────────┘ │ run `vcpkg env` to set │ - `configurePresetAdditionalArgs`
│ No │ the environment for MSVC │
│ └─────────────┬─────────────┘
│ ▼
│ ┌───────────────────────────┐
│ │ $CONFIGURE_PRESET_NAME = │
│ │ configurePreset's value │
│ └─────────────┬─────────────┘
│ ▼
│ ┌───────────────────────────┐ Inputs:
├────────────────────┤ run `cmake --preset` │ - `cmakeListsTxtPath`
│ └───────────────────────────┘ - `configurePreset`
│ - `configurePresetCmdString`
│
▼
┌───────────────────────────────────┐
│ <if buildPreset provided> │ Inputs:
│ │ - `buildPreset`
│ $BUILD_PRESET_NAME=buildPreset │ - `cmakeListsTxtPath`
│ run: `cmake --build --preset` │ - `buildPresetCmdString`
└─────────────┬─────────────────────┘ - `buildPresetAdditionalArgs`
│
▼
┌───────────────────────────────────┐
│ <if testPreset provided> │ Inputs:
│ │ - `testPreset`
│ $TEST_PRESET_NAME=testPreset │ - `cmakeListsTxtPath`
│ run a`ctest --preset` │ - `testPresetCmdString`
└─────────────┬─────────────────────┘ - `testPresetAdditionalArgs`
│
▼
⬬
Checkmarks indicates whether the samples "uses" or specifies the thing in the header or whether it is true.
| workflow link | vcpkg as submodule |
explicit triplet | vcpkg toolchain |
CMake's Presets |
Ninja |
run-vcpkg runs vcpkg |
CMake runs vcpkg |
|---|---|---|---|---|---|---|---|
| link | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ |
| link | ❌ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ |
| link | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| link | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
This graph shows the list of public repositories with more than 25 stars using run-cmake.
All the content in this repository is licensed under the MIT License.
Copyright © 2019-2020-2021-2022 Luca Cappa
The software is provided as is, there is no warranty of any kind. All users are encouraged to improve the source code with fixes and new features.
Read CONTRIBUTING.md