Page MenuHomePhabricator

[analyzer] Add a new frontend flag to display all checker options
Needs RevisionPublic

Authored by Szelethus on Feb 6 2019, 3:48 PM.

Details

Summary

Title says it all, here is how it looks like locally:

clang -cc1 -analyzer-checker-option-help
OVERVIEW: Clang Static Analyzer Checker and Package Option List

USAGE: clang -cc1 [CLANG_OPTIONS] -analyzer-config <OPTION1=VALUE,OPTION2=VALUE,...>

       clang -cc1 [CLANG_OPTIONS] -analyzer-config OPTION1=VALUE, -analyzer-config OPTION2=VALUE, ...

       clang [CLANG_OPTIONS] -Xclang -analyzer-config -Xclang<OPTION1=VALUE,OPTION2=VALUE,...>

       clang [CLANG_OPTIONS] -Xclang -analyzer-config -Xclang OPTION1=VALUE, -Xclang -analyzer-config -Xclang OPTION2=VALUE, ...

OPTIONS:

  alpha.clone.CloneChecker:MinimumCloneComplexity   (int) Ensures that every clone has at least
                                                    the given complexity. Complexity is here
                                                    defined as the total amount of children
                                                    of a statement. This constraint assumes
                                                    the first statement in the group is representative
                                                    for all other statements in the group in
                                                    terms of complexity. (default: 50)

  alpha.clone.CloneChecker:ReportNormalClones       (bool) Report all clones, even less suspicious
                                                    ones. (default: true)

  alpha.clone.CloneChecker:IgnoredFilesPattern      (string) If supplied, the checker wont analyze
                                                    files with a filename that matches the given
                                                    pattern. (default: "")

  alpha.cplusplus.UninitializedObject:Pedantic      (bool) If set to false, the checker won't
                                                    emit warnings for objects that don't have
                                                    at least one initialized field. (default: false)

  alpha.cplusplus.UninitializedObject:NotesAsWarnings
                                                    (bool) If set to true, the checker will
                                                    emit a warning for each uninitalized field,
                                                    as opposed to emitting one warning per constructor
                                                    call, and listing the uninitialized fields
                                                    that belongs to it in notes. (default: false)

  alpha.cplusplus.UninitializedObject:CheckPointeeInitialization
                                                    (bool) If set to false, the checker will
                                                    not analyze the pointee of pointer/reference
                                                    fields, and will only check whether the
                                                    object itself is initialized. (default: false)

  alpha.cplusplus.UninitializedObject:IgnoreRecordsWithField
                                                    (string) If supplied, the checker will not
                                                    analyze structures that have a field with
                                                    a name or type name that matches the given
                                                    pattern. (default: "")

  alpha.cplusplus.UninitializedObject:IgnoreGuardedFields
                                                    (bool) If set to true, the checker will
                                                    analyze _syntactically_ whether the found
                                                    uninitialized object is used without a preceding
                                                    assert call. Defaults to false. (default: false)

  alpha.security.MmapWriteExec:MmapProtExec         (int) Specifies the value of PROT_EXEC 
                                                    (default: 0x04)

  alpha.security.MmapWriteExec:MmapProtRead         (int) Specifies the value of PROT_READ 
                                                    (default: 0x01)

  cplusplus.Move:WarnOn                             (string) In non-aggressive mode, only warn
                                                    on use-after-move of local variables (or
                                                    local rvalue references) and of STL objects.
                                                    The former is possible because local variables
                                                    (or local rvalue references) are not tempting
                                                    their user to re-use the storage. The latter
                                                    is possible because STL objects are known
                                                    to end up in a valid but unspecified state
                                                    after the move and their state-reset methods
                                                    are also known, which allows us to predict
                                                    precisely when use-after-move is invalid.
                                                    Some STL objects are known to conform to
                                                    additional contracts after move, so they
                                                    are not tracked. However, smart pointers
                                                    specifically are tracked because we can
                                                    perform extra checking over them. In aggressive
                                                    mode, warn on any use-after-move because
                                                    the user has intentionally asked us to completely
                                                    eliminate use-after-move in his code. Values:
                                                    "KnownsOnly", "KnownsAndLocals", "All". 
                                                    (default: KnownsAndLocals)

  debug.AnalysisOrder:PreStmtCastExpr               (bool) (default: false)

  debug.AnalysisOrder:PostStmtCastExpr              (bool) (default: false)

  debug.AnalysisOrder:PreStmtArraySubscriptExpr     (bool) (default: false)

  debug.AnalysisOrder:PostStmtArraySubscriptExpr    (bool) (default: false)

  debug.AnalysisOrder:PreStmtCXXNewExpr             (bool) (default: false)

  debug.AnalysisOrder:PostStmtCXXNewExpr            (bool) (default: false)

  debug.AnalysisOrder:PreStmtOffsetOfExpr           (bool) (default: false)

  debug.AnalysisOrder:PostStmtOffsetOfExpr          (bool) (default: false)

  debug.AnalysisOrder:PreCall                       (bool) (default: false)

  debug.AnalysisOrder:PostCall                      (bool) (default: false)

  debug.AnalysisOrder:EndFunction                   (bool) (default: false)

  debug.AnalysisOrder:NewAllocator                  (bool) (default: false)

  debug.AnalysisOrder:Bind                          (bool) (default: false)

  debug.AnalysisOrder:LiveSymbols                   (bool) (default: false)

  debug.AnalysisOrder:RegionChanges                 (bool) (default: false)

  debug.AnalysisOrder:*                             (bool) Enables all callbacks. (default: false)

  nullability:NoDiagnoseCallsToSystemHeaders        (bool) (default: false)

  optin.cplusplus.VirtualCall:PureOnly              (bool) Whether to only report calls to pure
                                                    virtual methods. (default: false)

  optin.osx.cocoa.localizability.NonLocalizedStringChecker:AggressiveReport
                                                    (bool) Marks a string being returned by
                                                    any call as localized if it is in LocStringFunctions
                                                    (LSF) or the function is annotated. Otherwise,
                                                    we mark it as NonLocalized (Aggressive)
                                                    or NonLocalized only if it is not backed
                                                    by a SymRegion (Non-Aggressive), basically
                                                    leaving only string literals as NonLocalized. 
                                                    (default: false)

  optin.performance.Padding:AllowedPad              (int) Reports are only generated if the
                                                    excessive padding exceeds 'AllowedPad' in
                                                    bytes. (default: 24)

  osx.NumberObjectConversion:Pedantic               (bool) Enables detection of more conversion
                                                    patterns (which are most likely more harmless,
                                                    and therefore are more likely to produce
                                                    false positives). (default: false)

  osx.cocoa.RetainCount:leak-diagnostics-reference-allocation
                                                    (bool) (default: false)

  osx.cocoa.RetainCount:CheckOSObject               (bool) (default: true)

  osx.cocoa.RetainCount:TrackNSCFStartParam         (bool) (default: false)

  unix.DynamicMemoryModeling:Optimistic             (bool) If set to true, the checker assumes
                                                    that all the allocating and deallocating
                                                    functions are annotated with ownership_holds,
                                                    ownership_takes and ownership_returns. 
                                                    (default: false)

Diff Detail

Event Timeline

Szelethus created this revision.Feb 6 2019, 3:48 PM
Herald added a project: Restricted Project. · View Herald TranscriptFeb 6 2019, 3:48 PM
NoQ accepted this revision.Feb 8 2019, 6:25 PM

I think this is awesome!

This revision is now accepted and ready to land.Feb 8 2019, 6:25 PM
Szelethus updated this revision to Diff 190625.Mar 14 2019, 7:31 AM
Szelethus edited the summary of this revision. (Show Details)

Also, don't forget package options :^)

Szelethus updated this revision to Diff 190997.Mar 16 2019, 1:06 PM

Add a test case for then checker plugin.

dcoughlin requested changes to this revision.Mar 17 2019, 8:06 PM

I'm pretty worried about exposing this flag to end users.

  • Almost none of the options you've listed are user facing. Many represent options intended for use by static analyzer developers: debugging options, feature flags, and checkers that were never finished. Others represent mechanisms for build systems to control the behavior of the analyzer. Even these are not meant for end users to interact with but rather for implementers of build systems and IDEs. I don't think end users should have to understand these options to use the analyzer.
  • The help text refers to analyzer implementation details (such as "SymRegion") that users won't have the context or knowledge to understand.
  • The help text also recommends invoking -cc1 directly or through the driver with -Xclang. Neither of these are supported end-user interfaces to the analyzer. Instead, users should use scan-build or another tool (such as CodeChecker) that was designed to be used by humans.
This revision now requires changes to proceed.Mar 17 2019, 8:06 PM

This patch isn't intended for end users, which is why -analyzer-checker-option-help is a frontend flag -- besides, some of the plain frontend flags aren't either. It is purely for development purposes, though exposing an end user friendly subset of these through a driver flag would be cool.

Szelethus edited the summary of this revision. (Show Details)Tue, Mar 26, 6:55 AM

@dcoughlin I don't necessarily agree with you.
Let me explain why we think this feature is important.

We should give the users the possibility to list all possibly configurable checker options and their meaning.

Many of these options should be possible to be set by the end user to be able to fine tune the checker behaviour to match the analyzed code style.
Such examples are:
alpha.clone.CloneChecker:MinimumCloneComplexity
alpha.cplusplus.UninitializedObject:CheckPointeeInitialization
alpha.clone.CloneChecker:ReportNormalClones
alpha.cplusplus.UninitializedObject:IgnoreRecordsWithField
etc.
Actually except for the debug checker options and unix.DynamicMemoryModeling:Optimistic all these options are meaningful end-user options.

Of course there are the debug checker options which are not interesting for the end user, but debug checkers should anyway be ignored by the end-users.

We always wanted to add checker option listing to CodeChecker, however did not want to duplicate the option list and option documentation in the CodeChecker codebase.
It belongs to the analyzer and actually to the checker implementation.
So from CodeChecker we would like to invoke the "clang -cc1 -analyzer-checker-option-help" to be able to list these options to the end users.

The same feature is available already in clang-tidy: clang-tidy -dump-config

I think it is the responsibility of the end-user to decide what option he may want to configure.

I understand you would like to differentiate between "developer" and "end-user" options.
What we could do maybe is to indicate in the option explanation that the given option is "analyzer-internal", "experimental" or "developer only".

What do you think about that?

I'm pretty worried about exposing this flag to end users.

  • Almost none of the options you've listed are user facing. Many represent options intended for use by static analyzer developers: debugging options, feature flags, and checkers that were never finished. Others represent mechanisms for build systems to control the behavior of the analyzer. Even these are not meant for end users to interact with but rather for implementers of build systems and IDEs. I don't think end users should have to understand these options to use the analyzer.
  • The help text refers to analyzer implementation details (such as "SymRegion") that users won't have the context or knowledge to understand.
  • The help text also recommends invoking -cc1 directly or through the driver with -Xclang. Neither of these are supported end-user interfaces to the analyzer. Instead, users should use scan-build or another tool (such as CodeChecker) that was designed to be used by humans.