115 lines · plain
1========================2Configuring the Analyzer3========================4 5The clang static analyzer supports two kinds of options:6 71. Global **analyzer options** influence the behavior of the analyzer engine.8 They are documented on this page, in the section :ref:`List of analyzer9 options<list-of-analyzer-options>`.102. The **checker options** belong to individual checkers (e.g.11 ``core.BitwiseShift:Pedantic`` and ``unix.Stream:Pedantic`` are completely12 separate options) and customize the behavior of that particular checker.13 These are documented within the documentation of each individual checker at14 :doc:`../checkers`.15 16Assigning values to options17===========================18 19With the compiler frontend20--------------------------21 22All options can be configured by using the ``-analyzer-config`` flag of ``clang23-cc1`` (the so-called *compiler frontend* part of clang). The values of the24options are specified with the syntax ``-analyzer-config25OPT=VAL,OPT2=VAL2,...`` which supports specifying multiple options, but26separate flags like ``-analyzer-config OPT=VAL -analyzer-config OPT2=VAL2`` are27also accepted (with equivalent behavior). Analyzer options and checker options28can be freely intermixed here because it's easy to recognize that checker29option names are always prefixed with ``some.groups.NameOfChecker:``.30 31.. warning::32 This is an internal interface, one should prefer `clang --analyze ...` for33 regular use. Clang does not intend to preserve backwards compatibility or34 announce breaking changes within the flags accepted by ``clang -cc1``35 (but ``-analyzer-config`` survived many years without major changes).36 37With the clang driver38---------------------39 40In a conventional workflow ``clang -cc1`` (which is a low-level internal41interface) is invoked indirectly by the clang *driver* (i.e. plain ``clang``42without the ``-cc1`` flag), which acts as an "even more frontend" wrapper layer43around the ``clang -cc1`` *compiler frontend*. In this situation **each**44command line argument intended for the *compiler frontend* must be prefixed45with ``-Xclang``.46 47For example the following command analyzes ``foo.c`` in :ref:`shallow mode48<analyzer-option-mode>` with :ref:`loop unrolling49<analyzer-option-unroll-loops>`:50 51::52 53 clang --analyze -Xclang -analyzer-config -Xclang mode=shallow,unroll-loops=true foo.c54 55When this is executed, the *driver* will compose and execute the following56``clang -cc1`` command (which can be inspected by passing the ``-v`` flag to57the *driver*):58 59::60 61 clang -cc1 -analyze [...] -analyzer-config mode=shallow,unroll-loops=true foo.c62 63Here ``[...]`` stands for dozens of low-level flags which ensure that ``clang64-cc1`` does the right thing (e.g. ``-fcolor-diagnostics`` when it's suitable;65``-analyzer-checker`` flags to enable the default set of checkers). Also66note the distinction that the ``clang`` *driver* requires ``--analyze`` (double67dashes) while the ``clang -cc1`` *compiler frontend* requires ``-analyze``68(single dash).69 70.. note::71 The flag ``-Xanalyzer`` is equivalent to ``-Xclang`` in these situations72 (but doesn't forward other options of the clang frontend).73 74With CodeChecker75----------------76 77If the analysis is performed through :ref:`CodeChecker78<command-line-usage-CodeChecker>` (which e.g. supports the analysis of a whole79project instead of a single file) then it will act as another indirection80layer. CodeChecker provides separate command-line flags called81``--analyzer-config`` (for analyzer options) and ``--checker-config`` (for82checker options):83 84::85 86 CodeChecker analyze -o outdir --checker-config clangsa:unix.Stream:Pedantic=true \87 --analyzer-config clangsa:mode=shallow clangsa:unroll-loops=true \88 -- compile_commands.json89 90These CodeChecker flags may be followed by multiple ``OPT=VAL`` pairs as91separate arguments (and this is why the example needs to use ``--`` before92``compile_commands.json``). The option names are all prefixed with ``clangsa:``93to ensure that they are passed to the clang static analyzer (and not other94analyzer tools that are also supported by CodeChecker).95 96.. _list-of-analyzer-options:97 98List of analyzer options99========================100 101.. warning::102 These options are primarily intended for development purposes and103 non-default values are usually unsupported. Changing their values may104 drastically alter the behavior of the analyzer, and may even result in105 instabilities or crashes! Crash reports are welcome and depending on the106 severity they may be fixed.107 108..109 The contents of this section are automatically generated by the script110 clang/docs/tools/generate_analyzer_options_docs.py from the header file111 AnalyzerOptions.def to ensure that the RST/web documentation is synchronized112 with the command line help options.113 114.. OPTIONS_LIST_PLACEHOLDER115