diff options
Diffstat (limited to 'gcc/doc/invoke.texi')
| -rw-r--r-- | gcc/doc/invoke.texi | 123 |
1 files changed, 116 insertions, 7 deletions
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index b435781d513..8274d74ef0a 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}. |