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.
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.
Static Analysis Jobs on invent.kde.org
Enabling static analysis jobs on KDE's instance of GitLab effectively create two new jobs. We'll explain why there are two jobs later on. The jobs are placed in the "Test" stage, which follows after the "Build" stage. This way the project is first compiled as part of a regular CI build (same as what we have per-commit on build.kde.org. At the end the "build" directory is captured as a job artifact and is passed over to the "Test" stage. This way the static analysis jobs have access to all the generated files without having to compile the project again, which speeds up the pipeline.
To explain why there are two jobs: due to limitation in GitLab CI, it's not possible to define a single job that would create a pipeline either for a merge request OR for push to a git branch. This means that pushing to a branch that has an existing merge request would create a duplicate pipeline - one due for the merge_requests trigger, one for the pushes trigger. The two jobs are called static-analysis-linux-merge-request and static-analysis-linux-commit
static-analysis-linux-merge-request
This job is executed for merge requested - when merge request is created and whenever a new commit is pushed there, this job will be included in the pipeline.
The job doesn't perform static analysis of the entire code base, but it instead detects files that have been changed compared to the merge request target branch and only perform static analysis on those files, again considerably speeding up the pipeline.
static-analysis-linux-commit
This job is executed automatically for push to the master branch. It is possible to customize the trigger branches per project, this will be shown below. The job doesn't perform static analysis of the entire project, but only of files that have changed since the last push to the branch.
Alternatively this job is also used in manually triggered pipelines. This is the only case when the entire code base will be analyzed.
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