1.. _clang:
2
3Clang static analyzer support
4#############################
5
6Clang Static Analyzer is built on top of Clang and LLVM.
7Strictly speaking, the analyzer is part of Clang, as Clang
8consists of a set of reusable C++ libraries for building
9powerful source-level tools. The static analysis engine used by the
10Clang Static Analyzer is a Clang library, and has the capability to
11be reused in different contexts and by different clients.
12
13LLVM provides various methods to run the analyzer on a codebase,
14through either a dedicated set of tools (scan-build and analyze-build),
15or via command line arguments when running clang ('--analyze').
16
17- 'scan-build' utility comes as the most convenient way for projects
18  using a simple $CC makefile variables, as it will wraps and replace
19  the compiler calls to perform it's analysis.
20
21- 'analyze-build' utility is a sub-tool from 'scan-build', it only
22  relies on a 'compile_commands.json' database to perform the analysis.
23
24- clang option '--analyze' will run the analyzer alongside the build, but
25  objects files are not generated, making any link stage impossible. In
26  our case the first link stage will fail and stop the analysis.
27
28Because of it's complexe build infrastructure, invoking clang analyzer with
29'analyze-build' is the most simple way to analyze a Zephyr project.
30
31`Clang static analyzer documentation <https://clang.llvm.org/docs/ClangStaticAnalyzer.html>`__
32
33Installing clang analyzer
34*************************
35
36'scan-build' and its sub-tool 'analyze-build' come natively with llvm as part of the binaries.
37Make sure to have the binary directory accessible into your PATH.
38
39'scan-build' is also available as a standalone python package available on `pypi <https://pypi.org/project/scan-build/>`__.
40
41.. code-block:: shell
42
43    pip install scan-build
44
45Run clang static analyzer
46*************************
47
48.. note::
49
50  The analyser requires that the project builds with a LLVM toolchain, and
51  produces a 'compile_commands.json' database.
52
53To run clang static analyzer, :ref:`west build <west-building>` should be
54called with a ``-DZEPHYR_SCA_VARIANT=clang`` parameter, alongside the llvm
55toolchain parameters, e.g.
56
57.. zephyr-app-commands::
58   :zephyr-app: samples/userspace/hello_world_user
59   :board: qemu_x86
60   :gen-args: -DZEPHYR_TOOLCHAIN_VARIANT=llvm -DLLVM_TOOLCHAIN_PATH=... -DZEPHYR_SCA_VARIANT=clang
61   :goals: build
62   :compact:
63
64.. note::
65
66  By default, clang static analyzer produces a html report, but various other
67  outputs can be selected with options (sarif, plist, html)
68
69Configuring clang static analyzer
70*********************************
71
72Clang static analyzer can be controlled using specific options.
73To get an exhaustive list of available options, report to the
74'analyze-build' helper and 'scan-build' helper.
75
76.. code-block:: shell
77
78    analyze-build --help
79
80Options already activated by default:
81
82* --analyze-headers : Also analyze functions in #included files.
83
84.. list-table::
85   :header-rows: 1
86
87   * - Parameter
88     - Description
89   * - ``CLANG_SCA_OPTS``
90     - A semicolon separated list of 'analyze-build' options.
91
92These parameters can be passed on the command line, or be set as environment variables.
93
94.. zephyr-app-commands::
95   :zephyr-app: samples/hello_world
96   :board: stm32h573i_dk
97   :gen-args: -DZEPHYR_TOOLCHAIN_VARIANT=llvm -DLLVM_TOOLCHAIN_PATH=... -DZEPHYR_SCA_VARIANT=clang -DCLANG_SCA_OPTS="--sarif;--verbose"
98   :goals: build
99   :compact:
100