.. include:: ./../../macros.txt
.. include:: ./../../units.txt

.. _CPPCHECK:

Cppcheck
========

..
    Comments:
    ons is from "add-ons" and not properly recognized by the spellchecker

.. spelling::
    ons

Static Analysis tries to uncover potential errors in software by analyzing the
source code. In this project one of the tools that are used is Cppcheck.

Setup
-----
Cppcheck is free open-source software and obtainable from the
`Cppcheck project website`_. Install the program into the standard paths, but
make sure to also install the optional add-ons, which are not selected by
default. These add-ons add features such as a MISRA analysis.

MISRA
+++++
`MISRA C`_ is an embedded code-style that puts rules in place that aim to avoid
typical mistakes in C-programs.

In order for Cppcheck to be able to conduct a MISRA analysis, the add-on has to
be installed as described. The project maintainers host a
`list of supported MISRA rules`_. As the MISRA rules are proprietary you will
have to obtain the rule texts if you want to see the full rule texts.
Please refer to the `Cppcheck manual`_ in chapter 9.1.2 for more details.

For the GUI, you will have to configure the location of the rule text file
manually in the programs settings.
For the integration in our waf-toolchain, the configure-step expects the file
in ``$USERHOME\Documents\MISRA-C\rules-2012.txt``.

Usage
-----
For using Cppcheck two options are available. The first one is the Cppcheck
GUI, which allows to inspect each defect per file. The second one is the
waf-task, which allows to check all files in one pass.

GUI
+++
The GUI can use a configuration that is generated by the waf-task. For this
to work you have to execute the waf-task at least once.

The generated configuration will be available under
``build/static_analysis/cppcheck.cppcheck``. You can configure Cppcheck to open
the editor of your choice when double-clicking on a violation.

WAF
+++
The waf-task can be called with the parameter ``build_static_analysis``.
It is intended for CI-jobs and will fail if a violation without suppression is
detected. A list of suppressed errors can be configured in
``conf/spa/cppcheck-suppression.txt``.

Suppression
-----------
As mentioned in the section `WAF`_ some checks are suppressed and do not lead
to a failing build task. For most of them this is due to the fact that we are
coming from a codebase that is not adhering to all rules. By suppressing
single rules (ideally only for the offending files) we can revise our codebase
step-by-step and transition to zero violations.

The following part mentions all suppressions that may not be disabled even
transitioning to a cleaner codebase.

``unusedFunction``
++++++++++++++++++
This check has to be suppressed as Cppcheck is not able to recognize every
function that is actually in use. Apart from that Cppcheck is correct on some
unused functions. We aim to check such occurrences with unit- and integration-
tests with coverage-analysis.

``missingInclude``
++++++++++++++++++
Cppcheck can be supplied with the headers of a C-file. It can, however, also
work without the headers and is designed to yield good results nevertheless.
In fact, supplying to many headers, will heavily impact performance of the
analysis and will most of the time not improve the results.

For this reason we are omitting most of the header files in this analysis.
Cppcheck will inform about the missing header-file and this information
is suppressed.

``unmatchedSuppression``
++++++++++++++++++++++++
The used suppressions should be as narrow as possible. Sometimes it is,
however, impractical to mention explicitly every file that violates a certain
rule.
In this case the suppression is applied on every file. In the case that a
particular file has no violations of this type, a warning is generated, which
can be suppressed.