Cit - Control it

Control your c++ code using this continuous integration template.

cit - is a project template for development of C++ codebase. It aggregates linters, static and dynamic analysis tools in single, ready to use template.

Main goals of project

• Explore capabilities of automatic tools and their impact on development

• Give users of project unified access to linters and analysis tools

• Showcase techniques of testing different properties of codebase

• Provide reproducible builds and environments through docker and nix

• Encourage responsible attitude towards the development of quality software

Features

• [x] This repository provides reproducible development and testing environments with version pinning thanks to docker and nix

• [x] Support of major c++ compilers, with all compile time checks enabled

• [x] Familiar cross-platform build setup using cmake and conan

• [x] Runtime tests with doctest and sanitizers

• [x] Command-line tool to simplify usage of functionality

  

• [x] A lot of linters, formatters and static analysis tools integrated and setup for each aspect of project with informative reports thanks to integration with patched version of megalinter

  

• [x] You don’t need to stare at raw logs of tools, thanks to CodeChecker you can check summary tables, statistics for project and reports in your browser

• [x] Even if you can’t run it locally - that’s not an issue. Ready to use GitHub ci setup with same checks and reports uploaded as artifacts

• [x] Pull requests won’t pass if linters found some issues

  

• [x] Reviewdog comments cpp linters output in pull request

  

• [x] Linters suggestions and auto fixes are also displayed by reviewdog as suggestions in pull request

  

• [x] Pull requests feedback with linting results as comment: example. When there are no issues left with pr you will see updated message from bot

  

• [x] Code coverage with pull request Codecov reports

  

• [x] All artifacts with logs are available for download from ci

Current status

This project is under development, expect changes in api, setup and tools. It uses opinionated set of rules and conventions for project, feel free to change configuration files to best fit your personal needs. You can fork and play with it, contributions to the source code, issues and requests are welcome.

Getting Started

You can use this template in different levels of integration with user environment. From using text editor and running all checks in CI, up to using prepared docker image or nix-shell and running check locally.

1. Fork this project, enable GitHub actions and edit it either with GitHub editor or with local text editor

2. Project use cmake ninja and conan. If you have them installed on your system you can build and run tests as with any other cmake project. Or run this bash script from root of project to build project with gcc:

     ci/builders/gcc/build.sh

3. To use this project locally to the full potential you have options:

• Install docker than you can use prepared docker image. Call this script from root of project to run bash shell inside docker image

   ci/docker/run_shell.sh

• Install nix package manager or use nixos. In that case call nix-shell

   nix-shell

Usage

Okay. You got your environment either with docker image or with nix-shell, let’s take a look what’s next. To ease usage of project we use just. So we can call it like that:

   just

You will see available recipes (actions) which you can do to use project:

Let’s explore main functions. You can build project with gcc or clang compiler using commands:

   just build-gcc

   just build-clang

To run all linters on your project use:

   just lint-all

To run specific linter on your project use lint-with command with name of descriptor and linter all capital case split by underscores. So if we want to run clang-tidy from CPP descriptor we call:

   just lint-with CPP_CLANG_TIDY

And we will see report of single linter:

After linting you can check report folder with all logs from linters.

From nix-shell or docker image you can also build docker image yourself. Nix used to reproducibly build tar archive with docker image containing all linters

   just docker-build

You can check that produced result has same hash sum as result produced by ci:

   sha256sum result

Docker image than loaded from result:

   just docker-load

Or you can run docker-update-locally to do image creation, sha256sum and load in single command:

   just docker-update-locally

Docker-update command will build image and upload it to docker-hub:

   just docker-update

To see all inner workings take a look in justfile for concrete bash scripts for each action. Check GitHub workflows file for GitHub ci setup.

Available tools

• online services

  • GitHub actions - check/build/run tests
  • Codecov - verify code coverage of tests
  • lgtm - build and analyze source code
  • dependabot - check dependencies

• unified console commands

  • just - CC0 1.0 Universal

• git

  • git - GPLv2,LGPLv2.1
  • git-sizer - MIT
  • conform - MPL2.0
  • commitlint - MIT
  • gitlint - MIT
  • git-lint - Apache 2.0
  • gitleaks - MIT

• licenses

  • reuse - Apache-2.0

• files and directories

  • ls-lint - MIT

• spelling

  • cspell - MIT
  • codespell - GPLv.2.0

• cpp static analysis

  • clang - warnings as errors checks - Apache 2.0
  • clang-format - NCSA
  • clang-tidy - NCSA
  • cppcheck - GPLv3.0
  • cpplint - BSD 3-clause
  • gcc - warnings as errors checks - GPLv3.0

• cpp dynamic analysis

  • clang - sanitizers - Apache 2.0
  • gcc - sanitizers - GPLv3.0
  • grcov - code coverage - MPL-2.0

• cpp examples of library usage

  • doctest - MIT
  • outcome - Apache-2.0

• cmake

  • cmake-format GPLv3.0
  • cmake-lint GPLv3.0

• shell

  • shellcheck - GPLv3.0

• nix

  • nixpkgs-fmt - Apache-2.0
  • nix-linter - BSD 3-clause
  • nix-shell - LGPL-2.1 License

• md files

  • remark - MIT
  • textlint - MIT

• yaml

  • yamllint - GPLv3.0

Planned

• cpp tools

  • jscpd - MIT
  • valgrind - GPLv2.0
  • libFuzzer - NCSA
  • doxygen - GPLv2.0
  • standardese - MIT
  • mull - Apache-2.0
  • mutate_cpp - MIT
  • rapidcheck - BSD-2-Clause
  • clazy - LGPLv2
  • infer - MIT
  • pvs studio

• cpp compilers

  • msvc - Microsoft EULA
  • MinGW - GNU GPL

• ci environments

  • MacOS
  • Windows

• examples of library usage

  • qt6
  • openssl - Apache-2.0
  • gsl-lite - MIT

• gui testing

  • SikuliX1 - MIT

• reproducible builds testing

  • sha256sum - GPL-3.0

• unified console commands

  • husky - MIT

• approval testing

  • ApprovalTests.cpp - Apache-2.0

• microbenchmarking

• compile time benchmarking

• wiki about project

• logo and illustrations

• stable release versions and tags

• roadmap

Credits

Big thanks to contributors. You can see contributors in credits.

License

cit template released under the terms of the MIT license. See license for more information.