1//===-- AnalyzerOptions.def - Metadata about Static Analyses ----*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9//  This file defines the analyzer options avaible with -analyzer-config.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_ADT_STRINGREF_H
14#error This .def file is expected to be included in translation units where \
15"llvm/ADT/StringRef.h" is already included!
16#endif
17
18#ifdef ANALYZER_OPTION
19#ifndef ANALYZER_OPTION_DEPENDS_ON_USER_MODE
20#error If you didnt include this file with the intent of generating methods, \
21define both 'ANALYZER_OPTION' and 'ANALYZER_OPTION_DEPENDS_ON_USER_MODE' macros!
22#endif
23#endif
24
25#ifndef ANALYZER_OPTION_DEPENDS_ON_USER_MODE
26#ifdef ANALYZER_OPTION
27#error If you didnt include this file with the intent of generating methods, \
28define both 'ANALYZER_OPTION' and 'ANALYZER_OPTION_DEPENDS_ON_USER_MODE' macros!
29#endif
30#endif
31
32#ifndef ANALYZER_OPTION
33/// Create a new analyzer option, but dont generate a method for it in
34/// AnalyzerOptions.
35///
36///   TYPE - The type of the option object that will be stored in
37///          AnalyzerOptions. This file is expected to be icluded in translation
38///          units where AnalyzerOptions.h is included, so types from that
39///          header should be used.
40///   NAME - The name of the option object.
41///   CMDFLAG - The command line flag for the option.
42///             (-analyzer-config CMDFLAG=VALUE)
43///   DESC - Description of the flag.
44///   DEFAULT_VAL - The default value for CMDFLAG.
45#define ANALYZER_OPTION(TYPE, NAME, CMDFLAG, DESC, DEFAULT_VAL)
46#endif
47
48#ifndef ANALYZER_OPTION_DEPENDS_ON_USER_MODE
49/// Create a new analyzer option, but dont generate a method for it in
50/// AnalyzerOptions. It's value depends on the option "user-mode".
51///
52///   TYPE - The type of the option object that will be stored in
53///          AnalyzerOptions. This file is expected to be icluded in translation
54///          units where AnalyzerOptions.h is included, so types from that
55///          header should be used.
56///   NAME - The name of the option object.
57///   CMDFLAG - The command line flag for the option.
58///             (-analyzer-config CMDFLAG=VALUE)
59///   DESC - Description of the flag.
60///   SHALLOW_VAL - The default value for CMDFLAG, when "user-mode" was set to
61///                 "shallow".
62///   DEEP_VAL - The default value for CMDFLAG, when "user-mode" was set to
63///              "deep".
64#define ANALYZER_OPTION_DEPENDS_ON_USER_MODE(TYPE, NAME, CMDFLAG, DESC,        \
65                                             SHALLOW_VAL, DEEP_VAL)
66#endif
67
68//===----------------------------------------------------------------------===//
69// The "mode" option. Since some options depend on this, we list it on top of
70// this file in order to make sure that the generated field for it is
71// initialized before the rest.
72//===----------------------------------------------------------------------===//
73
74ANALYZER_OPTION(
75    StringRef, UserMode, "mode",
76    "(string) Controls the high-level analyzer mode, which influences the "
77    "default settings for some of the lower-level config options (such as "
78    "IPAMode). Value: \"deep\", \"shallow\".",
79    "deep")
80
81//===----------------------------------------------------------------------===//
82// Boolean analyzer options.
83//===----------------------------------------------------------------------===//
84
85ANALYZER_OPTION(bool, ShouldIncludeImplicitDtorsInCFG, "cfg-implicit-dtors",
86                "Whether or not implicit destructors for C++ objects "
87                "should be included in the CFG.",
88                true)
89
90ANALYZER_OPTION(bool, ShouldIncludeTemporaryDtorsInCFG, "cfg-temporary-dtors",
91                "Whether or not the destructors for C++ temporary "
92                "objects should be included in the CFG.",
93                true)
94
95ANALYZER_OPTION(
96    bool, ShouldIncludeLifetimeInCFG, "cfg-lifetime",
97    "Whether or not end-of-lifetime information should be included in the CFG.",
98    false)
99
100ANALYZER_OPTION(bool, ShouldIncludeLoopExitInCFG, "cfg-loopexit",
101                "Whether or not the end of the loop information should "
102                "be included in the CFG.",
103                false)
104
105ANALYZER_OPTION(bool, ShouldIncludeRichConstructorsInCFG,
106                "cfg-rich-constructors",
107                "Whether or not construction site information should be "
108                "included in the CFG C++ constructor elements.",
109                true)
110
111ANALYZER_OPTION(
112    bool, ShouldIncludeScopesInCFG, "cfg-scopes",
113    "Whether or not scope information should be included in the CFG.", false)
114
115ANALYZER_OPTION(bool, ShouldIncludeDefaultInitForAggregates,
116                "cfg-expand-default-aggr-inits",
117                "Whether or not inline CXXDefaultInitializers for aggregate "
118                "initialization in the CFG.",
119                false)
120
121ANALYZER_OPTION(
122    bool, MayInlineTemplateFunctions, "c++-template-inlining",
123    "Whether or not templated functions may be considered for inlining.", true)
124
125ANALYZER_OPTION(bool, MayInlineCXXStandardLibrary, "c++-stdlib-inlining",
126                "Whether or not C++ standard library functions may be "
127                "considered for inlining.",
128                true)
129
130ANALYZER_OPTION(bool, MayInlineCXXAllocator, "c++-allocator-inlining",
131                "Whether or not allocator and deallocator calls may be "
132                "considered for inlining.",
133                true)
134
135ANALYZER_OPTION(
136    bool, MayInlineCXXSharedPtrDtor, "c++-shared_ptr-inlining",
137    "Whether or not the destructor of C++ 'shared_ptr' may be considered for "
138    "inlining. This covers std::shared_ptr, std::tr1::shared_ptr, and "
139    "boost::shared_ptr, and indeed any destructor named '~shared_ptr'.",
140    false)
141
142ANALYZER_OPTION(bool, MayInlineCXXTemporaryDtors, "c++-temp-dtor-inlining",
143                "Whether C++ temporary destructors should be inlined "
144                "during analysis. If temporary destructors are disabled "
145                "in the CFG via the 'cfg-temporary-dtors' option, "
146                "temporary destructors would not be inlined anyway.",
147                true)
148
149ANALYZER_OPTION(
150    bool, ShouldSuppressNullReturnPaths, "suppress-null-return-paths",
151    "Whether or not paths that go through null returns should be suppressed. "
152    "This is a heuristic for avoiding bug reports with paths that go through "
153    "inlined functions that are more defensive than their callers.",
154    true)
155
156ANALYZER_OPTION(
157    bool, ShouldAvoidSuppressingNullArgumentPaths,
158    "avoid-suppressing-null-argument-paths",
159    "Whether a bug report should not be suppressed if its path includes a call "
160    "with a null argument, even if that call has a null return. This option "
161    "has no effect when ShouldSuppressNullReturnPaths is false. This is a "
162    "counter-heuristic to avoid false negatives.",
163    false)
164
165ANALYZER_OPTION(bool, ShouldSuppressInlinedDefensiveChecks,
166                "suppress-inlined-defensive-checks",
167                "Whether or not diagnostics containing inlined "
168                "defensive NULL checks should be suppressed.",
169                true)
170
171ANALYZER_OPTION(bool, MayInlineCXXContainerMethods, "c++-container-inlining",
172                "Whether or not methods of C++ container objects may be "
173                "considered for inlining.",
174                false)
175
176ANALYZER_OPTION(bool, ShouldSuppressFromCXXStandardLibrary,
177                "suppress-c++-stdlib",
178                "Whether or not diagnostics reported within the C++ "
179                "standard library should be suppressed.",
180                true)
181
182ANALYZER_OPTION(bool, ShouldCrosscheckWithZ3, "crosscheck-with-z3",
183                "Whether bug reports should be crosschecked with the Z3 "
184                "constraint manager backend.",
185                false)
186
187ANALYZER_OPTION(bool, ShouldReportIssuesInMainSourceFile,
188                "report-in-main-source-file",
189                "Whether or not the diagnostic report should be always "
190                "reported in the main source file and not the headers.",
191                false)
192
193ANALYZER_OPTION(bool, ShouldWriteStableReportFilename, "stable-report-filename",
194                "Deprecated: report filenames are now always stable. "
195                "See also 'verbose-report-filename'.",
196                false)
197
198ANALYZER_OPTION(bool, ShouldWriteVerboseReportFilename, "verbose-report-filename",
199                "Whether or not the report filename should contain extra "
200                "information about the issue.",
201                false)
202
203ANALYZER_OPTION(
204    bool, ShouldSerializeStats, "serialize-stats",
205    "Whether the analyzer should serialize statistics to plist output. "
206    "Statistics would be serialized in JSON format inside the main dictionary "
207    "under the statistics key. Available only if compiled in assert mode or "
208    "with LLVM statistics explicitly enabled.",
209    false)
210
211ANALYZER_OPTION(bool, MayInlineObjCMethod, "objc-inlining",
212                "Whether ObjectiveC inlining is enabled, false otherwise.",
213                true)
214
215ANALYZER_OPTION(bool, ShouldPrunePaths, "prune-paths",
216                "Whether irrelevant parts of a bug report path should "
217                "be pruned out of the final output.",
218                true)
219
220ANALYZER_OPTION(bool, ShouldAddPopUpNotes, "add-pop-up-notes",
221                "Whether pop-up notes should be added to the final output.",
222                true)
223
224ANALYZER_OPTION(
225    bool, ShouldConditionalizeStaticInitializers,
226    "cfg-conditional-static-initializers",
227    "Whether 'static' initializers should be in conditional logic in the CFG.",
228    true)
229
230ANALYZER_OPTION(bool, ShouldSynthesizeBodies, "faux-bodies",
231                "Whether the analyzer engine should synthesize fake "
232                "bodies for well-known functions.",
233                true)
234
235ANALYZER_OPTION(
236    bool, ShouldElideConstructors, "elide-constructors",
237    "Whether elidable C++ copy-constructors and move-constructors should be "
238    "actually elided during analysis. Both behaviors are allowed by the C++ "
239    "standard, and the analyzer, like CodeGen, defaults to eliding. Starting "
240    "with C++17 some elisions become mandatory, and in these cases the option "
241    "will be ignored.",
242    true)
243
244ANALYZER_OPTION(
245    bool, ShouldInlineLambdas, "inline-lambdas",
246    "Whether lambdas should be inlined. Otherwise a sink node will be "
247    "generated each time a LambdaExpr is visited.",
248    true)
249
250ANALYZER_OPTION(bool, ShouldWidenLoops, "widen-loops",
251                "Whether the analysis should try to widen loops.", false)
252
253ANALYZER_OPTION(
254    bool, ShouldUnrollLoops, "unroll-loops",
255    "Whether the analysis should try to unroll loops with known bounds.", false)
256
257ANALYZER_OPTION(
258    bool, ShouldDisplayNotesAsEvents, "notes-as-events",
259    "Whether the bug reporter should transparently treat extra note diagnostic "
260    "pieces as event diagnostic pieces. Useful when the diagnostic consumer "
261    "doesn't support the extra note pieces.",
262    false)
263
264ANALYZER_OPTION(
265    bool, ShouldAggressivelySimplifyBinaryOperation,
266    "aggressive-binary-operation-simplification",
267    "Whether SValBuilder should rearrange comparisons and additive operations "
268    "of symbolic expressions which consist of a sum of a symbol and a concrete "
269    "integer into the format where symbols are on the left-hand side and the "
270    "integer is on the right. This is only done if both symbols and both "
271    "concrete integers are signed, greater than or equal to the quarter of the "
272    "minimum value of the type and less than or equal to the quarter of the "
273    "maximum value of that type. A + n <OP> B + m becomes A - B <OP> m - n, "
274    "where A and B symbolic, n and m are integers. <OP> is any of '==', '!=', "
275    "'<', '<=', '>', '>=', '+' or '-'. The rearrangement also happens with '-' "
276    "instead of '+' on either or both side and also if any or both integers "
277    "are missing.",
278    false)
279
280ANALYZER_OPTION(
281    bool, ShouldEagerlyAssume, "eagerly-assume",
282    "Whether we should eagerly assume evaluations of conditionals, thus, "
283    "bifurcating the path. This indicates how the engine should handle "
284    "expressions such as: 'x = (y != 0)'. When this is true then the "
285    "subexpression 'y != 0' will be eagerly assumed to be true or false, thus "
286    "evaluating it to the integers 0 or 1 respectively. The upside is that "
287    "this can increase analysis precision until we have a better way to lazily "
288    "evaluate such logic. The downside is that it eagerly bifurcates paths.",
289    true)
290
291ANALYZER_OPTION(
292    bool, IsNaiveCTUEnabled, "experimental-enable-naive-ctu-analysis",
293    "Whether naive cross translation unit analysis is enabled. This is an "
294    "experimental feature to inline functions from other translation units.",
295    false)
296
297ANALYZER_OPTION(bool, ShouldDisplayMacroExpansions, "expand-macros",
298                "Whether macros related to the bugpath should be "
299                "expanded and included in the plist output.",
300                false)
301
302ANALYZER_OPTION(bool, DisplayCTUProgress, "display-ctu-progress",
303                "Whether to emit verbose output about "
304                "the analyzer's progress related to ctu.",
305                false)
306
307ANALYZER_OPTION(bool, ShouldTrackConditions, "track-conditions",
308                "Whether to track conditions that are a control dependency of "
309                "an already tracked variable.",
310                true)
311
312ANALYZER_OPTION(bool, ShouldTrackConditionsDebug, "track-conditions-debug",
313                "Whether to place an event at each tracked condition.",
314                false)
315
316ANALYZER_OPTION(bool, ShouldApplyFixIts, "apply-fixits",
317                "Apply the fix-it hints to the files",
318                false)
319
320ANALYZER_OPTION(bool, ShouldDisplayCheckerNameForText, "display-checker-name",
321                "Display the checker name for textual outputs",
322                true)
323
324ANALYZER_OPTION(bool, ShouldSupportSymbolicIntegerCasts,
325                "support-symbolic-integer-casts",
326                "Produce cast symbols for integral types.",
327                false)
328
329ANALYZER_OPTION(
330    bool, ShouldConsiderSingleElementArraysAsFlexibleArrayMembers,
331    "consider-single-element-arrays-as-flexible-array-members",
332    "Consider single element arrays as flexible array member candidates. "
333    "This will prevent the analyzer from assuming that a single element array "
334    "holds a single element. [DEPRECATED, removing in clang-17; "
335    "use '-fstrict-flex-arrays=<N>' instead]",
336    true)
337
338ANALYZER_OPTION(
339    bool, ShouldAssumeControlledEnvironment, "assume-controlled-environment",
340    "Whether the analyzed application runs in a controlled environment. "
341    "We will assume that environment variables exist in queries and they hold "
342    "no malicious data. For instance, if this option is enabled, 'getenv()' "
343    "might be modeled by the analyzer to never return NULL.",
344    false)
345
346ANALYZER_OPTION(
347    bool, ShouldIgnoreBisonGeneratedFiles, "ignore-bison-generated-files",
348    "If enabled, any files containing the \"/* A Bison parser, made by\" "
349    "won't be analyzed.",
350    true)
351
352ANALYZER_OPTION(
353    bool, ShouldIgnoreFlexGeneratedFiles, "ignore-flex-generated-files",
354    "If enabled, any files containing the \"/* A lexical scanner generated by "
355    "flex\" won't be analyzed.",
356    true)
357
358//===----------------------------------------------------------------------===//
359// Unsigned analyzer options.
360//===----------------------------------------------------------------------===//
361
362ANALYZER_OPTION(unsigned, CTUImportThreshold, "ctu-import-threshold",
363                "The maximal amount of translation units that is considered "
364                "for import when inlining functions during CTU analysis. "
365                "Lowering this threshold can alleviate the memory burden of "
366                "analysis with many interdependent definitions located in "
367                "various translation units. This is valid only for non C++ "
368                "source files.",
369                24u)
370
371ANALYZER_OPTION(unsigned, CTUImportCppThreshold, "ctu-import-cpp-threshold",
372                "The maximal amount of translation units that is considered "
373                "for import when inlining functions during CTU analysis of C++ "
374                "source files.",
375                8u)
376
377ANALYZER_OPTION(
378    unsigned, AlwaysInlineSize, "ipa-always-inline-size",
379    "The size of the functions (in basic blocks), which should be considered "
380    "to be small enough to always inline.",
381    3)
382
383ANALYZER_OPTION(
384    unsigned, GraphTrimInterval, "graph-trim-interval",
385    "How often nodes in the ExplodedGraph should be recycled to save memory. "
386    "To disable node reclamation, set the option to 0.",
387    1000)
388
389ANALYZER_OPTION(
390    unsigned, MinCFGSizeTreatFunctionsAsLarge,
391    "min-cfg-size-treat-functions-as-large",
392    "The number of basic blocks a function needs to have to be considered "
393    "large for the 'max-times-inline-large' config option.",
394    14)
395
396ANALYZER_OPTION(unsigned, MaxSymbolComplexity, "max-symbol-complexity",
397                "The maximum complexity of symbolic constraint.", 35)
398
399ANALYZER_OPTION(unsigned, MaxTimesInlineLarge, "max-times-inline-large",
400                "The maximum times a large function could be inlined.", 32)
401
402ANALYZER_OPTION_DEPENDS_ON_USER_MODE(
403    unsigned, MaxInlinableSize, "max-inlinable-size",
404    "The bound on the number of basic blocks in an inlined function.",
405    /* SHALLOW_VAL */ 4, /* DEEP_VAL */ 100)
406
407ANALYZER_OPTION_DEPENDS_ON_USER_MODE(
408    unsigned, MaxNodesPerTopLevelFunction, "max-nodes",
409    "The maximum number of nodes the analyzer can generate while exploring a "
410    "top level function (for each exploded graph). 0 means no limit.",
411    /* SHALLOW_VAL */ 75000, /* DEEP_VAL */ 225000)
412
413ANALYZER_OPTION(
414    unsigned, CTUMaxNodesPercentage, "ctu-max-nodes-pct",
415    "The percentage of single-TU analysed nodes that the CTU analysis is "
416    "allowed to visit.", 50)
417
418ANALYZER_OPTION(
419    unsigned, CTUMaxNodesMin, "ctu-max-nodes-min",
420    "The maximum number of nodes in CTU mode is determinded by "
421    "'ctu-max-nodes-pct'. However, if the number of nodes in single-TU "
422    "analysis is too low, it is meaningful to provide a minimum value that "
423    "serves as an upper bound instead.", 10000)
424
425ANALYZER_OPTION(
426    StringRef, CTUPhase1InliningMode, "ctu-phase1-inlining",
427    "Controls which functions will be inlined during the first phase of the ctu "
428    "analysis. "
429    "If the value is set to 'all' then all foreign functions are inlinied "
430    "immediately during the first phase, thus rendering the second phase a noop. "
431    "The 'ctu-max-nodes-*' budge has no effect in this case. "
432    "If the value is 'small' then only functions with a linear CFG and with a "
433    "limited number of statements would be inlined during the first phase. The "
434    "long and/or nontrivial functions are handled in the second phase and are "
435    "controlled by the 'ctu-max-nodes-*' budge. "
436    "The value 'none' means that all foreign functions are inlined only in the "
437    "second phase, 'ctu-max-nodes-*' budge limits the second phase. "
438    "Value: \"none\", \"small\", \"all\".",
439    "small")
440
441ANALYZER_OPTION(
442    unsigned, RegionStoreSmallStructLimit, "region-store-small-struct-limit",
443    "The largest number of fields a struct can have and still be considered "
444    "small. This is currently used to decide whether or not it is worth forcing "
445    "a LazyCompoundVal on bind. To disable all small-struct-dependent "
446    "behavior, set the option to 0.",
447    2)
448
449ANALYZER_OPTION(
450    unsigned, RegionStoreSmallArrayLimit, "region-store-small-array-limit",
451    "The largest number of elements an array can have and still be considered "
452    "small. This is currently used to decide whether or not it is worth forcing "
453    "a LazyCompoundVal on bind. To disable all small-array-dependent "
454    "behavior, set the option to 0.",
455    5)
456
457//===----------------------------------------------------------------------===//
458// String analyzer options.
459//===----------------------------------------------------------------------===//
460
461ANALYZER_OPTION(StringRef, CTUDir, "ctu-dir",
462                "The directory containing the CTU related files.", "")
463
464ANALYZER_OPTION(StringRef, CTUIndexName, "ctu-index-name",
465                "The name of the file containing the CTU index of definitions. "
466                "The index file maps USR-names to identifiers. An identifier "
467                "can end with an '.ast' suffix, indicating the indentifier is "
468                "a path to a pch-dump. Otherwise the identifier is regarded as "
469                "path to a source file which is parsed on-demand. Relative "
470                "paths are prefixed with ctu-dir, absolute paths are used "
471                "unmodified during lookup.",
472                "externalDefMap.txt")
473
474ANALYZER_OPTION(
475    StringRef, CTUInvocationList, "ctu-invocation-list",
476    "The path to the YAML format file containing a mapping from source file "
477    "paths to command-line invocations represented as a list of arguments. "
478    "This invocation is used produce the source-file's AST in case on-demand "
479    "loading is performed. Example file-content: "
480    "{/main.cpp: [clang++, /main.cpp], other.cpp: [clang++, /other.cpp]}",
481    "invocations.yaml")
482
483ANALYZER_OPTION(
484    StringRef, ModelPath, "model-path",
485    "The analyzer can inline an alternative implementation written in C at the "
486    "call site if the called function's body is not available. This is a path "
487    "where to look for those alternative implementations (called models).",
488    "")
489
490ANALYZER_OPTION(
491    StringRef, CXXMemberInliningMode, "c++-inlining",
492    "Controls which C++ member functions will be considered for inlining. "
493    "Value: \"constructors\", \"destructors\", \"methods\".",
494    "destructors")
495
496ANALYZER_OPTION(
497    StringRef, ExplorationStrategy, "exploration_strategy",
498    "Value: \"dfs\", \"bfs\", \"unexplored_first\", "
499    "\"unexplored_first_queue\", \"unexplored_first_location_queue\", "
500    "\"bfs_block_dfs_contents\".",
501    "unexplored_first_queue")
502
503ANALYZER_OPTION(
504    StringRef, RawSilencedCheckersAndPackages, "silence-checkers",
505    "A semicolon separated list of checker and package names to silence. "
506    "Silenced checkers will not emit reports, but the modeling remain enabled.",
507    "")
508
509ANALYZER_OPTION_DEPENDS_ON_USER_MODE(
510    StringRef, IPAMode, "ipa",
511    "Controls the mode of inter-procedural analysis. Value: \"none\", "
512    "\"basic-inlining\", \"inlining\", \"dynamic\", \"dynamic-bifurcate\".",
513    /* SHALLOW_VAL */ "inlining", /* DEEP_VAL */ "dynamic-bifurcate")
514
515#undef ANALYZER_OPTION_DEPENDS_ON_USER_MODE
516#undef ANALYZER_OPTION
517