Skip to content

Commit 899f263

Browse files
NagyDonatNagyDonat
authored
[NFC][analyzer] Document configuration options (#135169)
This commit documents the process of specifying values for the analyzer options and checker options implemented in the static analyzer, and adds a script which includes the documentation of the analyzer options (which was previously only available through a command-line flag) in the RST-based web documentation.
1 parent 5fb9dca commit 899f263

File tree

8 files changed

+457
-0
lines changed

8 files changed

+457
-0
lines changed

‎clang/docs/CMakeLists.txt

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,34 @@ if (LLVM_ENABLE_SPHINX)
134134
gen_rst_file_from_td(DiagnosticsReference.rst -gen-diag-docs ../include/clang/Basic/Diagnostic.td "${docs_targets}")
135135
gen_rst_file_from_td(ClangCommandLineReference.rst -gen-opt-docs ../include/clang/Driver/ClangOptionDocs.td "${docs_targets}")
136136

137+
# Another generated file from a different source
138+
set(docs_tools_dir ${CMAKE_CURRENT_SOURCE_DIR}/tools)
139+
set(aopts_rst_rel_path analyzer/user-docs/Options.rst)
140+
set(aopts_rst "${CMAKE_CURRENT_BINARY_DIR}/${aopts_rst_rel_path}")
141+
set(analyzeroptions_def "${CMAKE_CURRENT_SOURCE_DIR}/../include/clang/StaticAnalyzer/Core/AnalyzerOptions.def")
142+
set(aopts_rst_in "${CMAKE_CURRENT_SOURCE_DIR}/${aopts_rst_rel_path}.in")
143+
add_custom_command(
144+
OUTPUT ${aopts_rst}
145+
COMMAND ${Python3_EXECUTABLE} generate_analyzer_options_docs.py
146+
--options-def "${analyzeroptions_def}"
147+
--template "${aopts_rst_in}"
148+
--out "${aopts_rst}"
149+
WORKING_DIRECTORY ${docs_tools_dir}
150+
VERBATIM
151+
COMMENT "Generating ${aopts_rst}"
152+
DEPENDS ${docs_tools_dir}/${generate_aopts_docs}
153+
${aopts_rst_in}
154+
copy-clang-rst-docs
155+
)
156+
add_custom_target(generate-analyzer-options-rst DEPENDS ${aopts_rst})
157+
foreach(target ${docs_targets})
158+
add_dependencies(${target} generate-analyzer-options-rst)
159+
endforeach()
160+
161+
# Technically this is redundant because generate-analyzer-options-rst
162+
# depends on the copy operation (because it wants to drop a generated file
163+
# into a subdirectory of the copied tree), but I'm leaving it here for the
164+
# sake of clarity.
137165
foreach(target ${docs_targets})
138166
add_dependencies(${target} copy-clang-rst-docs)
139167
endforeach()

‎clang/docs/analyzer/user-docs.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Contents:
88

99
user-docs/Installation
1010
user-docs/CommandLineUsage
11+
user-docs/Options
1112
user-docs/UsingWithXCode
1213
user-docs/FilingBugs
1314
user-docs/CrossTranslationUnit

‎clang/docs/analyzer/user-docs/CommandLineUsage.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,8 @@ When compiling your application to run on the simulator, it is important that **
194194

195195
If you aren't certain which compiler Xcode uses to build your project, try just running ``xcodebuild`` (without **scan-build**). You should see the full path to the compiler that Xcode is using, and use that as an argument to ``--use-cc``.
196196

197+
.. _command-line-usage-CodeChecker:
198+
197199
CodeChecker
198200
-----------
199201

‎clang/docs/analyzer/user-docs/Options.rst.in

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
========================
2+
Configuring the Analyzer
3+
========================
4+
5+
The clang static analyzer supports two kinds of options:
6+
7+
1. Global **analyzer options** influence the behavior of the analyzer engine.
8+
They are documented on this page, in the section :ref:`List of analyzer
9+
options<list-of-analyzer-options>`.
10+
2. The **checker options** belong to individual checkers (e.g.
11+
``core.BitwiseShift:Pedantic`` and ``unix.Stream:Pedantic`` are completely
12+
separate options) and customize the behavior of that particular checker.
13+
These are documented within the documentation of each individual checker at
14+
:doc:`../checkers`.
15+
16+
Assigning values to options
17+
===========================
18+
19+
With the compiler frontend
20+
--------------------------
21+
22+
All options can be configured by using the ``-analyzer-config`` flag of ``clang
23+
-cc1`` (the so-called *compiler frontend* part of clang). The values of the
24+
options are specified with the syntax ``-analyzer-config
25+
OPT=VAL,OPT2=VAL2,...`` which supports specifying multiple options, but
26+
separate flags like ``-analyzer-config OPT=VAL -analyzer-config OPT2=VAL2`` are
27+
also accepted (with equivalent behavior). Analyzer options and checker options
28+
can be freely intermixed here because it's easy to recognize that checker
29+
option names are always prefixed with ``some.groups.NameOfChecker:``.
30+
31+
.. warning::
32+
This is an internal interface, one should prefer `clang --analyze ...` for
33+
regular use. Clang does not intend to preserve backwards compatibility or
34+
announce breaking changes within the flags accepted by ``clang -cc1``
35+
(but ``-analyzer-config`` survived many years without major changes).
36+
37+
With the clang driver
38+
---------------------
39+
40+
In a conventional workflow ``clang -cc1`` (which is a low-level internal
41+
interface) is invoked indirectly by the clang *driver* (i.e. plain ``clang``
42+
without the ``-cc1`` flag), which acts as an "even more frontend" wrapper layer
43+
around the ``clang -cc1`` *compiler frontend*. In this situation **each**
44+
command line argument intended for the *compiler frontend* must be prefixed
45+
with ``-Xclang``.
46+
47+
For example the following command analyzes ``foo.c`` in :ref:`shallow mode
48+
<analyzer-option-mode>` with :ref:`loop unrolling
49+
<analyzer-option-unroll-loops>`:
50+
51+
::
52+
53+
clang --analyze -Xclang -analyzer-config -Xclang mode=shallow,unroll-loops=true foo.c
54+
55+
When this is executed, the *driver* will compose and execute the following
56+
``clang -cc1`` command (which can be inspected by passing the ``-v`` flag to
57+
the *driver*):
58+
59+
::
60+
61+
clang -cc1 -analyze [...] -analyzer-config mode=shallow,unroll-loops=true foo.c
62+
63+
Here ``[...]`` stands for dozens of low-level flags which ensure that ``clang
64+
-cc1`` does the right thing (e.g. ``-fcolor-diagnostics`` when it's suitable;
65+
``-analyzer-checker`` flags to enable the default set of checkers). Also
66+
note the distinction that the ``clang`` *driver* requires ``--analyze`` (double
67+
dashes) while the ``clang -cc1`` *compiler frontend* requires ``-analyze``
68+
(single dash).
69+
70+
.. note::
71+
The flag ``-Xanalyzer`` is equivalent to ``-Xclang`` in these situations
72+
(but doesn't forward other options of the clang frontend).
73+
74+
With CodeChecker
75+
----------------
76+
77+
If the analysis is performed through :ref:`CodeChecker
78+
<command-line-usage-CodeChecker>` (which e.g. supports the analysis of a whole
79+
project instead of a single file) then it will act as another indirection
80+
layer. CodeChecker provides separate command-line flags called
81+
``--analyzer-config`` (for analyzer options) and ``--checker-config`` (for
82+
checker 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.json
89+
90+
These CodeChecker flags may be followed by multiple ``OPT=VAL`` pairs as
91+
separate arguments (and this is why the example needs to use ``--`` before
92+
``compile_commands.json``). The option names are all prefixed with ``clangsa:``
93+
to ensure that they are passed to the clang static analyzer (and not other
94+
analyzer tools that are also supported by CodeChecker).
95+
96+
.. _list-of-analyzer-options:
97+
98+
List of analyzer options
99+
========================
100+
101+
.. warning::
102+
These options are primarily intended for development purposes and
103+
non-default values are usually unsupported. Changing their values may
104+
drastically alter the behavior of the analyzer, and may even result in
105+
instabilities or crashes! Crash reports are welcome and depending on the
106+
severity they may be fixed.
107+
108+
..
109+
The contents of this section are automatically generated by the script
110+
clang/docs/tools/generate_analyzer_options_docs.py from the header file
111+
AnalyzerOptions.def to ensure that the RST/web documentation is synchronized
112+
with the command line help options.
113+
114+
.. OPTIONS_LIST_PLACEHOLDER

0 commit comments

Comments
 (0)