ghaction-cmake

ghaction-cmake是一个用于使用CMake的项目的GitHub Action。默认情况下，它构建、测试和安装项目——但通过使用预设，它可以轻松运行代码检查工具、覆盖率测试、Valgrind内存检查或sanitizers等。

阶段

ghaction-cmake按阶段运行：

setup（设置）：可选地安装依赖项并进入指定目录。
cmake：在空目录中运行cmake，指向源目录，并附加所有其他参数。这确保树外构建（out-of-tree builds）正常工作。
build（构建）：可自定义，默认是make VERBOSE=1（显示构建命令）。
test（测试）：可自定义，默认是ctest --output-on-failure .。
post（后置）：可自定义，默认为空。

输入参数

`preset`

设置预设，详见下方预设部分。

阶段：可更改任意数量阶段的默认命令。

`dependencies_debian`

要在容器中安装的项目依赖项（Debian包），以空格分隔。

阶段：setup
预设行为：不受影响。

`working-directory`

将此目录用作cmake的源目录。主要用于CMake项目位于仓库子目录中的情况。

阶段：setup
预设行为：不受影响。

`cmakeflags`

传递给cmake的标志。例如-DSOME_OPTION=On，用于向CMakeLists.txt传递选项。

阶段：cmake
预设行为：大多数预设会附加到此输入。

`build_command`

自定义构建命令。默认是make VERBOSE=1。

阶段：build
预设行为：部分预设会更改或移除默认构建命令。

`test_command`

自定义测试命令。未使用预设时，默认是ctest --output-on-failure .。

阶段：test
预设行为：部分预设会更改或移除默认测试命令。

`post_command`

测试后运行的自定义命令。未使用预设时，默认为空。

阶段：post
预设行为：部分预设会添加默认后置命令。

预设

cmake是一个非常通用的工具，给定适当的参数可以完成多种不同任务。为了简化矩阵构建（matrix builds），ghaction-cmake提供预设，用于为特定模式配置这些选项。

可用的预设包括：

cppcheck：运行cppcheck静态分析。
- cmake：向cmakeflags附加-DCMAKE_C/CXX_CPPCHECK=cppcheck。
- test：清除默认值。
iwyu：运行include-what-you-use静态分析。
- cmake：向cmakeflags附加-DCMAKE_C/CXX_INCLUDE_WHAT_YOU_USE=iwyu。
- test：清除默认值。
install：测试安装。
- cmake：向cmakeflags附加'-DCMAKE_INSTALL_PREFIX'。
- test：使用make install作为测试。
- post：使用find显示所有已安装文件。
clang-tidy：运行clang-tidy静态分析。
- cmake：向cmakeflags附加-DCMAKE_C/CXX_CLANG_TIDY=clang-tidy。
- test：清除默认值。
clang-sanitize-<sanitizer>：使用Clang sanitizers之一编译并运行测试。
- cmake：向cmakeflags附加-DCMAKE_C/CXX_COMPILER=clang/clang++ -DCMAKE_C/CXX_FLAGS=-fno-omit-frame-pointer -fsanitize=<sanitizer>。
valgrind：使用Valgrind运行测试。
- test：将默认测试阶段设置为ctest -DExperimentalMemCheck --output-on-failure .。
coverage：运行覆盖率测试。
- cmake：向cmakeflags附加-DCMAKE_C/CXX_FLAGS=--coverage。
- post：将默认后置阶段设置为运行lcov，命令为lcov -c -d . -o lcov.info。
此预设可与上传覆盖率数据到在线服务（如codecov和coveralls）的GitHub Action配合使用。下方示例展示了如何实现。

下表总结了各预设的具体更改：

预设	cmake	test	post
cppcheck	-DCMAKE_C/CXX_CPPCHECK=cppcheck	(删除)
iwyu	-DCMAKE_C/CXX_INCLUDE_WHAT_YOU_USE=iwyu	(删除)
install	-DCMAKE_INSTALL_PREFIX=/tmp/_install	make install	find /tmp_install -type f
clang-tidy	-DCMAKE_C/CXX_CLANG_TIDY=clang-tidy	(删除)
clang-sanitize-<sanitizer>	-DCMAKE_C/CXX_COMPILER=clang/clang++ -DCMAKE_C/CXX_FLAGS=-fno-omit-frame-pointer -fsanitize=<sanitizer>
valgrind		-DExperimentalMemCheck
coverage	-DCMAKE_C/CXX_FLAGS=--coverage		lcov -c -d . -o lcov.info

请注意，预设会覆盖默认值，而其他更具体的输入（build_command、test_command、post_command）会覆盖预设。

示例

以下工作流展示了如何在矩阵作业中使用预设：

yml
---
name: CI
on: [push, pull_request]
jobs:
  # 使用环境变量的常规C构建，使用两种编译器：
  build_using_compiler_in_environment:
    strategy:
        matrix:
          compiler:
            - gcc
            - clang
    runs-on: ubuntu-latest
    # 可使用cmakeflags，或直接使用常规环境变量（GitHub Action已支持）：
    env:
      - CC: ${{ matri***piler }}
    steps:
      - uses: actions/checkout@v2
      - uses: docker://lpenz/ghaction-cmake:v0.10
  # 使用cmakeflags的常规C构建，使用两种编译器：
  build_using_compiler_in_cmakeflags:
    strategy:
        matrix:
          compiler:
            - gcc
            - clang
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      # 此示例使用适当的cmakeflags
      - uses: docker://lpenz/ghaction-cmake:v0.10
        with:
          cmakeflags: ${{ format('-DCMAKE_C_COMPILER={0}', matri***piler) }}
  # 使用codecov的覆盖率测试：
  codecov:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: docker://lpenz/ghaction-cmake:v0.10
        with:
          preset: coverage
      # ghaction-cmake可与codecov提供的GitHub Action配合使用：
      - uses: codecov/codecov-action@v1
        with:
          fail_ci_if_error: true
  # 使用coveralls的覆盖率测试：
  coveralls:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: docker://lpenz/ghaction-cmake:v0.10
        with:
          preset: coverage
      # 若传递path-to-lcov，ghaction-cmake可与coveralls提供的GitHub Action配合使用：
      - uses: coverallsapp/github-action@master
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          path-to-lcov: lcov.info
  # 静态分析工具：
  linters:
    strategy:
        matrix:
          preset: [ cppcheck, iwyu, clang-tidy ]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: docker://lpenz/ghaction-cmake:v0.10
        with:
          preset: ${{ matrix.preset }}
  # 使用多种sanitizers和valgrind的测试：
  test:
    strategy:
        matrix:
          preset:
            - clang-sanitizer-address
            - clang-sanitizer-memory
            - clang-sanitizer-undefined
            - clang-sanitizer-dataflow
            - clang-sanitizer-safe-stack
            - valgrind
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: docker://lpenz/ghaction-cmake:v0.10
        with:
          preset: ${{ matrix.preset }}
  # 测试安装：
  install:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: docker://lpenz/ghaction-cmake:v0.10
        with:
          preset: install

注意，上述文件将静态分析工具与sanitizers分开，但实际上它们可放在同一个矩阵作业中，因为其他参数相同。

在其他环境中使用

此GitHub Action实际上是一个Docker镜像，可在本地甚至travis-ci中使用。为此，首先从Docker Hub下载镜像：

sh
docker pull lpenz/ghaction-cmake:v0.10

然后，在项目目录中运行容器，例如：

sh
docker run --rm -t -u "$UID" -w "$PWD" -v "${PWD}:${PWD}" -e INPUT_PRESET=valgrind lpenz/ghaction-cmake:v0.10

需注意，Action参数通过大写环境变量传递，前缀为INPUT_。

以下.travis.yml在travis-ci中运行相同内容：

yml
---
language: generic
jobs:
  include:
    - install: docker pull lpenz/ghaction-cmake:v0.10
    - script: docker run --rm -t -u "$UID" -w "$PWD" -v "${PWD}:${PWD}" -e INPUT_PRESET=valgrind lpenz/ghaction-cmake:v0.10

查看更多 ghaction-cmake 相关镜像 →