coollibs / cpp-ci-template

Simple template to start with continuous integration on GitHub Actions

cpp_CI_template

This template provides a starting point to learn how to set up CI in a C++ project that use CMake. If you don't know nothing about GitHub Actions and CI, see our article that explain what GitHub Actions is and what is it used for. You can find a code example here.

Set-up a workflow

First of all, you need to create a .github/workflows directory and add a .yml file on it.

Choose a name, a trigger and a target

First, you need to give a name to your workflow and choose the trigger of it. Then, you have to choose your target and this should be the name of the target you created in your CMakeLists.txt and want to build and run.

Examples

name: Build and run tests

on: 
  push:
    branches: [ main ]

  pull_request:
    branches: [ main ]


env:
  TARGET: cpp_CI_template-tests

This workflow's name is Build and run tests, it's triggered on push and on pull_request on main and our target is cpp_CI_template-tests

If you want to run mannually a workflow, you can use workflow_dispatch trigger. Then run it using the GitHub API, GitHub CLI, or GitHub browser interface.

name: Create release executables

on: workflow_dispatch

env:
  TARGET: CoolLab

To run your workflow in the GitHub browser interface, you'll have this call to action.

Just clic on it and select the branch or the tag you want the workflow to run on.

Set up a job

Once you have your trigger and your target, you have to set up a job. In this example we have a job for each triplet (OS, compiler, build type) we needed. When setting up a job, you can give it a name and you have to give it the OS on which the job will be effective. There are several way to do it. As we have at least a job for each OS we needed we use

Windows_Clang_Debug:
    name: Windows Clang Debug
    runs-on: windows-2022 

To run on windows. You can find other runners and know more about it here.

Once you have set it up, you can start giving steps to follow to your job. The first one is

- uses: actions/checkout@v3
      with:
          submodules: recursive

This action checks-out your repository and his submodules under $GITHUB_WORKSPACE, so your workflow can access it.

You can now use different steps to configure your Cmake file and run your tests

Example

steps:
    - uses: actions/checkout@v3
      with:
          submodules: recursive

    - name: Configure CMake
      run: cmake .\tests -B ${{github.workspace}}\build -T ClangCL

    - name: Build
      run: cmake --build ${{github.workspace}}\build --config Debug --target ${{env.TARGET}}

    - name: Run
      run: ${{github.workspace}}\build\Debug\${{env.TARGET}}

If you want to run multiple action in one step, you could use the pipe to do it.

steps:
    - uses: actions/checkout@v3
      with:
          submodules: recursive

    - name: Configure CMake
      run: cmake .\tests -B ${{github.workspace}}\build -T ClangCL

    - name: Build and run
      run: |
            cmake --build ${{github.workspace}}\build --config Debug --target ${{env.TARGET}}
            ${{github.workspace}}\build\Debug\${{env.TARGET}}

It will give the same result as before.

Create downloable executables

If you want Github Action to build your project and gives you executables for it, you can use this Justus Adam's tutorial about it and you can learn more about it here. To bo release, you need to have a github tag on the commit you want to release.

Results

Once your CI is set up, you can find the result on the Actions section of your repo.

Then you can see all of your triggered workflows, there names and if they succeed or fail.



If you clic on one you can also see all of the running jobs and how they're going.

Ressources

You can find more about implementing a CI to your project with GitHub Action on the official documentation