invoke.texi (Overall Options): Document --help=.

* doc/invoke.texi (Overall Options): Document --help=.                                                        
* gcc.c (target_help_flag): Rename to print_subprocess_flag.                                                  
  (cc1_options): Pass --help= on to cc1.                                                                      
  (display_help): Add description of --help=.                                                                 
  (process_command): Add code to handle --help=.  Allow translated                                            
  --help and --target-help switches to be passed on to compiler sub-process.                                                                                               
  (main): Remove unused if statement.                                                                         
* opts.c (columns): Remove.                                                                                   
  (LEFT_COLUMN): Define.                                                                                      
  (wrap_help): Add columns argument.                                                                          
  (print_filtered_help): Change parameters to be an include bitmask,                                          
  an exclude bitmask, an any bitmask and the column width.  Move the                                          
  code to display the params list here.  Add code to display the                                              
  status of options rather than their descriptions if the quiet flag                                          
  is not active.                                                                                              
  (print_specific_help): Change parameters to be an include bitmask,                                          
  an exclude bitmask and an any bitmask.  Move code to look up the                                            
  column width here.  Decide upon the title for an options listing.                                           
  (common_handle_options): Add code to handle --help=.  Adapt code                                            
  for --help and --target-help to use the revised form of the                                                 
  print_specific_help function.                                                                               
  (print_help): Delete.                                                                                       
  (print_param_help): Delete.                                                                                 
  (print_switch): Delete.                                                                                     
* opts.h (cl_lang_count): Add prototype.                                                                      
 (CL_PARAMS, CL_WARNING, CL_OPTIMIZATION, CL_MIN_OPTION_CLASS, CL_MAX_OPTION_CLASS): New defines.            
* optc-gen.awk: Add construction of cl_lang_count.                                                            
* c.opt: Add Warning attribute to warning options and Optimization attribute to optimization options.         
* common.opt: Likewise.                                                                                       
  Add --help=.                                                                                                
  Add -fhelp and -ftarget-help as aliases for the transformed --help and --target-help options.               
* opt-functions.awk: Add code to handle Warning and Optimization attributes.

From-SVN: r121849

1 files changed, 116 insertions, 7 deletions

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index b435781..8274d74 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -160,8 +160,9 @@ in the following sections.
 @table @emph
 @item Overall Options
 @xref{Overall Options,,Options Controlling the Kind of Output}.
-@gccoptlist{-c  -S  -E  -o @var{file}  -combine -pipe  -pass-exit-codes  @gol
--x @var{language}  -v  -###  --help  --target-help  --version @@@var{file}}
+@gccoptlist{-c  -S  -E  -o @var{file}  -combine  -pipe  -pass-exit-codes  @gol
+-x @var{language}  -v  -###  --help@r{[}=@var{class}@r{]}  --target-help  @gol 
+--version @@@var{file}}
 
 @item C Language Options
 @xref{C Dialect Options,,Options Controlling C Dialect}.
@@ -1078,15 +1079,123 @@ Print (on the standard output) a description of the command line options
 understood by @command{gcc}.  If the @option{-v} option is also specified
 then @option{--help} will also be passed on to the various processes
 invoked by @command{gcc}, so that they can display the command line options
-they accept.  If the @option{-Wextra} option is also specified then command
-line options which have no documentation associated with them will also
-be displayed.
+they accept.  If the @option{-Wextra} option has also been specified
+(prior to the @option{--help} option), then command line options which
+have no documentation associated with them will also be displayed.
 
 @item --target-help
 @opindex target-help
-Print (on the standard output) a description of target specific command
+Print (on the standard output) a description of target-specific command
 line options for each tool.
 
+@item --help=@var{class}@r{[},@var{qualifier}@r{]}
+Print (on the standard output) a description of the command line
+options understood by the compiler that fit into a specific class.
+The class can be one of @var{optimizers}, @var{warnings}, @var{target}
+or @var{params}:
+
+@table @gcctabopt
+@item @var{optimizers}
+This will display all of the optimization options supported by the
+compiler.
+
+@item @var{warnings}
+This will display all of the options controlling warning messages
+produced by the compiler.
+
+@item @var{target}
+This will display target-specific options.  Unlike the
+@option{--target-help} option however, target-specific options of the
+linker and assembler will not be displayed.  This is because those
+tools do not currently support the extended @option{--help=} syntax.
+
+@item @var{params}
+This will display the values recognized by the @option{--param}
+option.
+@end table
+
+It is possible to further refine the output of the @option{--help=}
+option by adding a comma separated list of qualifiers after the
+class.  These can be any from the following list:
+
+@table @gcctabopt
+@item undocumented
+Display only those options which are undocumented.
+
+@item joined
+Display options which take an argument that appears after an equal
+sign in the same continuous piece of text, such as:
+@samp{--help=target}.
+
+@item separate
+Display options which take an argument that appears as a separate word
+following the original option, such as: @samp{-o output-file}.
+@end table
+
+Thus for example to display all the undocumented target-specific
+switches supported by the compiler the following can be used:
+
+@smallexample
+--help=target,undocumented
+@end smallexample
+
+The sense of a qualifier can be inverted by prefixing it with the
+@var{^} character, so for example to display all binary warning
+options (i.e. ones that are either on or off and that do not take an
+argument), which have a description the following can be used:
+
+@smallexample
+--help=warnings,^joined,^undocumented
+@end smallexample
+
+A class can also be used as a qualifier, although this usually
+restricts the output by so much that there is nothing to display.  One
+case where it does work however is when one of the classes is
+@var{target}.  So for example to display all the target-specific
+optimization options the following can be used:
+
+@smallexample
+--help=target,optimizers
+@end smallexample
+
+The @option{--help=} option can be repeated on the command line.  Each
+successive use will display its requested class of options, skipping
+those that have already been displayed.
+
+If the @option{-Q} option appears on the command line before the
+@option{--help=} option, then the descriptive text displayed by
+@option{--help=} is changed.  Instead of describing the displayed
+options, an indication is given as to whether the option is enabled,
+disabled or set to a specific value (assuming that the compiler
+knows this at the point where the @option{--help=} option is used).
+
+Here is a truncated example from the ARM port of @command{gcc}:
+
+@smallexample
+  % gcc -Q -mabi=2 --help=target -c
+  The following options are target specific:
+  -mabi=                                2
+  -mabort-on-noreturn                   [disabled]
+  -mapcs                                [disabled]
+@end smallexample
+
+The output is sensitive to the effects of previous command line
+options, so for example it is possible to find out which optimizations
+are enabled at @option{-O2} by using:
+
+@smallexample
+-O2 --help=optimizers
+@end smallexample
+
+Alternatively you can discover which binary optimizations are enabled
+by @option{-O3} by using:
+
+@smallexample
+gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts
+gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts
+diff /tmp/O2-opts /tmp/O3-opts | grep enabled
+@end smallexample
+
 @item --version
 @opindex version
 Display the version number and copyrights of the invoked GCC@.
@@ -2754,7 +2863,7 @@ if a variable may be clobbered by a @code{setjmp} call.
 
 These warnings are possible only in optimizing compilation,
 because they require data flow information that is computed only
-when optimizing.  If you do not specify @option{-O}, you will not get 
+when optimizing.  If you do not specify @option{-O}, you will not get
 these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
 requiring @option{-O}.