Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 899f263

Browse filesBrowse 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
Copy full SHA for 899f263

File tree

Expand file treeCollapse file tree

8 files changed

+457
-0
lines changed
Filter options
Expand file treeCollapse file tree

8 files changed

+457
-0
lines changed

‎clang/docs/CMakeLists.txt

Copy file name to clipboardExpand all lines: clang/docs/CMakeLists.txt
+28Lines 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

Copy file name to clipboardExpand all lines: clang/docs/analyzer/user-docs.rst
+1Lines 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

Copy file name to clipboardExpand all lines: clang/docs/analyzer/user-docs/CommandLineUsage.rst
+2Lines 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

Copy file name to clipboard
+114Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.