[21/49] analyzer: command-line options

This patch contains the command-line options for the analyzer.

gcc/ChangeLog:
	* analyzer/plugin.opt: New file.
	* common.opt (--analyzer): New driver option.
---
 gcc/analyzer/plugin.opt | 161 ++++++++++++++++++++++++++++++++++++++++++++++++
 gcc/common.opt          |   3 +
 2 files changed, 164 insertions(+)
 create mode 100644 gcc/analyzer/plugin.opt

On 11/15/19 6:23 PM, David Malcolm wrote:
> This patch contains the command-line options for the analyzer.
> 

Some of the -Wanalyzer- options sounds like they control similar
warnings as existing options (e.g., -Wanalyzer-null-argument sounds
like -Wnonnull and -Wanalyzer-null-dereference like -Wnull-dereference).
There are also options whose names suggest they are in the same class
as -Wmaybe-xxx (e.g., -Wanalyzer-possible-null-argument sounds like
it would correspond to -Wmaybe-null-argument if it existed).

I have a more general question about the apparent overlap of
functionality that I will save for later but here I wonder about
the names: that introducing a new set of similar sounding options
might make them confusing, and might make the analyzer seem more
like an add-on rather than an integral part of GCC.  I realize
the existing option names don't use any particular convention so
this is an opportunity to put one in place, but at a cost of
divergence.  Unless you expect the existing options to go away,
having consistent names would make for a more cohesive feel.

My other concern is the verbosity of some these options:
-Wanalyzer-use-of-pointer-in-stale-stack-frame is a mouthful and
will take up a lot of terminal space.  It sounds like the option
controls warnings about uses of dangling pointers to auto objects,
similar to -Wreturn-local-addr.  My impression that conventionally
GCC options have tended to be brief, and I personally would prefer
shorter option names.

Martin

> gcc/ChangeLog:
> 	* analyzer/plugin.opt: New file.
> 	* common.opt (--analyzer): New driver option.
> ---
>   gcc/analyzer/plugin.opt | 161 ++++++++++++++++++++++++++++++++++++++++++++++++
>   gcc/common.opt          |   3 +
>   2 files changed, 164 insertions(+)
>   create mode 100644 gcc/analyzer/plugin.opt
> 
> diff --git a/gcc/analyzer/plugin.opt b/gcc/analyzer/plugin.opt
> new file mode 100644
> index 0000000..55f54bb
> --- /dev/null
> +++ b/gcc/analyzer/plugin.opt
> @@ -0,0 +1,161 @@
> +; plugin.opt -- Options for the analyzer.
> +
> +; Copyright (C) 2019 Free Software Foundation, Inc.
> +;
> +; This file is part of GCC.
> +;
> +; GCC is free software; you can redistribute it and/or modify it under
> +; the terms of the GNU General Public License as published by the Free
> +; Software Foundation; either version 3, or (at your option) any later
> +; version.
> +;
> +; GCC is distributed in the hope that it will be useful, but WITHOUT ANY
> +; WARRANTY; without even the implied warranty of MERCHANTABILITY or
> +; FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
> +; for more details.
> +;
> +; You should have received a copy of the GNU General Public License
> +; along with GCC; see the file COPYING3.  If not see
> +; <http://www.gnu.org/licenses/>.
> +
> +; See the GCC internals manual for a description of this file's format.
> +
> +; Please try to keep this file in ASCII collating order.
> +
> +Wanalyzer-double-fclose
> +Common Var(warn_analyzer_double_fclose) Init(1) Warning
> +Warn about code paths in which a stdio FILE can be closed more than once.
> +
> +Wanalyzer-double-free
> +Common Var(warn_analyzer_double_free) Init(1) Warning
> +Warn about code paths in which a pointer can be freed more than once.
> +
> +Wanalyzer-exposure-through-output-file
> +Common Var(warn_analyzer_exposure_through_output_file) Init(1) Warning
> +Warn about code paths in which sensitive data is written to a file.
> +
> +Wanalyzer-file-leak
> +Common Var(warn_analyzer_file_leak) Init(1) Warning
> +Warn about code paths in which a stdio FILE is not closed.
> +
> +Wanalyzer-free-of-non-heap
> +Common Var(warn_analyzer_free_of_non_heap) Init(1) Warning
> +Warn about code paths in which a non-heap pointer is freed.
> +
> +Wanalyzer-malloc-leak
> +Common Var(warn_analyzer_malloc_leak) Init(1) Warning
> +Warn about code paths in which a heap-allocated pointer leaks.
> +
> +Wanalyzer-possible-null-argument
> +Common Var(warn_analyzer_possible_null_argument) Init(1) Warning
> +Warn about code paths in which a possibly-NULL value is passed to a must-not-be-NULL function argument.
> +
> +Wanalyzer-possible-null-dereference
> +Common Var(warn_analyzer_possible_null_dereference) Init(1) Warning
> +Warn about code paths in which a possibly-NULL pointer is dereferenced.
> +
> +Wanalyzer-null-argument
> +Common Var(warn_analyzer_null_argument) Init(1) Warning
> +Warn about code paths in which NULL is passed to a must-not-be-NULL function argument.
> +
> +Wanalyzer-null-dereference
> +Common Var(warn_analyzer_null_dereference) Init(1) Warning
> +Warn about code paths in which a NULL pointer is dereferenced.
> +
> +Wanalyzer-stale-setjmp-buffer
> +Common Var(warn_analyzer_stale_setjmp_buffer) Init(1) Warning
> +Warn about code paths in which a longjmp rewinds to a jmp_buf saved in a stack frame that has returned.
> +
> +Wanalyzer-tainted-array-index
> +Common Var(warn_analyzer_tainted_array_index) Init(1) Warning
> +Warn about code paths in which an unsanitized value is used as an array index.
> +
> +Wanalyzer-use-after-free
> +Common Var(warn_analyzer_use_after_free) Init(1) Warning
> +Warn about code paths in which a freed value is used.
> +
> +Wanalyzer-use-of-pointer-in-stale-stack-frame
> +Common Var(warn_analyzer_use_of_pointer_in_stale_stack_frame) Init(1) Warning
> +Warn about code paths in which a pointer to a stale stack frame is used.
> +
> +Wanalyzer-use-of-uninitialized-value
> +Common Var(warn_analyzer_use_of_uninitialized_value) Init(1) Warning
> +Warn about code paths in which an initialized value is used.
> +
> +Wanalyzer-too-complex
> +Common Var(warn_analyzer_too_complex) Init(0) Warning
> +Warn if the code is too complicated for the analyzer to fully explore.
> +
> +fanalyzer-checker=
> +Common Joined RejectNegative Var(flag_analyzer_checker)
> +Restrict the analyzer to run just the named checker.
> +
> +fanalyzer-fine-grained
> +Common Var(flag_analyzer_fine_grained) Init(0)
> +Avoid combining multiple statements into one exploded edge.
> +
> +fanalyzer-state-purge
> +Common Var(flag_analyzer_state_purge) Init(1)
> +Purge unneeded state during analysis.
> +
> +fanalyzer-state-merge
> +Common Var(flag_analyzer_state_merge) Init(1)
> +Merge similar-enough states during analysis.
> +
> +fanalyzer-transitivity
> +Common Var(flag_analyzer_transitivity) Init(0)
> +Enable transitivity of constraints during analysis.
> +
> +fanalyzer-call-summaries
> +Common Var(flag_analyzer_call_summaries) Init(0)
> +Approximate the effect of function calls to simplify analysis.
> +
> +fanalyzer-verbose-edges
> +Common Var(flag_analyzer_verbose_edges) Init(0)
> +Emit more verbose descriptions of control flow in diagnostics.
> +
> +fanalyzer-verbose-state-changes
> +Common Var(flag_analyzer_verbose_state_changes) Init(0)
> +Emit more verbose descriptions of state changes in diagnostics.
> +
> +fanalyzer-verbosity=
> +Common Joined UInteger Var(analyzer_verbosity) Init(2)
> +Control which events are displayed in diagnostic paths.
> +
> +fdump-analyzer
> +Common RejectNegative Var(flag_dump_analyzer)
> +Dump internal details about what the analyzer is doing to SRCFILE.analyzer.txt.
> +
> +fdump-analyzer-stderr
> +Common RejectNegative Var(flag_dump_analyzer_stderr)
> +Dump internal details about what the analyzer is doing to stderr.
> +
> +fdump-analyzer-callgraph
> +Common RejectNegative Var(flag_dump_analyzer_callgraph)
> +Dump the analyzer supergraph to a SRCFILE.callgraph.dot file.
> +
> +fdump-analyzer-exploded-graph
> +Common RejectNegative Var(flag_dump_analyzer_exploded_graph)
> +Dump the analyzer exploded graph to a SRCFILE.eg.dot file.
> +
> +fdump-analyzer-exploded-nodes
> +Common RejectNegative Var(flag_dump_analyzer_exploded_nodes)
> +Emit diagnostics showing the location of nodes in the exploded graph.
> +
> +fdump-analyzer-exploded-nodes-2
> +Common RejectNegative Var(flag_dump_analyzer_exploded_nodes_2)
> +Dump a textual representation of the exploded graph to SRCFILE.eg.txt.
> +
> +fdump-analyzer-exploded-nodes-3
> +Common RejectNegative Var(flag_dump_analyzer_exploded_nodes_3)
> +Dump a textual representation of the exploded graph to SRCFILE.eg-ID.txt.
> +
> +fdump-analyzer-state-purge
> +Common RejectNegative Var(flag_dump_analyzer_state_purge)
> +Dump state-purging information to a SRCFILE.state-purge.dot file.
> +
> +fdump-analyzer-supergraph
> +Common RejectNegative Var(flag_dump_analyzer_supergraph)
> +Dump the analyzer supergraph to a SRCFILE.supergraph.dot file.
> +
> +; This comment is to ensure we retain the blank line above.
> diff --git a/gcc/common.opt b/gcc/common.opt
> index adc9931..0c352a3 100644
> --- a/gcc/common.opt
> +++ b/gcc/common.opt
> @@ -269,6 +269,9 @@ Driver Joined Alias(e)
>   -extra-warnings
>   Common Warning Alias(Wextra)
>   
> +-analyzer
> +Driver Var(analyzer_flag)
> +
>   -for-assembler
>   Driver Separate Alias(Xassembler)
>   
>

On 12/4/19, Martin Sebor <msebor@gmail.com> wrote:
> On 11/15/19 6:23 PM, David Malcolm wrote:
>> This patch contains the command-line options for the analyzer.
>>
>
> Some of the -Wanalyzer- options sounds like they control similar
> warnings as existing options (e.g., -Wanalyzer-null-argument sounds
> like -Wnonnull and -Wanalyzer-null-dereference like -Wnull-dereference).
> There are also options whose names suggest they are in the same class
> as -Wmaybe-xxx (e.g., -Wanalyzer-possible-null-argument sounds like
> it would correspond to -Wmaybe-null-argument if it existed).

This is something I wondered about too, but I think when you compare
it to how clang does it (their analyzer options don't even have normal
-W names; you have to toggle them in a different way), the approach
David is suggesting for GCC here is better.

>
> I have a more general question about the apparent overlap of
> functionality that I will save for later but here I wonder about
> the names: that introducing a new set of similar sounding options
> might make them confusing, and might make the analyzer seem more
> like an add-on rather than an integral part of GCC.

Clang has this problem, too.

> I realize the existing option names don't use any particular convention so
> this is an opportunity to put one in place, but at a cost of
> divergence.  Unless you expect the existing options to go away,
> having consistent names would make for a more cohesive feel.
>
> My other concern is the verbosity of some these options:
> -Wanalyzer-use-of-pointer-in-stale-stack-frame is a mouthful and
> will take up a lot of terminal space.  It sounds like the option
> controls warnings about uses of dangling pointers to auto objects,
> similar to -Wreturn-local-addr.  My impression that conventionally
> GCC options have tended to be brief, and I personally would prefer
> shorter option names.

While I get this preference, to compare to clang again, some of their
warning names are even longer than that...
-Wanalyzer-use-of-pointer-in-stale-stack-frame really isn't that much
worse than, say, -Wincompatible-pointer-types-discards-qualifiers or
-Wtautological-constant-out-of-range-compare, for example.

>
> Martin
>
>> gcc/ChangeLog:
>> 	* analyzer/plugin.opt: New file.
>> 	* common.opt (--analyzer): New driver option.
>> ---
>>   gcc/analyzer/plugin.opt | 161
>> ++++++++++++++++++++++++++++++++++++++++++++++++
>>   gcc/common.opt          |   3 +
>>   2 files changed, 164 insertions(+)
>>   create mode 100644 gcc/analyzer/plugin.opt
>>
>> diff --git a/gcc/analyzer/plugin.opt b/gcc/analyzer/plugin.opt
>> new file mode 100644
>> index 0000000..55f54bb
>> --- /dev/null
>> +++ b/gcc/analyzer/plugin.opt
>> @@ -0,0 +1,161 @@
>> +; plugin.opt -- Options for the analyzer.
>> +
>> +; Copyright (C) 2019 Free Software Foundation, Inc.
>> +;
>> +; This file is part of GCC.
>> +;
>> +; GCC is free software; you can redistribute it and/or modify it under
>> +; the terms of the GNU General Public License as published by the Free
>> +; Software Foundation; either version 3, or (at your option) any later
>> +; version.
>> +;
>> +; GCC is distributed in the hope that it will be useful, but WITHOUT ANY
>> +; WARRANTY; without even the implied warranty of MERCHANTABILITY or
>> +; FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
>> +; for more details.
>> +;
>> +; You should have received a copy of the GNU General Public License
>> +; along with GCC; see the file COPYING3.  If not see
>> +; <http://www.gnu.org/licenses/>.
>> +
>> +; See the GCC internals manual for a description of this file's format.
>> +
>> +; Please try to keep this file in ASCII collating order.
>> +
>> +Wanalyzer-double-fclose
>> +Common Var(warn_analyzer_double_fclose) Init(1) Warning
>> +Warn about code paths in which a stdio FILE can be closed more than
>> once.
>> +
>> +Wanalyzer-double-free
>> +Common Var(warn_analyzer_double_free) Init(1) Warning
>> +Warn about code paths in which a pointer can be freed more than once.
>> +
>> +Wanalyzer-exposure-through-output-file
>> +Common Var(warn_analyzer_exposure_through_output_file) Init(1) Warning
>> +Warn about code paths in which sensitive data is written to a file.
>> +
>> +Wanalyzer-file-leak
>> +Common Var(warn_analyzer_file_leak) Init(1) Warning
>> +Warn about code paths in which a stdio FILE is not closed.
>> +
>> +Wanalyzer-free-of-non-heap
>> +Common Var(warn_analyzer_free_of_non_heap) Init(1) Warning
>> +Warn about code paths in which a non-heap pointer is freed.
>> +
>> +Wanalyzer-malloc-leak
>> +Common Var(warn_analyzer_malloc_leak) Init(1) Warning
>> +Warn about code paths in which a heap-allocated pointer leaks.
>> +
>> +Wanalyzer-possible-null-argument
>> +Common Var(warn_analyzer_possible_null_argument) Init(1) Warning
>> +Warn about code paths in which a possibly-NULL value is passed to a
>> must-not-be-NULL function argument.
>> +
>> +Wanalyzer-possible-null-dereference
>> +Common Var(warn_analyzer_possible_null_dereference) Init(1) Warning
>> +Warn about code paths in which a possibly-NULL pointer is dereferenced.
>> +
>> +Wanalyzer-null-argument
>> +Common Var(warn_analyzer_null_argument) Init(1) Warning
>> +Warn about code paths in which NULL is passed to a must-not-be-NULL
>> function argument.
>> +
>> +Wanalyzer-null-dereference
>> +Common Var(warn_analyzer_null_dereference) Init(1) Warning
>> +Warn about code paths in which a NULL pointer is dereferenced.
>> +
>> +Wanalyzer-stale-setjmp-buffer
>> +Common Var(warn_analyzer_stale_setjmp_buffer) Init(1) Warning
>> +Warn about code paths in which a longjmp rewinds to a jmp_buf saved in a
>> stack frame that has returned.
>> +
>> +Wanalyzer-tainted-array-index
>> +Common Var(warn_analyzer_tainted_array_index) Init(1) Warning
>> +Warn about code paths in which an unsanitized value is used as an array
>> index.
>> +
>> +Wanalyzer-use-after-free
>> +Common Var(warn_analyzer_use_after_free) Init(1) Warning
>> +Warn about code paths in which a freed value is used.
>> +
>> +Wanalyzer-use-of-pointer-in-stale-stack-frame
>> +Common Var(warn_analyzer_use_of_pointer_in_stale_stack_frame) Init(1)
>> Warning
>> +Warn about code paths in which a pointer to a stale stack frame is used.
>> +
>> +Wanalyzer-use-of-uninitialized-value
>> +Common Var(warn_analyzer_use_of_uninitialized_value) Init(1) Warning
>> +Warn about code paths in which an initialized value is used.
>> +
>> +Wanalyzer-too-complex
>> +Common Var(warn_analyzer_too_complex) Init(0) Warning
>> +Warn if the code is too complicated for the analyzer to fully explore.
>> +
>> +fanalyzer-checker=
>> +Common Joined RejectNegative Var(flag_analyzer_checker)
>> +Restrict the analyzer to run just the named checker.
>> +
>> +fanalyzer-fine-grained
>> +Common Var(flag_analyzer_fine_grained) Init(0)
>> +Avoid combining multiple statements into one exploded edge.
>> +
>> +fanalyzer-state-purge
>> +Common Var(flag_analyzer_state_purge) Init(1)
>> +Purge unneeded state during analysis.
>> +
>> +fanalyzer-state-merge
>> +Common Var(flag_analyzer_state_merge) Init(1)
>> +Merge similar-enough states during analysis.
>> +
>> +fanalyzer-transitivity
>> +Common Var(flag_analyzer_transitivity) Init(0)
>> +Enable transitivity of constraints during analysis.
>> +
>> +fanalyzer-call-summaries
>> +Common Var(flag_analyzer_call_summaries) Init(0)
>> +Approximate the effect of function calls to simplify analysis.
>> +
>> +fanalyzer-verbose-edges
>> +Common Var(flag_analyzer_verbose_edges) Init(0)
>> +Emit more verbose descriptions of control flow in diagnostics.
>> +
>> +fanalyzer-verbose-state-changes
>> +Common Var(flag_analyzer_verbose_state_changes) Init(0)
>> +Emit more verbose descriptions of state changes in diagnostics.
>> +
>> +fanalyzer-verbosity=
>> +Common Joined UInteger Var(analyzer_verbosity) Init(2)
>> +Control which events are displayed in diagnostic paths.
>> +
>> +fdump-analyzer
>> +Common RejectNegative Var(flag_dump_analyzer)
>> +Dump internal details about what the analyzer is doing to
>> SRCFILE.analyzer.txt.
>> +
>> +fdump-analyzer-stderr
>> +Common RejectNegative Var(flag_dump_analyzer_stderr)
>> +Dump internal details about what the analyzer is doing to stderr.
>> +
>> +fdump-analyzer-callgraph
>> +Common RejectNegative Var(flag_dump_analyzer_callgraph)
>> +Dump the analyzer supergraph to a SRCFILE.callgraph.dot file.
>> +
>> +fdump-analyzer-exploded-graph
>> +Common RejectNegative Var(flag_dump_analyzer_exploded_graph)
>> +Dump the analyzer exploded graph to a SRCFILE.eg.dot file.
>> +
>> +fdump-analyzer-exploded-nodes
>> +Common RejectNegative Var(flag_dump_analyzer_exploded_nodes)
>> +Emit diagnostics showing the location of nodes in the exploded graph.
>> +
>> +fdump-analyzer-exploded-nodes-2
>> +Common RejectNegative Var(flag_dump_analyzer_exploded_nodes_2)
>> +Dump a textual representation of the exploded graph to SRCFILE.eg.txt.
>> +
>> +fdump-analyzer-exploded-nodes-3
>> +Common RejectNegative Var(flag_dump_analyzer_exploded_nodes_3)
>> +Dump a textual representation of the exploded graph to
>> SRCFILE.eg-ID.txt.
>> +
>> +fdump-analyzer-state-purge
>> +Common RejectNegative Var(flag_dump_analyzer_state_purge)
>> +Dump state-purging information to a SRCFILE.state-purge.dot file.
>> +
>> +fdump-analyzer-supergraph
>> +Common RejectNegative Var(flag_dump_analyzer_supergraph)
>> +Dump the analyzer supergraph to a SRCFILE.supergraph.dot file.
>> +
>> +; This comment is to ensure we retain the blank line above.
>> diff --git a/gcc/common.opt b/gcc/common.opt
>> index adc9931..0c352a3 100644
>> --- a/gcc/common.opt
>> +++ b/gcc/common.opt
>> @@ -269,6 +269,9 @@ Driver Joined Alias(e)
>>   -extra-warnings
>>   Common Warning Alias(Wextra)
>>
>> +-analyzer
>> +Driver Var(analyzer_flag)
>> +
>>   -for-assembler
>>   Driver Separate Alias(Xassembler)
>>
>>
>
>