lpenz/ghaction-cmake

https://github.com/lpenz/ghaction-cmake/workflows/CI/badge.svg](https://github.com/lpenz/ghaction-cmake/actions)

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。

  此预设可与上传覆盖率数据到在线服务（如https://github.com/marketplace/actions/codecov%E5%92%8Chttps://github.com/marketplace/actions/coveralls-github-action%EF%BC%89%E7%9A%84GitHub Action配合使用。下方示例展示了如何实现。

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

-DCMAKE_C/CXX_CPPCHECK=cppcheck

-DCMAKE_C/CXX_INCLUDE_WHAT_YOU_USE=iwyu

-DCMAKE_INSTALL_PREFIX=/tmp/_install

make install

find /tmp_install -type f

-DCMAKE_C/CXX_CLANG_TIDY=clang-tidy

-DCMAKE_C/CXX_COMPILER=clang/clang++
-DCMAKE_C/CXX_FLAGS=-fno-omit-frame-pointer -fsanitize=<sanitizer>

-DExperimentalMemCheck

-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: ${{ matrix.compiler }}
    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}', matrix.compiler) }}
  # 使用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中使用。为此，首先从https://hub.docker.com/r/lpenz/ghaction-cmake%E4%B8%8B%E8%BD%BD%E9%95%9C%E5%83%8F%EF%BC%9A

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