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-analyzer-linux-merge-request
static-analyzer-linux-commit
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