========================
Configuring the Analyzer
========================

The clang static analyzer supports two kinds of options:

1. Global **analyzer options** influence the behavior of the analyzer engine.
   They are documented on this page, in the section :ref:`List of analyzer
   options<list-of-analyzer-options>`.
2. The **checker options** belong to individual checkers (e.g.
   ``core.BitwiseShift:Pedantic`` and ``unix.Stream:Pedantic`` are completely
   separate options) and customize the behavior of that particular checker.
   These are documented within the documentation of each individual checker at
   :doc:`../checkers`.

Assigning values to options
===========================

With the compiler frontend
--------------------------

All options can be configured by using the ``-analyzer-config`` flag of ``clang
-cc1`` (the so-called *compiler frontend* part of clang). The values of the
options are specified with the syntax ``-analyzer-config
OPT=VAL,OPT2=VAL2,...`` which supports specifying multiple options, but
separate flags like ``-analyzer-config OPT=VAL -analyzer-config OPT2=VAL2`` are
also accepted (with equivalent behavior). Analyzer options and checker options
can be freely intermixed here because it's easy to recognize that checker
option names are always prefixed with ``some.groups.NameOfChecker:``.

.. warning::
   This is an internal interface, one should prefer `clang --analyze ...` for
   regular use. Clang does not intend to preserve backwards compatibility or
   announce breaking changes within the flags accepted by ``clang -cc1``
   (but ``-analyzer-config`` survived many years without major changes).

With the clang driver
---------------------

In a conventional workflow ``clang -cc1`` (which is a low-level internal
interface) is invoked indirectly by the clang *driver* (i.e. plain ``clang``
without the ``-cc1`` flag), which acts as an "even more frontend" wrapper layer
around the ``clang -cc1`` *compiler frontend*. In this situation **each**
command line argument intended for the *compiler frontend* must be prefixed
with ``-Xclang``.

For example the following command analyzes ``foo.c`` in :ref:`shallow mode
<analyzer-option-mode>` with :ref:`loop unrolling
<analyzer-option-unroll-loops>`:

::

  clang --analyze -Xclang -analyzer-config -Xclang mode=shallow,unroll-loops=true foo.c

When this is executed, the *driver* will compose and execute the following
``clang -cc1`` command (which can be inspected by passing the ``-v`` flag to
the *driver*):

::

  clang -cc1 -analyze [...] -analyzer-config mode=shallow,unroll-loops=true foo.c

Here ``[...]`` stands for dozens of low-level flags which ensure that ``clang
-cc1`` does the right thing (e.g. ``-fcolor-diagnostics`` when it's suitable;
``-analyzer-checker`` flags to enable the default set of checkers). Also
note the distinction that the ``clang`` *driver* requires ``--analyze`` (double
dashes) while the ``clang -cc1`` *compiler frontend* requires ``-analyze``
(single dash).

.. note::
   The flag ``-Xanalyzer`` is equivalent to ``-Xclang`` in these situations
   (but doesn't forward other options of the clang frontend).

With CodeChecker
----------------

If the analysis is performed through :ref:`CodeChecker
<command-line-usage-CodeChecker>` (which e.g. supports the analysis of a whole
project instead of a single file) then it will act as another indirection
layer. CodeChecker provides separate command-line flags called
``--analyzer-config`` (for analyzer options) and ``--checker-config`` (for
checker options):

::

  CodeChecker analyze -o outdir --checker-config clangsa:unix.Stream:Pedantic=true  \
          --analyzer-config clangsa:mode=shallow clangsa:unroll-loops=true          \
          -- compile_commands.json

These CodeChecker flags may be followed by multiple ``OPT=VAL`` pairs as
separate arguments (and this is why the example needs to use ``--`` before
``compile_commands.json``). The option names are all prefixed with ``clangsa:``
to ensure that they are passed to the clang static analyzer (and not other
analyzer tools that are also supported by CodeChecker).

.. _list-of-analyzer-options:

List of analyzer options
========================

.. warning::
   These options are primarily intended for development purposes and
   non-default values are usually unsupported. Changing their values may
   drastically alter the behavior of the analyzer, and may even result in
   instabilities or crashes! Crash reports are welcome and depending on the
   severity they may be fixed.

..
   The contents of this section are automatically generated by the script
   clang/docs/tools/generate_analyzer_options_docs.py from the header file
   AnalyzerOptions.def to ensure that the RST/web documentation is synchronized
   with the command line help options.

.. _analyzer-option-mode:

mode
----

(string) Controls the high-level analyzer mode, which influences the default
settings for some of the lower-level config options (such as IPAMode).

Accepted values: "deep", "shallow".

Default value: "deep"

.. _analyzer-option-cfg-implicit-dtors:

cfg-implicit-dtors
------------------

Whether or not implicit destructors for C++ objects should be included in the
CFG.

Default value: true

.. _analyzer-option-cfg-temporary-dtors:

cfg-temporary-dtors
-------------------

Whether or not the destructors for C++ temporary objects should be included in
the CFG.

Default value: true

.. _analyzer-option-cfg-lifetime:

cfg-lifetime
------------

Whether or not end-of-lifetime information should be included in the CFG.

Default value: false

.. _analyzer-option-cfg-loopexit:

cfg-loopexit
------------

Whether or not the end of the loop information should be included in the CFG.

Default value: false

.. _analyzer-option-cfg-rich-constructors:

cfg-rich-constructors
---------------------

Whether or not construction site information should be included in the CFG C++
constructor elements.

Default value: true

.. _analyzer-option-cfg-scopes:

cfg-scopes
----------

Whether or not scope information should be included in the CFG.

Default value: false

.. _analyzer-option-cfg-expand-default-aggr-inits:

cfg-expand-default-aggr-inits
-----------------------------

Whether or not inline CXXDefaultInitializers for aggregate initialization in the
CFG.

Default value: false

.. _analyzer-option-c++-template-inlining:

c++-template-inlining
---------------------

Whether or not templated functions may be considered for inlining.

Default value: true

.. _analyzer-option-c++-stdlib-inlining:

c++-stdlib-inlining
-------------------

Whether or not C++ standard library functions may be considered for inlining.

Default value: true

.. _analyzer-option-c++-allocator-inlining:

c++-allocator-inlining
----------------------

Whether or not allocator and deallocator calls may be considered for inlining.

Default value: true

.. _analyzer-option-c++-shared_ptr-inlining:

c++-shared_ptr-inlining
-----------------------

Whether or not the destructor of C++ 'shared\_ptr' may be considered for
inlining. This covers std::shared\_ptr, std::tr1::shared\_ptr, and
boost::shared\_ptr, and indeed any destructor named '~shared\_ptr'.

Default value: false

.. _analyzer-option-c++-temp-dtor-inlining:

c++-temp-dtor-inlining
----------------------

Whether C++ temporary destructors should be inlined during analysis. If
temporary destructors are disabled in the CFG via the 'cfg-temporary-dtors'
option, temporary destructors would not be inlined anyway.

Default value: true

.. _analyzer-option-suppress-null-return-paths:

suppress-null-return-paths
--------------------------

Whether or not paths that go through null returns should be suppressed. This is
a heuristic for avoiding bug reports with paths that go through inlined
functions that are more defensive than their callers.

Default value: true

.. _analyzer-option-avoid-suppressing-null-argument-paths:

avoid-suppressing-null-argument-paths
-------------------------------------

Whether a bug report should not be suppressed if its path includes a call with a
null argument, even if that call has a null return. This option has no effect
when ShouldSuppressNullReturnPaths is false. This is a counter-heuristic to
avoid false negatives.

Default value: false

.. _analyzer-option-suppress-inlined-defensive-checks:

suppress-inlined-defensive-checks
---------------------------------

Whether or not diagnostics containing inlined defensive NULL checks should be
suppressed.

Default value: true

.. _analyzer-option-c++-container-inlining:

c++-container-inlining
----------------------

Whether or not methods of C++ container objects may be considered for inlining.

Default value: false

.. _analyzer-option-suppress-c++-stdlib:

suppress-c++-stdlib
-------------------

Whether or not diagnostics reported within the C++ standard library should be
suppressed.

Default value: true

.. _analyzer-option-crosscheck-with-z3:

crosscheck-with-z3
------------------

Whether bug reports should be crosschecked with the Z3 constraint manager
backend.

Default value: false

.. _analyzer-option-crosscheck-with-z3-eqclass-timeout-threshold:

crosscheck-with-z3-eqclass-timeout-threshold
--------------------------------------------

Set a timeout for bug report equivalence classes in milliseconds. If we exhaust
this threshold, we will drop the bug report eqclass instead of doing more Z3
queries. Setting this to 700 ms in conjunction with "crosscheck-with-z3-timeout-
threshold" of 300 ms, would nicely guarantee that no bug report equivalence
class can take longer than 1 second, effectively mitigating Z3 hangs during
refutation. If there were Z3 retries, only the minimum query time is considered
when accumulating query times within a report equivalence class. Set 0 for no
timeout.

Default value: 0

.. _analyzer-option-crosscheck-with-z3-timeout-threshold:

crosscheck-with-z3-timeout-threshold
------------------------------------

Set a timeout for individual Z3 queries in milliseconds. On fast machines, 300
worked well in some cases. The lower it is, the higher the chances of having
flaky issues. Having no timeout may hang the analyzer indefinitely. Set 0 for no
timeout.

Default value: 15000

.. _analyzer-option-crosscheck-with-z3-rlimit-threshold:

crosscheck-with-z3-rlimit-threshold
-----------------------------------

Set the Z3 resource limit threshold. This sets a supposedly deterministic cutoff
point for Z3 queries, as longer queries usually consume more resources. 400'000
should on average make Z3 queries run for up to 100ms on modern hardware. Set 0
for unlimited.

Default value: 0

.. _analyzer-option-crosscheck-with-z3-max-attempts-per-query:

crosscheck-with-z3-max-attempts-per-query
-----------------------------------------

Set how many times the oracle is allowed to run a Z3 query. This must be a
positive value. Set 1 to not allow any retry attempts. Increasing the number of
attempts is often more effective at reducing the number of nondeterministic
diagnostics than "crosscheck-with-z3-timeout-threshold" in practice.

Default value: 3

.. _analyzer-option-report-in-main-source-file:

report-in-main-source-file
--------------------------

Whether or not the diagnostic report should be always reported in the main
source file and not the headers.

Default value: false

.. _analyzer-option-stable-report-filename:

stable-report-filename
----------------------

Deprecated: report filenames are now always stable. See also 'verbose-report-
filename'.

Default value: false

.. _analyzer-option-verbose-report-filename:

verbose-report-filename
-----------------------

Whether or not the report filename should contain extra information about the
issue.

Default value: false

.. _analyzer-option-serialize-stats:

serialize-stats
---------------

Whether the analyzer should serialize statistics to plist output. Statistics
would be serialized in JSON format inside the main dictionary under the
statistics key. Available only if compiled in assert mode or with LLVM
statistics explicitly enabled.

Default value: false

.. _analyzer-option-objc-inlining:

objc-inlining
-------------

Whether ObjectiveC inlining is enabled, false otherwise.

Default value: true

.. _analyzer-option-prune-paths:

prune-paths
-----------

Whether irrelevant parts of a bug report path should be pruned out of the final
output.

Default value: true

.. _analyzer-option-add-pop-up-notes:

add-pop-up-notes
----------------

Whether pop-up notes should be added to the final output.

Default value: true

.. _analyzer-option-cfg-conditional-static-initializers:

cfg-conditional-static-initializers
-----------------------------------

Whether 'static' initializers should be in conditional logic in the CFG.

Default value: true

.. _analyzer-option-faux-bodies:

faux-bodies
-----------

Whether the analyzer engine should synthesize fake bodies for well-known
functions.

Default value: true

.. _analyzer-option-elide-constructors:

elide-constructors
------------------

Whether elidable C++ copy-constructors and move-constructors should be actually
elided during analysis. Both behaviors are allowed by the C++ standard, and the
analyzer, like CodeGen, defaults to eliding. Starting with C++17 some elisions
become mandatory, and in these cases the option will be ignored.

Default value: true

.. _analyzer-option-inline-lambdas:

inline-lambdas
--------------

Whether lambdas should be inlined. Otherwise a sink node will be generated each
time a LambdaExpr is visited.

Default value: true

.. _analyzer-option-widen-loops:

widen-loops
-----------

Whether the analysis should try to widen loops.

Default value: false

.. _analyzer-option-unroll-loops:

unroll-loops
------------

Whether the analysis should try to unroll loops with known bounds.

Default value: false

.. _analyzer-option-assume-at-least-one-iteration:

assume-at-least-one-iteration
-----------------------------

Whether the analyzer should always assume at least one iteration in loops where
the loop condition is opaque (i.e. the analyzer cannot determine if it's true or
false). Setting this to true eliminates some false positives (where e.g. a
structure is nonempty, but the analyzer does not notice this); but it also
eliminates some true positives (e.g. cases where a structure can be empty and
this causes buggy behavior).

Default value: false

.. _analyzer-option-notes-as-events:

notes-as-events
---------------

Whether the bug reporter should transparently treat extra note diagnostic pieces
as event diagnostic pieces. Useful when the diagnostic consumer doesn't support
the extra note pieces.

Default value: false

.. _analyzer-option-aggressive-binary-operation-simplification:

aggressive-binary-operation-simplification
------------------------------------------

Whether SValBuilder should rearrange comparisons and additive operations of
symbolic expressions which consist of a sum of a symbol and a concrete integer
into the format where symbols are on the left-hand side and the integer is on
the right. This is only done if both symbols and both concrete integers are
signed, greater than or equal to the quarter of the minimum value of the type
and less than or equal to the quarter of the maximum value of that type. A + n
<OP> B + m becomes A - B <OP> m - n, where A and B symbolic, n and m are
integers. <OP> is any of '==', '!=', '<', '<=', '>', '>=', '+' or '-'. The
rearrangement also happens with '-' instead of '+' on either or both side and
also if any or both integers are missing.

Default value: false

.. _analyzer-option-eagerly-assume:

eagerly-assume
--------------

If this is enabled (the default behavior), when the analyzer encounters a
comparison operator or logical negation, it immediately splits the state to
separate the case when the expression is true and the case when it's false. The
upside is that this can increase analysis precision until we have a better way
to lazily evaluate such logic; the downside is that it eagerly bifurcates paths.

Default value: true

.. _analyzer-option-experimental-enable-naive-ctu-analysis:

experimental-enable-naive-ctu-analysis
--------------------------------------

Whether naive cross translation unit analysis is enabled. This is an
experimental feature to inline functions from other translation units.

Default value: false

.. _analyzer-option-expand-macros:

expand-macros
-------------

Whether macros related to the bugpath should be expanded and included in the
plist output.

Default value: false

.. _analyzer-option-display-ctu-progress:

display-ctu-progress
--------------------

Whether to emit verbose output about the analyzer's progress related to ctu.

Default value: false

.. _analyzer-option-dump-entry-point-stats-to-csv:

dump-entry-point-stats-to-csv
-----------------------------

If provided, the analyzer will dump statistics per entry point into the
specified CSV file.

Default value: (empty string)

.. _analyzer-option-track-conditions:

track-conditions
----------------

Whether to track conditions that are a control dependency of an already tracked
variable.

Default value: true

.. _analyzer-option-track-conditions-debug:

track-conditions-debug
----------------------

Whether to place an event at each tracked condition.

Default value: false

.. _analyzer-option-apply-fixits:

apply-fixits
------------

Apply the fix-it hints to the files

Default value: false

.. _analyzer-option-display-checker-name:

display-checker-name
--------------------

Display the checker name for textual outputs

Default value: true

.. _analyzer-option-support-symbolic-integer-casts:

support-symbolic-integer-casts
------------------------------

Produce cast symbols for integral types.

Default value: false

.. _analyzer-option-assume-controlled-environment:

assume-controlled-environment
-----------------------------

Whether the analyzed application runs in a controlled environment. We will
assume that environment variables exist in queries and they hold no malicious
data. For instance, if this option is enabled, 'getenv()' might be modeled by
the analyzer to never return NULL.

Default value: false

.. _analyzer-option-ignore-bison-generated-files:

ignore-bison-generated-files
----------------------------

If enabled, any files containing the "/\* A Bison parser, made by" won't be
analyzed.

Default value: true

.. _analyzer-option-ignore-flex-generated-files:

ignore-flex-generated-files
---------------------------

If enabled, any files containing the "/\* A lexical scanner generated by flex"
won't be analyzed.

Default value: true

.. _analyzer-option-suppress-dereferences-from-any-address-space:

suppress-dereferences-from-any-address-space
--------------------------------------------

The analyzer does not report dereferences on memory that use address space #256,
#257, and #258. Those address spaces are used when dereferencing address spaces
relative to the GS, FS, and SS segments on x86/x86-64 targets. Dereferencing a
null pointer in these address spaces is not defined as an error. All other null
dereferences in other address spaces are defined as an error unless explicitly
defined. When this option is turned on, the special behavior of address spaces
#256, #257, #258 is extended to all pointers with address spaces and on any
target.

Default value: true

.. _analyzer-option-inline-functions-with-ambiguous-loops:

inline-functions-with-ambiguous-loops
-------------------------------------

If disabled (the default), the analyzer puts functions on a "do not inline this"
list if it finds an execution path within that function that may potentially
perform 'analyzer-max-loop' (= 4 by default) iterations in a loop. (Note that
functions that \_definitely\_ reach the loop limit on some execution path are
currently marked as "do not inline" even if this option is enabled.) Enabling
this option eliminates this (somewhat arbitrary) restriction from the analysis
scope, which increases the analysis runtime (on average by ~10%, but a few
translation units may see much larger slowdowns).

Default value: false

.. _analyzer-option-ipa-always-inline-size:

ipa-always-inline-size
----------------------

The size of the functions (in basic blocks), which should be considered to be
small enough to always inline.

Default value: 3

.. _analyzer-option-graph-trim-interval:

graph-trim-interval
-------------------

How often nodes in the ExplodedGraph should be recycled to save memory. To
disable node reclamation, set the option to 0.

Default value: 1000

.. _analyzer-option-min-cfg-size-treat-functions-as-large:

min-cfg-size-treat-functions-as-large
-------------------------------------

The number of basic blocks a function needs to have to be considered large for
the 'max-times-inline-large' config option.

Default value: 14

.. _analyzer-option-max-symbol-complexity:

max-symbol-complexity
---------------------

The maximum complexity of symbolic constraint.

Default value: 35

.. _analyzer-option-max-tainted-symbol-complexity:

max-tainted-symbol-complexity
-----------------------------

[DEPRECATED] The maximum complexity of a symbol to carry taint

Default value: 9

.. _analyzer-option-max-times-inline-large:

max-times-inline-large
----------------------

The maximum times a large function could be inlined.

Default value: 32

.. _analyzer-option-max-inlinable-size:

max-inlinable-size
------------------

The bound on the number of basic blocks in an inlined function.

Default value: 4 (in shallow mode) / 100 (in deep mode)

.. _analyzer-option-max-nodes:

max-nodes
---------

The maximum number of nodes the analyzer can generate while exploring a top
level function (for each exploded graph). 0 means no limit.

Default value: 75000 (in shallow mode) / 225000 (in deep mode)

.. _analyzer-option-ctu-max-nodes-pct:

ctu-max-nodes-pct
-----------------

The percentage of single-TU analysed nodes that the CTU analysis is allowed to
visit.

Default value: 50

.. _analyzer-option-ctu-max-nodes-min:

ctu-max-nodes-min
-----------------

The maximum number of nodes in CTU mode is determinded by 'ctu-max-nodes-pct'.
However, if the number of nodes in single-TU analysis is too low, it is
meaningful to provide a minimum value that serves as an upper bound instead.

Default value: 10000

.. _analyzer-option-region-store-small-struct-limit:

region-store-small-struct-limit
-------------------------------

The largest number of fields a struct can have and still be considered small.
This is currently used to decide whether or not it is worth forcing a
LazyCompoundVal on bind. To disable all small-struct-dependent behavior, set the
option to 0.

Default value: 2

.. _analyzer-option-region-store-small-array-limit:

region-store-small-array-limit
------------------------------

The largest number of elements an array can have and still be considered small.
This is currently used to decide whether or not it is worth forcing a
LazyCompoundVal on bind. To disable all small-array-dependent behavior, set the
option to 0.

Default value: 5

.. _analyzer-option-region-store-max-binding-fanout:

region-store-max-binding-fanout
-------------------------------

This option limits how many sub-bindings a single binding operation can scatter
into. For example, binding an array would scatter into binding each individual
element. Setting this to zero means unlimited, but then modelling large array
initializers may take proportional time to their size.

Default value: 128

.. _analyzer-option-ctu-dir:

ctu-dir
-------

The directory containing the CTU related files.

Default value: (empty string)

.. _analyzer-option-ctu-index-name:

ctu-index-name
--------------

The name of the file containing the CTU index of definitions. The index file
maps USR-names to identifiers. An identifier can end with an '.ast' suffix,
indicating the indentifier is a path to a pch-dump. Otherwise the identifier is
regarded as path to a source file which is parsed on-demand. Relative paths are
prefixed with ctu-dir, absolute paths are used unmodified during lookup.

Default value: "externalDefMap.txt"

.. _analyzer-option-ctu-invocation-list:

ctu-invocation-list
-------------------

The path to the YAML format file containing a mapping from source file paths to
command-line invocations represented as a list of arguments. This invocation is
used produce the source-file's AST in case on-demand loading is performed.

Example file content::

   {/main.cpp: [clang++, /main.cpp], other.cpp: [clang++, /other.cpp]}

Default value: "invocations.yaml"

.. _analyzer-option-model-path:

model-path
----------

The analyzer can inline an alternative implementation written in C at the call
site if the called function's body is not available. This is a path where to
look for those alternative implementations (called models).

Default value: (empty string)

.. _analyzer-option-ctu-phase1-inlining:

ctu-phase1-inlining
-------------------

Controls which functions will be inlined during the first phase of the ctu
analysis. If the value is set to 'all' then all foreign functions are inlinied
immediately during the first phase, thus rendering the second phase a noop. The
'ctu-max-nodes-\*' budge has no effect in this case. If the value is 'small'
then only functions with a linear CFG and with a limited number of statements
would be inlined during the first phase. The long and/or nontrivial functions
are handled in the second phase and are controlled by the 'ctu-max-nodes-\*'
budge. The value 'none' means that all foreign functions are inlined only in the
second phase, 'ctu-max-nodes-\*' budge limits the second phase.

Accepted values: "none", "small", "all".

Default value: "small"

.. _analyzer-option-c++-inlining:

c++-inlining
------------

Controls which C++ member functions will be considered for inlining.

Accepted values: "constructors", "destructors", "methods".

Default value: "destructors"

.. _analyzer-option-exploration_strategy:

exploration_strategy
--------------------

Accepted values: "dfs", "bfs", "unexplored\_first", "unexplored\_first\_queue",
"unexplored\_first\_location\_queue", "bfs\_block\_dfs\_contents".

Default value: "unexplored_first_queue"

.. _analyzer-option-silence-checkers:

silence-checkers
----------------

A semicolon separated list of checker and package names to silence. Silenced
checkers will not emit reports, but the modeling remain enabled.

Default value: (empty string)

.. _analyzer-option-ipa:

ipa
---

Controls the mode of inter-procedural analysis.

Accepted values: "none", "basic-inlining", "inlining", "dynamic", "dynamic-
bifurcate".

Default value: "inlining" (in shallow mode) / "dynamic-bifurcate" (in deep mode)

