CMake Workflow

This action runs a complete CMake workflow from source files. A workflow is composed of the following steps:

  • Configure

  • Build

  • Test

  • Install

The action also sets up the environment for the workflow:

  • It validates the CMake version installed in the system,

  • Updates CMake if the library has a different minimum version,

  • Identifies what features the current CMake version supports, and

  • Runs a complete cmake workflow

The action will adjusts the parameters as needed according to the features that CMake version supports. For instance,

  • If the CMake version does not support the -S …​ -B …​ syntax, the action will create the build directory and run the configuration step from there.

  • If the specified or default generator is multi-config, CMAKE_CONFIGURATION_TYPES will be used instead of CMAKE_BUILD_TYPE, since the later is ignored by these generators.

  • If the CMake version does not support the cmake --install syntax, the cmake --build --target install will be use instead.

  • If the CMake version does not support multiple targets in the cmake --build syntax, the action will run the build step once for each target.

The action also creates GitHub annotations when warnings or errors are emitted at any of these steps. This includes annotations for CMake errors at the configure step and build errors emitted from the compiler at the build step.

Examples

Example 1:

steps:
- name: CMake Workflow
  uses: alandefreitas/cpp-actions/cmake-workflow@master
  with:
    cmake-version: '>=3.20'
    source-dir: tests
    toolchain: ${{ steps.package-install.outputs.vcpkg-toolchain }}
    run-tests: 'true'
    install-prefix: $GITHUB_WORKSPACE/.local
    cxxstd: 17,20
    cc: ${{ steps.setup-gcc.outputs.cc || steps.setup-clang.outputs.cc || 'gcc-13'
      }}
    cxx: ${{ steps.setup-gcc.outputs.cxx || steps.setup-clang.outputs.cxx || 'g++-13'
      }}
    extra-args: -D BOOST_SRC_DIR=$GITHUB_WORKSPACE/boost-root
    ref-source-dir: .

Example 2 (cxxflags):

steps:
- name: CMake Workflow
  uses: alandefreitas/cpp-actions/cmake-workflow@master
  with:
    cmake-version: '>=3.20'
    source-dir: tests
    toolchain: ${{ steps.package-install.outputs.vcpkg-toolchain }}
    run-tests: 'true'
    install-prefix: $GITHUB_WORKSPACE/.local
    cxxstd: 17,20
    cc: ${{ steps.setup-gcc.outputs.cc || steps.setup-clang.outputs.cc || 'gcc-13'
      }}
    cxx: ${{ steps.setup-gcc.outputs.cxx || steps.setup-clang.outputs.cxx || 'g++-13'
      }}
    cxxflags: -fsanitize=undefined
    extra-args: -D BOOST_SRC_DIR=$GITHUB_WORKSPACE/boost-root
    ref-source-dir: .

Example 3 (build-type, generator):

steps:
- name: CMake Workflow
  uses: alandefreitas/cpp-actions/cmake-workflow@master
  with:
    cmake-version: '>=3.20'
    source-dir: tests
    generator: Unix Makefiles
    toolchain: ${{ steps.package-install.outputs.vcpkg-toolchain }}
    build-type: Debug
    run-tests: 'true'
    install-prefix: $GITHUB_WORKSPACE/.local
    cc: ${{ steps.setup-gcc.outputs.cc || steps.setup-clang.outputs.cc || '' }}
    cxx: ${{ steps.setup-gcc.outputs.cxx || steps.setup-clang.outputs.cxx || '' }}
    extra-args: -D BOOST_SRC_DIR=$GITHUB_WORKSPACE/boost-root
    ref-source-dir: .

Input Parameters

Parameter

Description

Default

cmake-path

The cmake executable.

cmake

cmake-version

A semver range string with the cmake versions supported by this workflow.

If the existing version in the environment does not satisfy this requirement, the action install the min CMake version that satisfies it.

This should usually match the cmake_minimum_required defined in your CMakeLists.txt file. .

source-dir

Directory for the source files.

.

build-dir

Directory for the binaries relative to the source directory.

build

cc

Path to C compiler.

cxx

Path to C++ compiler.

cxxstd

List of standards with which cmake will build and test the program.

cxxflags

Force flags to be used with the C++ compiler.

toolchain

Path to toolchain.

generator

Generator name.

build-type

Build type.

Release

build-target

Targets to build instead of the default target.

install-prefix

Path where the library should be installed.

.local/usr

extra-args

Extra arguments to cmake configure command.

run-tests

Whether we should run tests.

true

install

Whether we should install the library.

The library is only installed once in the install-prefix.

The latest std version described in cxxstd is used for the installed version. .

true

create-annotations

Create github annotations on errors.

true

ref-source-dir

A reference source directory for annotations. Any annotation filename will be relative to this directory.

This is typically useful when the repository being tested is not the current directory, in which we need to make annotations relative to some other directory.

In most cases, the default option should be enough. .

.

trace-commands

Trace commands executed by the workflow.

false