CMake Workflow

This action runs a complete CMake workflow from source files.

This is usually the next step in your workflow after setting up a C++ compiler and fetching dependencies with Install Packages.

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.

Next steps

After running the a complete CMake workflow for your project, the next step in your workflow should usually be the generation of reports, with tools such as the Create Flamegraph (when matrix.time-trace) and Create Changelog (usually in another workflow job). You can also include customs steps to upload coverage reports (when matrix.coverage).

If your project provides CMake installation and configuration scripts, it is also usual to include multiple CMake workflow steps as integration tests for CMake.

Example

steps:
- name: CMake Workflow
  uses: alandefreitas/cpp-actions/cmake-workflow@v1.6.1
  with:
    cmake-version: '>=3.20'
    source-dir: tests
    generator: ${{ matrix.generator }}
    toolchain: ${{ steps.package-install.outputs.vcpkg-toolchain }}
    build-type: ${{ matrix.build-type }}
    run-tests: true
    install-prefix: $GITHUB_WORKSPACE/.local
    cxxstd: ${{ matrix.cxxstd }}
    cc: ${{ steps.setup-cpp.outputs.cc || matrix.cc }}
    ccflags: ${{ matrix.ccflags }}
    cxx: ${{ steps.setup-cpp.outputs.cxx || matrix.cxx }}
    cxxflags: ${{ matrix.cxxflags }}
    shared: ${{ matrix.shared }}
    extra-args: ${{ ( !matrix.no-deps && format('-D BOOST_SRC_DIR="{0}"', steps.boost-clone.outputs.boost-dir)
      ) || '' }} ${{ ( matrix.no-deps && '-D CPP_ACTIONS_NO_DEPS=ON' ) || '' }}
    export-compile-commands: ${{ matrix.time-trace }}
    package: true
    package-artifact: ${{ matrix.is-main }}
    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.

ccflags

Flags to be used with the C compiler.

cxx

Path to C++ compiler.

cxxstd

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

cxxflags

Flags to be used with the C++ compiler.

shared

Determines if add_library should create shared libraries (BUILD_SHARED_LIBS).

false

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.

export-compile-commands

Set CMAKE_EXPORT_COMPILE_COMMANDS=ON.

false

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

package

Run cpack with the specified generators after the install step.

false

package-name

The name of the package (or application). If not specified, it defaults to the project name.

package-dir

The directory in which the packages are generated by cpack.

If it is not set then this will default to the build dir.

The CPACK_PACKAGE_DIRECTORY may be defined in CMakeLists.txt, a CPack config file or from the cpack command line option -B.

If set, the command line option overrides the value found in the config file.

package-vendor

Override/define CPACK_PACKAGE_VENDOR.

package-generators

A semicolon-separated list of generator names used by cpack.

If this variable is not set, the action will attempt to generate the package with all cpack generators available to CMake.

package-artifact

Whether the packages generated with cpack should be stored as action artifacts.

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