Infrastructure/GitLab/CI/Static Code Analysis

Motivation

Static code analysis is a helpful tool to improve and keep high level of code quality. Static code analyzer inspects the source code and looks for issues like wrong usage of some API, bugprone statements, potential performance issues and many others. The static analyzers available on our KDE instance of GitLab are clazy and clang-tidy. Since both of those analyzers are based on the clang C++ compiler, the issues the analyzers find are reported as regular compiler warnings.

How It Works

The chapters below describe how to enable and configure static analysis for your project. Here we will describe some terminology and the overall design of the solution.

Introduction to GitLab CI

Whenever a trigger event happens on GitLab (e.g. a commit is pushed to GitLab, a new merge request is created etc.), GitLab CI will create a new pipeline. A pipeline consist of one or more stages, each stage containing one or more jobs. Which jobs are included in the pipeline may depend on the event that has triggered the pipeline - e.g. you can have different set of jobs executed for each push into the master branch and different set of jobs executed for merge requests.

Jobs within the same stage may be executed in parallel, but jobs in the next stage will always be executed after all jobs in the previous stage have finished. Artifacts of jobs from previous stage are automatically available to jobs in the next stage.

Screenshot of GitLab CI pipeline with two stages (Build and Test), each containing a single successfuly finished job.

Static Code Analysis Intermezzo

Static code analysis is performed, no surprise, by static code analyzers. Analyzers currently supported by our solution are clang-tidy and clazy. Both of them are based on the clang compiler. To perform static analysis, the tools are passed the same arguments as if they were invoked during a regular build, they attempt to compile the given file and as a side-effect of that they produce additional compiler warnings with results of the static analysis check.

Since the static analyzers are basically C++ compilers, one major prerequisite for them to be able to analyze the source code successfuly is that the code must compile. In case of Qt-based applications that means that all the generated header files that might be included from C++ code (e.g. MOC headers, UI headers, DBus adaptor and interface headers) must exist. Since those are generated at build time, it is necessary to run a regular build first to ensure all the files are generated and each file compiles just fine.

Setting up

The GitLab CI pipeline for each project is defined in project's .gitlab-ci.yml file, which must be placed in the top-level directory of the project's git repository.

Below are examples of default configuration that you need to add to the .gitlab-ci.yml file in order to get the static analysis jobs working. The configuration is slightly different based on whether your project is part of Frameworks, Applications or Extragear "groups", or whether it's a completely standalone project (e.g. a personal project).

Frameworks, Applications and Extragear projects

include:
  - https://invent.kde.org/sysadmin/ci-tooling/raw/master/invent/ci-before.yml
  - https://invent.kde.org/sysadmin/ci-tooling/raw/master/invent/ci-<PRODUCT>-linux.yml
  - https://invent.kde.org/sysadmin/ci-tooling/raw/master/invent/ci-static-analysis.yml

static-analysis-linux-merge-request:
  extends: .static-analysis-linux-merge-request

static-analysis-linux-commit:
  extends: .static-analysis-linux-commit

Replace <PRODUCT> with the lower-case name of the product your application belongs to, i.e. frameworks, applications or extragear.

Playground/Miscellaneous projects

include:
  - https://invent.kde.org/sysadmin/ci-tooling/raw/master/invent/ci-before.yml
  - https://invent.kde.org/sysadmin/ci-tooling/raw/master/invent/ci-playground-linux.yml
  - https://invent.kde.org/sysadmin/ci-tooling/raw/master/invent/ci-static-analysis.yml

static-analysis-linux-merge-request:
  extends: .static-analysis-linux-merge-request

static-analysis-linux-commit:
  extends: .static-analysis-linux-commit

Customizing the static analyzer jobs

TODO

Clazy

Intro TODO

Configuring Clazy

TODO

Supressing warnings

TODO

Clang-tidy

Intro TODO

Configuring Clang-tidy

TODO

Supressing warnings

TODO