1.. _codechecker:
2
3CodeChecker support
4###################
5
6`CodeChecker <https://codechecker.readthedocs.io/>`__ is a static analysis infrastructure.
7It executes analysis tools available on the build system, such as
8`Clang-Tidy <https://clang.llvm.org/extra/clang-tidy/>`__,
9`Clang Static Analyzer <https://clang-analyzer.llvm.org/>`__ and
10`Cppcheck <https://cppcheck.sourceforge.io/>`__. Refer to the analyzer's websites for installation
11instructions.
12
13Installing CodeChecker
14**********************
15
16CodeChecker itself is a python package available on `pypi <https://pypi.org/project/codechecker/>`__.
17
18.. code-block:: shell
19
20    pip install codechecker
21
22Building with CodeChecker
23*************************
24
25To run CodeChecker, :ref:`west build <west-building>` should be
26called with a ``-DZEPHYR_SCA_VARIANT=codechecker`` parameter, e.g.
27
28.. code-block:: shell
29
30    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker
31
32
33Configuring CodeChecker
34***********************
35
36CodeChecker uses different command steps, each with their respective configuration
37parameters. The following table lists all these options.
38
39.. list-table::
40   :header-rows: 1
41
42   * - Parameter
43     - Description
44   * - ``CODECHECKER_ANALYZE_JOBS``
45     - The number of threads to use in analysis. (default: <CPU count>)
46   * - ``CODECHECKER_ANALYZE_OPTS``
47     - Arguments passed to the ``analyze`` command directly. (e.g. ``--timeout;360``)
48   * - ``CODECHECKER_CLEANUP``
49     - Perform a cleanup after parsing/storing. This will remove all ``plist`` files.
50   * - ``CODECHECKER_CONFIG_FILE``
51     - A JSON or YAML file with configuration options passed to all commands.
52   * - ``CODECHECKER_EXPORT``
53     - A comma separated list of report types. Allowed types are:
54       ``html,json,codeclimate,gerrit,baseline``.
55   * - ``CODECHECKER_NAME``
56     - The CodeChecker run metadata name. (default: ``zephyr``)
57   * - ``CODECHECKER_PARSE_EXIT_STATUS``
58     - By default, CodeChecker identified issues will not fail the build, set this option to fail
59       during analysis.
60   * - ``CODECHECKER_PARSE_OPTS``
61     - Arguments passed to the ``parse`` command directly. (e.g. ``--verbose;debug``)
62   * - ``CODECHECKER_PARSE_SKIP``
63     - Skip parsing the analysis, useful if you simply want to store the results.
64   * - ``CODECHECKER_STORE``
65     - Run the ``store`` command after analysis.
66   * - ``CODECHECKER_STORE_OPTS``
67     - Arguments passed to the ``store`` command directly. Implies ``CODECHECKER_STORE``.
68       (e.g. ``--url;localhost:8001/Default``)
69   * - ``CODECHECKER_STORE_TAG``
70     - Pass an identifier ``--tag`` to the ``store`` command.
71   * - ``CODECHECKER_TRIM_PATH_PREFIX``
72     - Trim the defined path from the analysis results, e.g. ``/home/user/zephyrproject``.
73       The value from ``west topdir`` is added by default.
74
75These parameters can be passed on the command line, or be set as environment variables.
76
77
78Running twister with CodeChecker
79********************************
80
81When running CodeChecker as part of ``twister`` some default options are set as following:
82
83.. list-table::
84   :header-rows: 1
85
86   * - Parameter
87     - Value
88   * - ``CODECHECKER_ANALYZE_JOBS``
89     - ``1``
90   * - ``CODECHECKER_NAME``
91     - ``<board target>:<testsuite name>``
92   * - ``CODECHECKER_STORE_TAG``
93     - The value from ``git describe`` in the application source directory.
94
95To override these values, set an environment variable or pass them as extra arguments.
96