* [doc, 1/n] invoke.texi: name of gcc executable
2016-01-10 23:50 [doc, 0/n] improve organization of invoke.texi Sandra Loosemore
@ 2016-01-12 17:45 ` Sandra Loosemore
2016-01-13 0:48 ` [doc, 1.5/n] invoke.texi: reclassify -no-canonical-prefixes and -specs= Sandra Loosemore
` (6 subsequent siblings)
7 siblings, 0 replies; 12+ messages in thread
From: Sandra Loosemore @ 2016-01-12 17:45 UTC (permalink / raw)
To: GCC Patches
[-- Attachment #1: Type: text/plain, Size: 490 bytes --]
I've checked in the first installment of my planned reorganization of
the invoke.texi chapter. Here I've deleted the section placed randomly
in the middle of option descriptions that contained only a paragraph
about the name of the gcc executable, and incorporated that information
into the chapter introduction instead. I did a little bit of editing of
the text in the introduction as well, and rewrote the one reference to
the deleted node so it makes sense without it.
-Sandra
[-- Attachment #2: gccdoc.log --]
[-- Type: text/x-log, Size: 298 bytes --]
2016-01-12 Sandra Loosemore <sandra@codesourcery.com>
gcc/
* doc/invoke.texi (Invoking GCC): Copy-edit. Incorporate information
about name of GCC executable. Remove deleted node from menu.
(Directory Options) <-B>: Remove cross-reference to deleted node.
(Target Options): Delete section.
[-- Attachment #3: gccdoc.patch --]
[-- Type: text/x-patch, Size: 3698 bytes --]
Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi (revision 232279)
+++ gcc/doc/invoke.texi (working copy)
@@ -72,8 +72,9 @@ assembly and linking. The ``overall opt
process at an intermediate stage. For example, the @option{-c} option
says not to run the linker. Then the output consists of object files
output by the assembler.
+@xref{Overall Options,,Options Controlling the Kind of Output}.
-Other options are passed on to one stage of processing. Some options
+Other options are passed on to one or more stages of processing. Some options
control the preprocessor and others the compiler itself. Yet other
options control the assembler and linker; most of these are not
documented here, since you rarely need to use any of them.
@@ -85,9 +86,18 @@ for C programs; when an option is only u
for a particular option does not mention a source language, you can use
that option with all supported languages.
-@cindex C++ compilation options
-@xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
-options for compiling C++ programs.
+@cindex cross compiling
+@cindex specifying machine version
+@cindex specifying compiler version and target machine
+@cindex compiler version, specifying
+@cindex target machine, specifying
+The usual way to run GCC is to run the executable called @command{gcc}, or
+@command{@var{machine}-gcc} when cross-compiling, or
+@command{@var{machine}-gcc-@var{version}} to run a specific version of GCC.
+When you compile C++ programs, you should invoke GCC as @command{g++}
+instead. @xref{Invoking G++,,Compiling C++ Programs},
+for information about the differences in behavior between @command{gcc}
+and @code{g++} when compiling C++ programs.
@cindex grouping options
@cindex options, grouping
@@ -137,7 +147,6 @@ only one of these two forms, whichever o
* Directory Options:: Where to find header files and libraries.
Where to find the compiler executable files.
* Spec Files:: How to pass switches to sub-processes.
-* Target Options:: Running a cross-compiler, or an old version of GCC.
* Submodel Options:: Specifying minor hardware or convention variations,
such as 68010 vs 68020.
* Code Gen Options:: Specifying conventions for function calls, data layout
@@ -11733,7 +11742,8 @@ include files, and data files of the com
The compiler driver program runs one or more of the subprograms
@command{cpp}, @command{cc1}, @command{as} and @command{ld}. It tries
@var{prefix} as a prefix for each program it tries to run, both with and
-without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
+without @samp{@var{machine}/@var{version}/} for the corresponding target
+machine and compiler version.
For each subprogram to be run, the compiler driver first tries the
@option{-B} prefix, if any. If that name is not found, or if @option{-B}
@@ -12409,20 +12419,6 @@ proper position among the other output f
@c man begin OPTIONS
-@node Target Options
-@section Specifying Target Machine and Compiler Version
-@cindex target options
-@cindex cross compiling
-@cindex specifying machine version
-@cindex specifying compiler version and target machine
-@cindex compiler version, specifying
-@cindex target machine, specifying
-
-The usual way to run GCC is to run the executable called @command{gcc}, or
-@command{@var{machine}-gcc} when cross-compiling, or
-@command{@var{machine}-gcc-@var{version}} to run a version other than the
-one that was installed last.
-
@node Submodel Options
@section Hardware Models and Configurations
@cindex submodel options
^ permalink raw reply [flat|nested] 12+ messages in thread* [doc, 1.5/n] invoke.texi: reclassify -no-canonical-prefixes and -specs=
2016-01-10 23:50 [doc, 0/n] improve organization of invoke.texi Sandra Loosemore
2016-01-12 17:45 ` [doc, 1/n] invoke.texi: name of gcc executable Sandra Loosemore
@ 2016-01-13 0:48 ` Sandra Loosemore
2016-01-13 3:31 ` [doc, 2/n] invoke.texi: move spec file section Sandra Loosemore
` (5 subsequent siblings)
7 siblings, 0 replies; 12+ messages in thread
From: Sandra Loosemore @ 2016-01-13 0:48 UTC (permalink / raw)
To: GCC Patches
[-- Attachment #1: Type: text/plain, Size: 538 bytes --]
This is an "extra" installment in my series to clean up the organization
of invoke.texi. When I was working on the previous installment, I
noticed that -no-canonical-prefixes would be better classified in
"Directory Options" than "Overall Options", and vice-versa for -specs=
(which seems to be more closely related to the other subprocess-related
commands -pipe, -pass-exit-codes, and -wrapper than anything to do with
directories). I've checked in this patch to move the docs around to the
more appropriate sections.
-Sandra
[-- Attachment #2: gccdoc.log --]
[-- Type: text/x-log, Size: 357 bytes --]
2016-01-12 Sandra Loosemore <sandra@codesourcery.com>
gcc/
* doc/invoke.texi (Option Summary) Move -no-canonical-prefixes to
Directory Options, and -specs= to Overall Options.
(Overall Options): Adjust similarly. Reorder to group related
options together. Make -specs= cross-reference the spec file details.
(Directory Options): Adjust similarly.
[-- Attachment #3: gccdoc.patch --]
[-- Type: text/x-patch, Size: 5374 bytes --]
Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi (revision 232285)
+++ gcc/doc/invoke.texi (working copy)
@@ -166,10 +166,10 @@ 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} -no-canonical-prefixes @gol
--pipe -pass-exit-codes @gol
--x @var{language} -v -### --help@r{[}=@var{class}@r{[},@dots{}@r{]]} --target-help @gol
---version -wrapper @@@var{file} -fplugin=@var{file} -fplugin-arg-@var{name}=@var{arg} @gol
+@gccoptlist{-c -S -E -o @var{file} -x @var{language} @gol
+-v -### --help@r{[}=@var{class}@r{[},@dots{}@r{]]} --target-help --version @gol
+-pass-exit-codes -pipe -specs=@var{file} -wrapper @gol
+@@@var{file} -fplugin=@var{file} -fplugin-arg-@var{name}=@var{arg} @gol
-fdump-ada-spec@r{[}-slim@r{]} -fada-spec-parent=@var{unit} -fdump-go-spec=@var{file}}
@item C Language Options
@@ -513,7 +513,7 @@ Objective-C and Objective-C++ Dialects}.
@item Directory Options
@xref{Directory Options,,Options for Directory Search}.
@gccoptlist{-B@var{prefix} -I@var{dir} -iplugindir=@var{dir} @gol
--iquote@var{dir} -L@var{dir} -specs=@var{file} -I- @gol
+-iquote@var{dir} -L@var{dir} -no-canonical-prefixes -I- @gol
--sysroot=@var{dir} --no-sysroot-suffix}
@item Machine Dependent Options
@@ -1342,15 +1342,6 @@ java
Turn off any specification of a language, so that subsequent files are
handled according to their file name suffixes (as they are if @option{-x}
has not been used at all).
-
-@item -pass-exit-codes
-@opindex pass-exit-codes
-Normally the @command{gcc} program exits with the code of 1 if any
-phase of the compiler returns a non-success return code. If you specify
-@option{-pass-exit-codes}, the @command{gcc} program instead returns with
-the numerically highest error produced by any phase returning an error
-indication. The C, C++, and Fortran front ends return 4 if an internal
-compiler error is encountered.
@end table
If you only want some of the stages of compilation, you can use
@@ -1417,13 +1408,6 @@ Like @option{-v} except the commands are
are quoted unless they contain only alphanumeric characters or @code{./-_}.
This is useful for shell scripts to capture the driver-generated command lines.
-@item -pipe
-@opindex pipe
-Use pipes rather than temporary files for communication between the
-various stages of compilation. This fails to work on some systems where
-the assembler is unable to read from a pipe; but the GNU assembler has
-no trouble.
-
@item --help
@opindex help
Print (on the standard output) a description of the command-line options
@@ -1556,16 +1540,36 @@ gcc -c -Q -O2 --help=optimizers > /tmp/O
diff /tmp/O2-opts /tmp/O3-opts | grep enabled
@end smallexample
-@item -no-canonical-prefixes
-@opindex no-canonical-prefixes
-Do not expand any symbolic links, resolve references to @samp{/../}
-or @samp{/./}, or make the path absolute when generating a relative
-prefix.
-
@item --version
@opindex version
Display the version number and copyrights of the invoked GCC@.
+@item -pass-exit-codes
+@opindex pass-exit-codes
+Normally the @command{gcc} program exits with the code of 1 if any
+phase of the compiler returns a non-success return code. If you specify
+@option{-pass-exit-codes}, the @command{gcc} program instead returns with
+the numerically highest error produced by any phase returning an error
+indication. The C, C++, and Fortran front ends return 4 if an internal
+compiler error is encountered.
+
+@item -pipe
+@opindex pipe
+Use pipes rather than temporary files for communication between the
+various stages of compilation. This fails to work on some systems where
+the assembler is unable to read from a pipe; but the GNU assembler has
+no trouble.
+
+@item -specs=@var{file}
+@opindex specs
+Process @var{file} after the compiler reads in the standard @file{specs}
+file, in order to override the defaults which the @command{gcc} driver
+program uses when determining what switches to pass to @command{cc1},
+@command{cc1plus}, @command{as}, @command{ld}, etc. More than one
+@option{-specs=@var{file}} can be specified on the command line, and they
+are processed in order, from left to right. @xref{Spec Files}, for
+information about the format of the @var{file}.
+
@item -wrapper
@opindex wrapper
Invoke all subcommands under a wrapper program. The name of the
@@ -11778,14 +11782,11 @@ As a special kludge, if the path provide
9, then it is replaced by @file{[dir/]include}. This is to help
with boot-strapping the compiler.
-@item -specs=@var{file}
-@opindex specs
-Process @var{file} after the compiler reads in the standard @file{specs}
-file, in order to override the defaults which the @command{gcc} driver
-program uses when determining what switches to pass to @command{cc1},
-@command{cc1plus}, @command{as}, @command{ld}, etc. More than one
-@option{-specs=@var{file}} can be specified on the command line, and they
-are processed in order, from left to right.
+@item -no-canonical-prefixes
+@opindex no-canonical-prefixes
+Do not expand any symbolic links, resolve references to @samp{/../}
+or @samp{/./}, or make the path absolute when generating a relative
+prefix.
@item --sysroot=@var{dir}
@opindex sysroot
^ permalink raw reply [flat|nested] 12+ messages in thread* [doc, 2/n] invoke.texi: move spec file section
2016-01-10 23:50 [doc, 0/n] improve organization of invoke.texi Sandra Loosemore
2016-01-12 17:45 ` [doc, 1/n] invoke.texi: name of gcc executable Sandra Loosemore
2016-01-13 0:48 ` [doc, 1.5/n] invoke.texi: reclassify -no-canonical-prefixes and -specs= Sandra Loosemore
@ 2016-01-13 3:31 ` Sandra Loosemore
2016-01-13 21:08 ` [doc, 3/n] invoke.texi: move "Code Gen Options" before target-specific options Sandra Loosemore
` (4 subsequent siblings)
7 siblings, 0 replies; 12+ messages in thread
From: Sandra Loosemore @ 2016-01-13 3:31 UTC (permalink / raw)
To: GCC Patches
[-- Attachment #1: Type: text/plain, Size: 295 bytes --]
I've checked in this patch to move the section that documents spec file
formats towards the end of the invoke.texi chapter, so it isn't stuck
randomly in the middle of the discussion of unrelated command-line
options. I made no changes to the text of the section being moved here.
-Sandra
[-- Attachment #2: gccdoc.log --]
[-- Type: text/x-log, Size: 166 bytes --]
2016-01-12 Sandra Loosemore <sandra@codesourcery.com>
gcc/
* doc/invoke.texi (Spec Files): Move section down in file, past
all command-line option descriptions.
[-- Attachment #3: gccdoc.patch --]
[-- Type: text/x-patch, Size: 47256 bytes --]
Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi (revision 232306)
+++ gcc/doc/invoke.texi (working copy)
@@ -146,11 +146,11 @@ only one of these two forms, whichever o
* Link Options:: Specifying libraries and so on.
* Directory Options:: Where to find header files and libraries.
Where to find the compiler executable files.
-* Spec Files:: How to pass switches to sub-processes.
* Submodel Options:: Specifying minor hardware or convention variations,
such as 68010 vs 68020.
* Code Gen Options:: Specifying conventions for function calls, data layout
and register usage.
+* Spec Files:: How to pass switches to sub-processes.
* Environment Variables:: Env vars that affect GCC.
* Precompiled Headers:: Compiling a header once, and using it many times.
@end menu
@@ -11840,586 +11840,6 @@ for header files. Thus, @option{-I-} an
independent.
@end table
-@c man end
-
-@node Spec Files
-@section Specifying Subprocesses and the Switches to Pass to Them
-@cindex Spec Files
-
-@command{gcc} is a driver program. It performs its job by invoking a
-sequence of other programs to do the work of compiling, assembling and
-linking. GCC interprets its command-line parameters and uses these to
-deduce which programs it should invoke, and which command-line options
-it ought to place on their command lines. This behavior is controlled
-by @dfn{spec strings}. In most cases there is one spec string for each
-program that GCC can invoke, but a few programs have multiple spec
-strings to control their behavior. The spec strings built into GCC can
-be overridden by using the @option{-specs=} command-line switch to specify
-a spec file.
-
-@dfn{Spec files} are plaintext files that are used to construct spec
-strings. They consist of a sequence of directives separated by blank
-lines. The type of directive is determined by the first non-whitespace
-character on the line, which can be one of the following:
-
-@table @code
-@item %@var{command}
-Issues a @var{command} to the spec file processor. The commands that can
-appear here are:
-
-@table @code
-@item %include <@var{file}>
-@cindex @code{%include}
-Search for @var{file} and insert its text at the current point in the
-specs file.
-
-@item %include_noerr <@var{file}>
-@cindex @code{%include_noerr}
-Just like @samp{%include}, but do not generate an error message if the include
-file cannot be found.
-
-@item %rename @var{old_name} @var{new_name}
-@cindex @code{%rename}
-Rename the spec string @var{old_name} to @var{new_name}.
-
-@end table
-
-@item *[@var{spec_name}]:
-This tells the compiler to create, override or delete the named spec
-string. All lines after this directive up to the next directive or
-blank line are considered to be the text for the spec string. If this
-results in an empty string then the spec is deleted. (Or, if the
-spec did not exist, then nothing happens.) Otherwise, if the spec
-does not currently exist a new spec is created. If the spec does
-exist then its contents are overridden by the text of this
-directive, unless the first character of that text is the @samp{+}
-character, in which case the text is appended to the spec.
-
-@item [@var{suffix}]:
-Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
-and up to the next directive or blank line are considered to make up the
-spec string for the indicated suffix. When the compiler encounters an
-input file with the named suffix, it processes the spec string in
-order to work out how to compile that file. For example:
-
-@smallexample
-.ZZ:
-z-compile -input %i
-@end smallexample
-
-This says that any input file whose name ends in @samp{.ZZ} should be
-passed to the program @samp{z-compile}, which should be invoked with the
-command-line switch @option{-input} and with the result of performing the
-@samp{%i} substitution. (See below.)
-
-As an alternative to providing a spec string, the text following a
-suffix directive can be one of the following:
-
-@table @code
-@item @@@var{language}
-This says that the suffix is an alias for a known @var{language}. This is
-similar to using the @option{-x} command-line switch to GCC to specify a
-language explicitly. For example:
-
-@smallexample
-.ZZ:
-@@c++
-@end smallexample
-
-Says that .ZZ files are, in fact, C++ source files.
-
-@item #@var{name}
-This causes an error messages saying:
-
-@smallexample
-@var{name} compiler not installed on this system.
-@end smallexample
-@end table
-
-GCC already has an extensive list of suffixes built into it.
-This directive adds an entry to the end of the list of suffixes, but
-since the list is searched from the end backwards, it is effectively
-possible to override earlier entries using this technique.
-
-@end table
-
-GCC has the following spec strings built into it. Spec files can
-override these strings or create their own. Note that individual
-targets can also add their own spec strings to this list.
-
-@smallexample
-asm Options to pass to the assembler
-asm_final Options to pass to the assembler post-processor
-cpp Options to pass to the C preprocessor
-cc1 Options to pass to the C compiler
-cc1plus Options to pass to the C++ compiler
-endfile Object files to include at the end of the link
-link Options to pass to the linker
-lib Libraries to include on the command line to the linker
-libgcc Decides which GCC support library to pass to the linker
-linker Sets the name of the linker
-predefines Defines to be passed to the C preprocessor
-signed_char Defines to pass to CPP to say whether @code{char} is signed
- by default
-startfile Object files to include at the start of the link
-@end smallexample
-
-Here is a small example of a spec file:
-
-@smallexample
-%rename lib old_lib
-
-*lib:
---start-group -lgcc -lc -leval1 --end-group %(old_lib)
-@end smallexample
-
-This example renames the spec called @samp{lib} to @samp{old_lib} and
-then overrides the previous definition of @samp{lib} with a new one.
-The new definition adds in some extra command-line options before
-including the text of the old definition.
-
-@dfn{Spec strings} are a list of command-line options to be passed to their
-corresponding program. In addition, the spec strings can contain
-@samp{%}-prefixed sequences to substitute variable text or to
-conditionally insert text into the command line. Using these constructs
-it is possible to generate quite complex command lines.
-
-Here is a table of all defined @samp{%}-sequences for spec
-strings. Note that spaces are not generated automatically around the
-results of expanding these sequences. Therefore you can concatenate them
-together or combine them with constant text in a single argument.
-
-@table @code
-@item %%
-Substitute one @samp{%} into the program name or argument.
-
-@item %i
-Substitute the name of the input file being processed.
-
-@item %b
-Substitute the basename of the input file being processed.
-This is the substring up to (and not including) the last period
-and not including the directory.
-
-@item %B
-This is the same as @samp{%b}, but include the file suffix (text after
-the last period).
-
-@item %d
-Marks the argument containing or following the @samp{%d} as a
-temporary file name, so that that file is deleted if GCC exits
-successfully. Unlike @samp{%g}, this contributes no text to the
-argument.
-
-@item %g@var{suffix}
-Substitute a file name that has suffix @var{suffix} and is chosen
-once per compilation, and mark the argument in the same way as
-@samp{%d}. To reduce exposure to denial-of-service attacks, the file
-name is now chosen in a way that is hard to predict even when previously
-chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
-might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
-the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
-treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
-was simply substituted with a file name chosen once per compilation,
-without regard to any appended suffix (which was therefore treated
-just like ordinary text), making such attacks more likely to succeed.
-
-@item %u@var{suffix}
-Like @samp{%g}, but generates a new temporary file name
-each time it appears instead of once per compilation.
-
-@item %U@var{suffix}
-Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
-new one if there is no such last file name. In the absence of any
-@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
-the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
-involves the generation of two distinct file names, one
-for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
-simply substituted with a file name chosen for the previous @samp{%u},
-without regard to any appended suffix.
-
-@item %j@var{suffix}
-Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
-writable, and if @option{-save-temps} is not used;
-otherwise, substitute the name
-of a temporary file, just like @samp{%u}. This temporary file is not
-meant for communication between processes, but rather as a junk
-disposal mechanism.
-
-@item %|@var{suffix}
-@itemx %m@var{suffix}
-Like @samp{%g}, except if @option{-pipe} is in effect. In that case
-@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
-all. These are the two most common ways to instruct a program that it
-should read from standard input or write to standard output. If you
-need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
-construct: see for example @file{f/lang-specs.h}.
-
-@item %.@var{SUFFIX}
-Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
-when it is subsequently output with @samp{%*}. @var{SUFFIX} is
-terminated by the next space or %.
-
-@item %w
-Marks the argument containing or following the @samp{%w} as the
-designated output file of this compilation. This puts the argument
-into the sequence of arguments that @samp{%o} substitutes.
-
-@item %o
-Substitutes the names of all the output files, with spaces
-automatically placed around them. You should write spaces
-around the @samp{%o} as well or the results are undefined.
-@samp{%o} is for use in the specs for running the linker.
-Input files whose names have no recognized suffix are not compiled
-at all, but they are included among the output files, so they are
-linked.
-
-@item %O
-Substitutes the suffix for object files. Note that this is
-handled specially when it immediately follows @samp{%g, %u, or %U},
-because of the need for those to form complete file names. The
-handling is such that @samp{%O} is treated exactly as if it had already
-been substituted, except that @samp{%g, %u, and %U} do not currently
-support additional @var{suffix} characters following @samp{%O} as they do
-following, for example, @samp{.o}.
-
-@item %p
-Substitutes the standard macro predefinitions for the
-current target machine. Use this when running @command{cpp}.
-
-@item %P
-Like @samp{%p}, but puts @samp{__} before and after the name of each
-predefined macro, except for macros that start with @samp{__} or with
-@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
-C@.
-
-@item %I
-Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
-@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
-@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
-and @option{-imultilib} as necessary.
-
-@item %s
-Current argument is the name of a library or startup file of some sort.
-Search for that file in a standard list of directories and substitute
-the full name found. The current working directory is included in the
-list of directories scanned.
-
-@item %T
-Current argument is the name of a linker script. Search for that file
-in the current list of directories to scan for libraries. If the file
-is located insert a @option{--script} option into the command line
-followed by the full path name found. If the file is not found then
-generate an error message. Note: the current working directory is not
-searched.
-
-@item %e@var{str}
-Print @var{str} as an error message. @var{str} is terminated by a newline.
-Use this when inconsistent options are detected.
-
-@item %(@var{name})
-Substitute the contents of spec string @var{name} at this point.
-
-@item %x@{@var{option}@}
-Accumulate an option for @samp{%X}.
-
-@item %X
-Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
-spec string.
-
-@item %Y
-Output the accumulated assembler options specified by @option{-Wa}.
-
-@item %Z
-Output the accumulated preprocessor options specified by @option{-Wp}.
-
-@item %a
-Process the @code{asm} spec. This is used to compute the
-switches to be passed to the assembler.
-
-@item %A
-Process the @code{asm_final} spec. This is a spec string for
-passing switches to an assembler post-processor, if such a program is
-needed.
-
-@item %l
-Process the @code{link} spec. This is the spec for computing the
-command line passed to the linker. Typically it makes use of the
-@samp{%L %G %S %D and %E} sequences.
-
-@item %D
-Dump out a @option{-L} option for each directory that GCC believes might
-contain startup files. If the target supports multilibs then the
-current multilib directory is prepended to each of these paths.
-
-@item %L
-Process the @code{lib} spec. This is a spec string for deciding which
-libraries are included on the command line to the linker.
-
-@item %G
-Process the @code{libgcc} spec. This is a spec string for deciding
-which GCC support library is included on the command line to the linker.
-
-@item %S
-Process the @code{startfile} spec. This is a spec for deciding which
-object files are the first ones passed to the linker. Typically
-this might be a file named @file{crt0.o}.
-
-@item %E
-Process the @code{endfile} spec. This is a spec string that specifies
-the last object files that are passed to the linker.
-
-@item %C
-Process the @code{cpp} spec. This is used to construct the arguments
-to be passed to the C preprocessor.
-
-@item %1
-Process the @code{cc1} spec. This is used to construct the options to be
-passed to the actual C compiler (@command{cc1}).
-
-@item %2
-Process the @code{cc1plus} spec. This is used to construct the options to be
-passed to the actual C++ compiler (@command{cc1plus}).
-
-@item %*
-Substitute the variable part of a matched option. See below.
-Note that each comma in the substituted string is replaced by
-a single space.
-
-@item %<@code{S}
-Remove all occurrences of @code{-S} from the command line. Note---this
-command is position dependent. @samp{%} commands in the spec string
-before this one see @code{-S}, @samp{%} commands in the spec string
-after this one do not.
-
-@item %:@var{function}(@var{args})
-Call the named function @var{function}, passing it @var{args}.
-@var{args} is first processed as a nested spec string, then split
-into an argument vector in the usual fashion. The function returns
-a string which is processed as if it had appeared literally as part
-of the current spec.
-
-The following built-in spec functions are provided:
-
-@table @code
-@item @code{getenv}
-The @code{getenv} spec function takes two arguments: an environment
-variable name and a string. If the environment variable is not
-defined, a fatal error is issued. Otherwise, the return value is the
-value of the environment variable concatenated with the string. For
-example, if @env{TOPDIR} is defined as @file{/path/to/top}, then:
-
-@smallexample
-%:getenv(TOPDIR /include)
-@end smallexample
-
-expands to @file{/path/to/top/include}.
-
-@item @code{if-exists}
-The @code{if-exists} spec function takes one argument, an absolute
-pathname to a file. If the file exists, @code{if-exists} returns the
-pathname. Here is a small example of its usage:
-
-@smallexample
-*startfile:
-crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
-@end smallexample
-
-@item @code{if-exists-else}
-The @code{if-exists-else} spec function is similar to the @code{if-exists}
-spec function, except that it takes two arguments. The first argument is
-an absolute pathname to a file. If the file exists, @code{if-exists-else}
-returns the pathname. If it does not exist, it returns the second argument.
-This way, @code{if-exists-else} can be used to select one file or another,
-based on the existence of the first. Here is a small example of its usage:
-
-@smallexample
-*startfile:
-crt0%O%s %:if-exists(crti%O%s) \
-%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
-@end smallexample
-
-@item @code{replace-outfile}
-The @code{replace-outfile} spec function takes two arguments. It looks for the
-first argument in the outfiles array and replaces it with the second argument. Here
-is a small example of its usage:
-
-@smallexample
-%@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
-@end smallexample
-
-@item @code{remove-outfile}
-The @code{remove-outfile} spec function takes one argument. It looks for the
-first argument in the outfiles array and removes it. Here is a small example
-its usage:
-
-@smallexample
-%:remove-outfile(-lm)
-@end smallexample
-
-@item @code{pass-through-libs}
-The @code{pass-through-libs} spec function takes any number of arguments. It
-finds any @option{-l} options and any non-options ending in @file{.a} (which it
-assumes are the names of linker input library archive files) and returns a
-result containing all the found arguments each prepended by
-@option{-plugin-opt=-pass-through=} and joined by spaces. This list is
-intended to be passed to the LTO linker plugin.
-
-@smallexample
-%:pass-through-libs(%G %L %G)
-@end smallexample
-
-@item @code{print-asm-header}
-The @code{print-asm-header} function takes no arguments and simply
-prints a banner like:
-
-@smallexample
-Assembler options
-=================
-
-Use "-Wa,OPTION" to pass "OPTION" to the assembler.
-@end smallexample
-
-It is used to separate compiler options from assembler options
-in the @option{--target-help} output.
-@end table
-
-@item %@{@code{S}@}
-Substitutes the @code{-S} switch, if that switch is given to GCC@.
-If that switch is not specified, this substitutes nothing. Note that
-the leading dash is omitted when specifying this option, and it is
-automatically inserted if the substitution is performed. Thus the spec
-string @samp{%@{foo@}} matches the command-line option @option{-foo}
-and outputs the command-line option @option{-foo}.
-
-@item %W@{@code{S}@}
-Like %@{@code{S}@} but mark last argument supplied within as a file to be
-deleted on failure.
-
-@item %@{@code{S}*@}
-Substitutes all the switches specified to GCC whose names start
-with @code{-S}, but which also take an argument. This is used for
-switches like @option{-o}, @option{-D}, @option{-I}, etc.
-GCC considers @option{-o foo} as being
-one switch whose name starts with @samp{o}. %@{o*@} substitutes this
-text, including the space. Thus two arguments are generated.
-
-@item %@{@code{S}*&@code{T}*@}
-Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
-(the order of @code{S} and @code{T} in the spec is not significant).
-There can be any number of ampersand-separated variables; for each the
-wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
-
-@item %@{@code{S}:@code{X}@}
-Substitutes @code{X}, if the @option{-S} switch is given to GCC@.
-
-@item %@{!@code{S}:@code{X}@}
-Substitutes @code{X}, if the @option{-S} switch is @emph{not} given to GCC@.
-
-@item %@{@code{S}*:@code{X}@}
-Substitutes @code{X} if one or more switches whose names start with
-@code{-S} are specified to GCC@. Normally @code{X} is substituted only
-once, no matter how many such switches appeared. However, if @code{%*}
-appears somewhere in @code{X}, then @code{X} is substituted once
-for each matching switch, with the @code{%*} replaced by the part of
-that switch matching the @code{*}.
-
-If @code{%*} appears as the last part of a spec sequence then a space
-is added after the end of the last substitution. If there is more
-text in the sequence, however, then a space is not generated. This
-allows the @code{%*} substitution to be used as part of a larger
-string. For example, a spec string like this:
-
-@smallexample
-%@{mcu=*:--script=%*/memory.ld@}
-@end smallexample
-
-@noindent
-when matching an option like @option{-mcu=newchip} produces:
-
-@smallexample
---script=newchip/memory.ld
-@end smallexample
-
-@item %@{.@code{S}:@code{X}@}
-Substitutes @code{X}, if processing a file with suffix @code{S}.
-
-@item %@{!.@code{S}:@code{X}@}
-Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
-
-@item %@{,@code{S}:@code{X}@}
-Substitutes @code{X}, if processing a file for language @code{S}.
-
-@item %@{!,@code{S}:@code{X}@}
-Substitutes @code{X}, if not processing a file for language @code{S}.
-
-@item %@{@code{S}|@code{P}:@code{X}@}
-Substitutes @code{X} if either @code{-S} or @code{-P} is given to
-GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and
-@code{*} sequences as well, although they have a stronger binding than
-the @samp{|}. If @code{%*} appears in @code{X}, all of the
-alternatives must be starred, and only the first matching alternative
-is substituted.
-
-For example, a spec string like this:
-
-@smallexample
-%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
-@end smallexample
-
-@noindent
-outputs the following command-line options from the following input
-command-line options:
-
-@smallexample
-fred.c -foo -baz
-jim.d -bar -boggle
--d fred.c -foo -baz -boggle
--d jim.d -bar -baz -boggle
-@end smallexample
-
-@item %@{S:X; T:Y; :D@}
-
-If @code{S} is given to GCC, substitutes @code{X}; else if @code{T} is
-given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
-be as many clauses as you need. This may be combined with @code{.},
-@code{,}, @code{!}, @code{|}, and @code{*} as needed.
-
-
-@end table
-
-The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
-construct may contain other nested @samp{%} constructs or spaces, or
-even newlines. They are processed as usual, as described above.
-Trailing white space in @code{X} is ignored. White space may also
-appear anywhere on the left side of the colon in these constructs,
-except between @code{.} or @code{*} and the corresponding word.
-
-The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
-handled specifically in these constructs. If another value of
-@option{-O} or the negated form of a @option{-f}, @option{-m}, or
-@option{-W} switch is found later in the command line, the earlier
-switch value is ignored, except with @{@code{S}*@} where @code{S} is
-just one letter, which passes all matching options.
-
-The character @samp{|} at the beginning of the predicate text is used to
-indicate that a command should be piped to the following command, but
-only if @option{-pipe} is specified.
-
-It is built into GCC which switches take arguments and which do not.
-(You might think it would be useful to generalize this to allow each
-compiler's spec to say which switches take arguments. But this cannot
-be done in a consistent fashion. GCC cannot even decide which input
-files have been specified without knowing which switches take arguments,
-and it must know which input files to compile in order to tell which
-compilers to run).
-
-GCC also knows implicitly that arguments starting in @option{-l} are to be
-treated as compiler output files, and passed to the linker in their
-proper position among the other output files.
-
-@c man begin OPTIONS
-
@node Submodel Options
@section Hardware Models and Configurations
@cindex submodel options
@@ -24816,6 +24236,582 @@ the implementation of the @file{libatomi
@c man end
+@node Spec Files
+@section Specifying Subprocesses and the Switches to Pass to Them
+@cindex Spec Files
+
+@command{gcc} is a driver program. It performs its job by invoking a
+sequence of other programs to do the work of compiling, assembling and
+linking. GCC interprets its command-line parameters and uses these to
+deduce which programs it should invoke, and which command-line options
+it ought to place on their command lines. This behavior is controlled
+by @dfn{spec strings}. In most cases there is one spec string for each
+program that GCC can invoke, but a few programs have multiple spec
+strings to control their behavior. The spec strings built into GCC can
+be overridden by using the @option{-specs=} command-line switch to specify
+a spec file.
+
+@dfn{Spec files} are plaintext files that are used to construct spec
+strings. They consist of a sequence of directives separated by blank
+lines. The type of directive is determined by the first non-whitespace
+character on the line, which can be one of the following:
+
+@table @code
+@item %@var{command}
+Issues a @var{command} to the spec file processor. The commands that can
+appear here are:
+
+@table @code
+@item %include <@var{file}>
+@cindex @code{%include}
+Search for @var{file} and insert its text at the current point in the
+specs file.
+
+@item %include_noerr <@var{file}>
+@cindex @code{%include_noerr}
+Just like @samp{%include}, but do not generate an error message if the include
+file cannot be found.
+
+@item %rename @var{old_name} @var{new_name}
+@cindex @code{%rename}
+Rename the spec string @var{old_name} to @var{new_name}.
+
+@end table
+
+@item *[@var{spec_name}]:
+This tells the compiler to create, override or delete the named spec
+string. All lines after this directive up to the next directive or
+blank line are considered to be the text for the spec string. If this
+results in an empty string then the spec is deleted. (Or, if the
+spec did not exist, then nothing happens.) Otherwise, if the spec
+does not currently exist a new spec is created. If the spec does
+exist then its contents are overridden by the text of this
+directive, unless the first character of that text is the @samp{+}
+character, in which case the text is appended to the spec.
+
+@item [@var{suffix}]:
+Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
+and up to the next directive or blank line are considered to make up the
+spec string for the indicated suffix. When the compiler encounters an
+input file with the named suffix, it processes the spec string in
+order to work out how to compile that file. For example:
+
+@smallexample
+.ZZ:
+z-compile -input %i
+@end smallexample
+
+This says that any input file whose name ends in @samp{.ZZ} should be
+passed to the program @samp{z-compile}, which should be invoked with the
+command-line switch @option{-input} and with the result of performing the
+@samp{%i} substitution. (See below.)
+
+As an alternative to providing a spec string, the text following a
+suffix directive can be one of the following:
+
+@table @code
+@item @@@var{language}
+This says that the suffix is an alias for a known @var{language}. This is
+similar to using the @option{-x} command-line switch to GCC to specify a
+language explicitly. For example:
+
+@smallexample
+.ZZ:
+@@c++
+@end smallexample
+
+Says that .ZZ files are, in fact, C++ source files.
+
+@item #@var{name}
+This causes an error messages saying:
+
+@smallexample
+@var{name} compiler not installed on this system.
+@end smallexample
+@end table
+
+GCC already has an extensive list of suffixes built into it.
+This directive adds an entry to the end of the list of suffixes, but
+since the list is searched from the end backwards, it is effectively
+possible to override earlier entries using this technique.
+
+@end table
+
+GCC has the following spec strings built into it. Spec files can
+override these strings or create their own. Note that individual
+targets can also add their own spec strings to this list.
+
+@smallexample
+asm Options to pass to the assembler
+asm_final Options to pass to the assembler post-processor
+cpp Options to pass to the C preprocessor
+cc1 Options to pass to the C compiler
+cc1plus Options to pass to the C++ compiler
+endfile Object files to include at the end of the link
+link Options to pass to the linker
+lib Libraries to include on the command line to the linker
+libgcc Decides which GCC support library to pass to the linker
+linker Sets the name of the linker
+predefines Defines to be passed to the C preprocessor
+signed_char Defines to pass to CPP to say whether @code{char} is signed
+ by default
+startfile Object files to include at the start of the link
+@end smallexample
+
+Here is a small example of a spec file:
+
+@smallexample
+%rename lib old_lib
+
+*lib:
+--start-group -lgcc -lc -leval1 --end-group %(old_lib)
+@end smallexample
+
+This example renames the spec called @samp{lib} to @samp{old_lib} and
+then overrides the previous definition of @samp{lib} with a new one.
+The new definition adds in some extra command-line options before
+including the text of the old definition.
+
+@dfn{Spec strings} are a list of command-line options to be passed to their
+corresponding program. In addition, the spec strings can contain
+@samp{%}-prefixed sequences to substitute variable text or to
+conditionally insert text into the command line. Using these constructs
+it is possible to generate quite complex command lines.
+
+Here is a table of all defined @samp{%}-sequences for spec
+strings. Note that spaces are not generated automatically around the
+results of expanding these sequences. Therefore you can concatenate them
+together or combine them with constant text in a single argument.
+
+@table @code
+@item %%
+Substitute one @samp{%} into the program name or argument.
+
+@item %i
+Substitute the name of the input file being processed.
+
+@item %b
+Substitute the basename of the input file being processed.
+This is the substring up to (and not including) the last period
+and not including the directory.
+
+@item %B
+This is the same as @samp{%b}, but include the file suffix (text after
+the last period).
+
+@item %d
+Marks the argument containing or following the @samp{%d} as a
+temporary file name, so that that file is deleted if GCC exits
+successfully. Unlike @samp{%g}, this contributes no text to the
+argument.
+
+@item %g@var{suffix}
+Substitute a file name that has suffix @var{suffix} and is chosen
+once per compilation, and mark the argument in the same way as
+@samp{%d}. To reduce exposure to denial-of-service attacks, the file
+name is now chosen in a way that is hard to predict even when previously
+chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
+might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
+the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
+treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
+was simply substituted with a file name chosen once per compilation,
+without regard to any appended suffix (which was therefore treated
+just like ordinary text), making such attacks more likely to succeed.
+
+@item %u@var{suffix}
+Like @samp{%g}, but generates a new temporary file name
+each time it appears instead of once per compilation.
+
+@item %U@var{suffix}
+Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
+new one if there is no such last file name. In the absence of any
+@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
+the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
+involves the generation of two distinct file names, one
+for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
+simply substituted with a file name chosen for the previous @samp{%u},
+without regard to any appended suffix.
+
+@item %j@var{suffix}
+Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
+writable, and if @option{-save-temps} is not used;
+otherwise, substitute the name
+of a temporary file, just like @samp{%u}. This temporary file is not
+meant for communication between processes, but rather as a junk
+disposal mechanism.
+
+@item %|@var{suffix}
+@itemx %m@var{suffix}
+Like @samp{%g}, except if @option{-pipe} is in effect. In that case
+@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
+all. These are the two most common ways to instruct a program that it
+should read from standard input or write to standard output. If you
+need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
+construct: see for example @file{f/lang-specs.h}.
+
+@item %.@var{SUFFIX}
+Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
+when it is subsequently output with @samp{%*}. @var{SUFFIX} is
+terminated by the next space or %.
+
+@item %w
+Marks the argument containing or following the @samp{%w} as the
+designated output file of this compilation. This puts the argument
+into the sequence of arguments that @samp{%o} substitutes.
+
+@item %o
+Substitutes the names of all the output files, with spaces
+automatically placed around them. You should write spaces
+around the @samp{%o} as well or the results are undefined.
+@samp{%o} is for use in the specs for running the linker.
+Input files whose names have no recognized suffix are not compiled
+at all, but they are included among the output files, so they are
+linked.
+
+@item %O
+Substitutes the suffix for object files. Note that this is
+handled specially when it immediately follows @samp{%g, %u, or %U},
+because of the need for those to form complete file names. The
+handling is such that @samp{%O} is treated exactly as if it had already
+been substituted, except that @samp{%g, %u, and %U} do not currently
+support additional @var{suffix} characters following @samp{%O} as they do
+following, for example, @samp{.o}.
+
+@item %p
+Substitutes the standard macro predefinitions for the
+current target machine. Use this when running @command{cpp}.
+
+@item %P
+Like @samp{%p}, but puts @samp{__} before and after the name of each
+predefined macro, except for macros that start with @samp{__} or with
+@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
+C@.
+
+@item %I
+Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
+@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
+@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
+and @option{-imultilib} as necessary.
+
+@item %s
+Current argument is the name of a library or startup file of some sort.
+Search for that file in a standard list of directories and substitute
+the full name found. The current working directory is included in the
+list of directories scanned.
+
+@item %T
+Current argument is the name of a linker script. Search for that file
+in the current list of directories to scan for libraries. If the file
+is located insert a @option{--script} option into the command line
+followed by the full path name found. If the file is not found then
+generate an error message. Note: the current working directory is not
+searched.
+
+@item %e@var{str}
+Print @var{str} as an error message. @var{str} is terminated by a newline.
+Use this when inconsistent options are detected.
+
+@item %(@var{name})
+Substitute the contents of spec string @var{name} at this point.
+
+@item %x@{@var{option}@}
+Accumulate an option for @samp{%X}.
+
+@item %X
+Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
+spec string.
+
+@item %Y
+Output the accumulated assembler options specified by @option{-Wa}.
+
+@item %Z
+Output the accumulated preprocessor options specified by @option{-Wp}.
+
+@item %a
+Process the @code{asm} spec. This is used to compute the
+switches to be passed to the assembler.
+
+@item %A
+Process the @code{asm_final} spec. This is a spec string for
+passing switches to an assembler post-processor, if such a program is
+needed.
+
+@item %l
+Process the @code{link} spec. This is the spec for computing the
+command line passed to the linker. Typically it makes use of the
+@samp{%L %G %S %D and %E} sequences.
+
+@item %D
+Dump out a @option{-L} option for each directory that GCC believes might
+contain startup files. If the target supports multilibs then the
+current multilib directory is prepended to each of these paths.
+
+@item %L
+Process the @code{lib} spec. This is a spec string for deciding which
+libraries are included on the command line to the linker.
+
+@item %G
+Process the @code{libgcc} spec. This is a spec string for deciding
+which GCC support library is included on the command line to the linker.
+
+@item %S
+Process the @code{startfile} spec. This is a spec for deciding which
+object files are the first ones passed to the linker. Typically
+this might be a file named @file{crt0.o}.
+
+@item %E
+Process the @code{endfile} spec. This is a spec string that specifies
+the last object files that are passed to the linker.
+
+@item %C
+Process the @code{cpp} spec. This is used to construct the arguments
+to be passed to the C preprocessor.
+
+@item %1
+Process the @code{cc1} spec. This is used to construct the options to be
+passed to the actual C compiler (@command{cc1}).
+
+@item %2
+Process the @code{cc1plus} spec. This is used to construct the options to be
+passed to the actual C++ compiler (@command{cc1plus}).
+
+@item %*
+Substitute the variable part of a matched option. See below.
+Note that each comma in the substituted string is replaced by
+a single space.
+
+@item %<@code{S}
+Remove all occurrences of @code{-S} from the command line. Note---this
+command is position dependent. @samp{%} commands in the spec string
+before this one see @code{-S}, @samp{%} commands in the spec string
+after this one do not.
+
+@item %:@var{function}(@var{args})
+Call the named function @var{function}, passing it @var{args}.
+@var{args} is first processed as a nested spec string, then split
+into an argument vector in the usual fashion. The function returns
+a string which is processed as if it had appeared literally as part
+of the current spec.
+
+The following built-in spec functions are provided:
+
+@table @code
+@item @code{getenv}
+The @code{getenv} spec function takes two arguments: an environment
+variable name and a string. If the environment variable is not
+defined, a fatal error is issued. Otherwise, the return value is the
+value of the environment variable concatenated with the string. For
+example, if @env{TOPDIR} is defined as @file{/path/to/top}, then:
+
+@smallexample
+%:getenv(TOPDIR /include)
+@end smallexample
+
+expands to @file{/path/to/top/include}.
+
+@item @code{if-exists}
+The @code{if-exists} spec function takes one argument, an absolute
+pathname to a file. If the file exists, @code{if-exists} returns the
+pathname. Here is a small example of its usage:
+
+@smallexample
+*startfile:
+crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
+@end smallexample
+
+@item @code{if-exists-else}
+The @code{if-exists-else} spec function is similar to the @code{if-exists}
+spec function, except that it takes two arguments. The first argument is
+an absolute pathname to a file. If the file exists, @code{if-exists-else}
+returns the pathname. If it does not exist, it returns the second argument.
+This way, @code{if-exists-else} can be used to select one file or another,
+based on the existence of the first. Here is a small example of its usage:
+
+@smallexample
+*startfile:
+crt0%O%s %:if-exists(crti%O%s) \
+%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
+@end smallexample
+
+@item @code{replace-outfile}
+The @code{replace-outfile} spec function takes two arguments. It looks for the
+first argument in the outfiles array and replaces it with the second argument. Here
+is a small example of its usage:
+
+@smallexample
+%@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
+@end smallexample
+
+@item @code{remove-outfile}
+The @code{remove-outfile} spec function takes one argument. It looks for the
+first argument in the outfiles array and removes it. Here is a small example
+its usage:
+
+@smallexample
+%:remove-outfile(-lm)
+@end smallexample
+
+@item @code{pass-through-libs}
+The @code{pass-through-libs} spec function takes any number of arguments. It
+finds any @option{-l} options and any non-options ending in @file{.a} (which it
+assumes are the names of linker input library archive files) and returns a
+result containing all the found arguments each prepended by
+@option{-plugin-opt=-pass-through=} and joined by spaces. This list is
+intended to be passed to the LTO linker plugin.
+
+@smallexample
+%:pass-through-libs(%G %L %G)
+@end smallexample
+
+@item @code{print-asm-header}
+The @code{print-asm-header} function takes no arguments and simply
+prints a banner like:
+
+@smallexample
+Assembler options
+=================
+
+Use "-Wa,OPTION" to pass "OPTION" to the assembler.
+@end smallexample
+
+It is used to separate compiler options from assembler options
+in the @option{--target-help} output.
+@end table
+
+@item %@{@code{S}@}
+Substitutes the @code{-S} switch, if that switch is given to GCC@.
+If that switch is not specified, this substitutes nothing. Note that
+the leading dash is omitted when specifying this option, and it is
+automatically inserted if the substitution is performed. Thus the spec
+string @samp{%@{foo@}} matches the command-line option @option{-foo}
+and outputs the command-line option @option{-foo}.
+
+@item %W@{@code{S}@}
+Like %@{@code{S}@} but mark last argument supplied within as a file to be
+deleted on failure.
+
+@item %@{@code{S}*@}
+Substitutes all the switches specified to GCC whose names start
+with @code{-S}, but which also take an argument. This is used for
+switches like @option{-o}, @option{-D}, @option{-I}, etc.
+GCC considers @option{-o foo} as being
+one switch whose name starts with @samp{o}. %@{o*@} substitutes this
+text, including the space. Thus two arguments are generated.
+
+@item %@{@code{S}*&@code{T}*@}
+Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
+(the order of @code{S} and @code{T} in the spec is not significant).
+There can be any number of ampersand-separated variables; for each the
+wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
+
+@item %@{@code{S}:@code{X}@}
+Substitutes @code{X}, if the @option{-S} switch is given to GCC@.
+
+@item %@{!@code{S}:@code{X}@}
+Substitutes @code{X}, if the @option{-S} switch is @emph{not} given to GCC@.
+
+@item %@{@code{S}*:@code{X}@}
+Substitutes @code{X} if one or more switches whose names start with
+@code{-S} are specified to GCC@. Normally @code{X} is substituted only
+once, no matter how many such switches appeared. However, if @code{%*}
+appears somewhere in @code{X}, then @code{X} is substituted once
+for each matching switch, with the @code{%*} replaced by the part of
+that switch matching the @code{*}.
+
+If @code{%*} appears as the last part of a spec sequence then a space
+is added after the end of the last substitution. If there is more
+text in the sequence, however, then a space is not generated. This
+allows the @code{%*} substitution to be used as part of a larger
+string. For example, a spec string like this:
+
+@smallexample
+%@{mcu=*:--script=%*/memory.ld@}
+@end smallexample
+
+@noindent
+when matching an option like @option{-mcu=newchip} produces:
+
+@smallexample
+--script=newchip/memory.ld
+@end smallexample
+
+@item %@{.@code{S}:@code{X}@}
+Substitutes @code{X}, if processing a file with suffix @code{S}.
+
+@item %@{!.@code{S}:@code{X}@}
+Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
+
+@item %@{,@code{S}:@code{X}@}
+Substitutes @code{X}, if processing a file for language @code{S}.
+
+@item %@{!,@code{S}:@code{X}@}
+Substitutes @code{X}, if not processing a file for language @code{S}.
+
+@item %@{@code{S}|@code{P}:@code{X}@}
+Substitutes @code{X} if either @code{-S} or @code{-P} is given to
+GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and
+@code{*} sequences as well, although they have a stronger binding than
+the @samp{|}. If @code{%*} appears in @code{X}, all of the
+alternatives must be starred, and only the first matching alternative
+is substituted.
+
+For example, a spec string like this:
+
+@smallexample
+%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
+@end smallexample
+
+@noindent
+outputs the following command-line options from the following input
+command-line options:
+
+@smallexample
+fred.c -foo -baz
+jim.d -bar -boggle
+-d fred.c -foo -baz -boggle
+-d jim.d -bar -baz -boggle
+@end smallexample
+
+@item %@{S:X; T:Y; :D@}
+
+If @code{S} is given to GCC, substitutes @code{X}; else if @code{T} is
+given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
+be as many clauses as you need. This may be combined with @code{.},
+@code{,}, @code{!}, @code{|}, and @code{*} as needed.
+
+
+@end table
+
+The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
+construct may contain other nested @samp{%} constructs or spaces, or
+even newlines. They are processed as usual, as described above.
+Trailing white space in @code{X} is ignored. White space may also
+appear anywhere on the left side of the colon in these constructs,
+except between @code{.} or @code{*} and the corresponding word.
+
+The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
+handled specifically in these constructs. If another value of
+@option{-O} or the negated form of a @option{-f}, @option{-m}, or
+@option{-W} switch is found later in the command line, the earlier
+switch value is ignored, except with @{@code{S}*@} where @code{S} is
+just one letter, which passes all matching options.
+
+The character @samp{|} at the beginning of the predicate text is used to
+indicate that a command should be piped to the following command, but
+only if @option{-pipe} is specified.
+
+It is built into GCC which switches take arguments and which do not.
+(You might think it would be useful to generalize this to allow each
+compiler's spec to say which switches take arguments. But this cannot
+be done in a consistent fashion. GCC cannot even decide which input
+files have been specified without knowing which switches take arguments,
+and it must know which input files to compile in order to tell which
+compilers to run).
+
+GCC also knows implicitly that arguments starting in @option{-l} are to be
+treated as compiler output files, and passed to the linker in their
+proper position among the other output files.
+
@node Environment Variables
@section Environment Variables Affecting GCC
@cindex environment variables
^ permalink raw reply [flat|nested] 12+ messages in thread* [doc, 3/n] invoke.texi: move "Code Gen Options" before target-specific options
2016-01-10 23:50 [doc, 0/n] improve organization of invoke.texi Sandra Loosemore
` (2 preceding siblings ...)
2016-01-13 3:31 ` [doc, 2/n] invoke.texi: move spec file section Sandra Loosemore
@ 2016-01-13 21:08 ` Sandra Loosemore
2016-01-25 0:16 ` Gerald Pfeifer
2016-01-13 23:38 ` [doc, 3.5/n] invoke.texi: rename "Machine-Dependent Options" section Sandra Loosemore
` (3 subsequent siblings)
7 siblings, 1 reply; 12+ messages in thread
From: Sandra Loosemore @ 2016-01-13 21:08 UTC (permalink / raw)
To: GCC Patches
[-- Attachment #1: Type: text/plain, Size: 328 bytes --]
Here is the next installment of my series to make things easier to find
in invoke.texi. I've checked in this patch to move the "Code Gen
Options" up in the file so that all target-independent options are
documented ahead of the target-specific ones. I did not make any
changes to the text, just moved it around.
-Sandra
[-- Attachment #2: gccdoc.log --]
[-- Type: text/x-log, Size: 229 bytes --]
2016-01-13 Sandra Loosemore <sandra@codesourcery.com>
gcc/
* doc/invoke.texi (Code Gen Options): Move section up in file,
before target-specific options. Update menu and option summary
to reflect the new section ordering.
[-- Attachment #3: gccdoc.patch --]
[-- Type: text/x-patch, Size: 70102 bytes --]
Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi (revision 232350)
+++ gcc/doc/invoke.texi (working copy)
@@ -146,10 +146,10 @@ only one of these two forms, whichever o
* Link Options:: Specifying libraries and so on.
* Directory Options:: Where to find header files and libraries.
Where to find the compiler executable files.
-* Submodel Options:: Specifying minor hardware or convention variations,
- such as 68010 vs 68020.
* Code Gen Options:: Specifying conventions for function calls, data layout
and register usage.
+* Submodel Options:: Specifying minor hardware or convention variations,
+ such as 68010 vs 68020.
* Spec Files:: How to pass switches to sub-processes.
* Environment Variables:: Env vars that affect GCC.
* Precompiled Headers:: Compiling a header once, and using it many times.
@@ -516,6 +516,31 @@ Objective-C and Objective-C++ Dialects}.
-iquote@var{dir} -L@var{dir} -no-canonical-prefixes -I- @gol
--sysroot=@var{dir} --no-sysroot-suffix}
+@item Code Generation Options
+@xref{Code Gen Options,,Options for Code Generation Conventions}.
+@gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
+-ffixed-@var{reg} -fexceptions @gol
+-fnon-call-exceptions -fdelete-dead-exceptions -funwind-tables @gol
+-fasynchronous-unwind-tables @gol
+-fno-gnu-unique @gol
+-finhibit-size-directive -finstrument-functions @gol
+-finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol
+-finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} @gol
+-fno-common -fno-ident @gol
+-fpcc-struct-return -fpic -fPIC -fpie -fPIE -fno-plt @gol
+-fno-jump-tables @gol
+-frecord-gcc-switches @gol
+-freg-struct-return -fshort-enums @gol
+-fshort-double -fshort-wchar @gol
+-fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
+-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
+-fno-stack-limit -fsplit-stack @gol
+-fleading-underscore -ftls-model=@var{model} @gol
+-fstack-reuse=@var{reuse_level} @gol
+-ftrapv -fwrapv -fbounds-check @gol
+-fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} @gol
+-fstrict-volatile-bitfields -fsync-libcalls}
+
@item Machine Dependent Options
@xref{Submodel Options,,Hardware Models and Configurations}.
@c This list is ordered alphanumerically by subsection name.
@@ -1150,31 +1175,6 @@ See RS/6000 and PowerPC Options.
@emph{zSeries Options}
See S/390 and zSeries Options.
-
-@item Code Generation Options
-@xref{Code Gen Options,,Options for Code Generation Conventions}.
-@gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
--ffixed-@var{reg} -fexceptions @gol
--fnon-call-exceptions -fdelete-dead-exceptions -funwind-tables @gol
--fasynchronous-unwind-tables @gol
--fno-gnu-unique @gol
--finhibit-size-directive -finstrument-functions @gol
--finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol
--finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} @gol
--fno-common -fno-ident @gol
--fpcc-struct-return -fpic -fPIC -fpie -fPIE -fno-plt @gol
--fno-jump-tables @gol
--frecord-gcc-switches @gol
--freg-struct-return -fshort-enums @gol
--fshort-double -fshort-wchar @gol
--fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
--fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
--fno-stack-limit -fsplit-stack @gol
--fleading-underscore -ftls-model=@var{model} @gol
--fstack-reuse=@var{reuse_level} @gol
--ftrapv -fwrapv -fbounds-check @gol
--fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} @gol
--fstrict-volatile-bitfields -fsync-libcalls}
@end table
@@ -11845,6 +11845,729 @@ for header files. Thus, @option{-I-} an
independent.
@end table
+@node Code Gen Options
+@section Options for Code Generation Conventions
+@cindex code generation conventions
+@cindex options, code generation
+@cindex run-time options
+
+These machine-independent options control the interface conventions
+used in code generation.
+
+Most of them have both positive and negative forms; the negative form
+of @option{-ffoo} is @option{-fno-foo}. In the table below, only
+one of the forms is listed---the one that is not the default. You
+can figure out the other form by either removing @samp{no-} or adding
+it.
+
+@table @gcctabopt
+@item -fbounds-check
+@opindex fbounds-check
+For front ends that support it, generate additional code to check that
+indices used to access arrays are within the declared range. This is
+currently only supported by the Java and Fortran front ends, where
+this option defaults to true and false respectively.
+
+@item -fstack-reuse=@var{reuse-level}
+@opindex fstack_reuse
+This option controls stack space reuse for user declared local/auto variables
+and compiler generated temporaries. @var{reuse_level} can be @samp{all},
+@samp{named_vars}, or @samp{none}. @samp{all} enables stack reuse for all
+local variables and temporaries, @samp{named_vars} enables the reuse only for
+user defined local variables with names, and @samp{none} disables stack reuse
+completely. The default value is @samp{all}. The option is needed when the
+program extends the lifetime of a scoped local variable or a compiler generated
+temporary beyond the end point defined by the language. When a lifetime of
+a variable ends, and if the variable lives in memory, the optimizing compiler
+has the freedom to reuse its stack space with other temporaries or scoped
+local variables whose live range does not overlap with it. Legacy code extending
+local lifetime is likely to break with the stack reuse optimization.
+
+For example,
+
+@smallexample
+ int *p;
+ @{
+ int local1;
+
+ p = &local1;
+ local1 = 10;
+ ....
+ @}
+ @{
+ int local2;
+ local2 = 20;
+ ...
+ @}
+
+ if (*p == 10) // out of scope use of local1
+ @{
+
+ @}
+@end smallexample
+
+Another example:
+@smallexample
+
+ struct A
+ @{
+ A(int k) : i(k), j(k) @{ @}
+ int i;
+ int j;
+ @};
+
+ A *ap;
+
+ void foo(const A& ar)
+ @{
+ ap = &ar;
+ @}
+
+ void bar()
+ @{
+ foo(A(10)); // temp object's lifetime ends when foo returns
+
+ @{
+ A a(20);
+ ....
+ @}
+ ap->i+= 10; // ap references out of scope temp whose space
+ // is reused with a. What is the value of ap->i?
+ @}
+
+@end smallexample
+
+The lifetime of a compiler generated temporary is well defined by the C++
+standard. When a lifetime of a temporary ends, and if the temporary lives
+in memory, the optimizing compiler has the freedom to reuse its stack
+space with other temporaries or scoped local variables whose live range
+does not overlap with it. However some of the legacy code relies on
+the behavior of older compilers in which temporaries' stack space is
+not reused, the aggressive stack reuse can lead to runtime errors. This
+option is used to control the temporary stack reuse optimization.
+
+@item -ftrapv
+@opindex ftrapv
+This option generates traps for signed overflow on addition, subtraction,
+multiplication operations.
+The options @option{-ftrapv} and @option{-fwrapv} override each other, so using
+@option{-ftrapv} @option{-fwrapv} on the command-line results in
+@option{-fwrapv} being effective. Note that only active options override, so
+using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line
+results in @option{-ftrapv} being effective.
+
+@item -fwrapv
+@opindex fwrapv
+This option instructs the compiler to assume that signed arithmetic
+overflow of addition, subtraction and multiplication wraps around
+using twos-complement representation. This flag enables some optimizations
+and disables others. This option is enabled by default for the Java
+front end, as required by the Java language specification.
+The options @option{-ftrapv} and @option{-fwrapv} override each other, so using
+@option{-ftrapv} @option{-fwrapv} on the command-line results in
+@option{-fwrapv} being effective. Note that only active options override, so
+using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line
+results in @option{-ftrapv} being effective.
+
+@item -fexceptions
+@opindex fexceptions
+Enable exception handling. Generates extra code needed to propagate
+exceptions. For some targets, this implies GCC generates frame
+unwind information for all functions, which can produce significant data
+size overhead, although it does not affect execution. If you do not
+specify this option, GCC enables it by default for languages like
+C++ that normally require exception handling, and disables it for
+languages like C that do not normally require it. However, you may need
+to enable this option when compiling C code that needs to interoperate
+properly with exception handlers written in C++. You may also wish to
+disable this option if you are compiling older C++ programs that don't
+use exception handling.
+
+@item -fnon-call-exceptions
+@opindex fnon-call-exceptions
+Generate code that allows trapping instructions to throw exceptions.
+Note that this requires platform-specific runtime support that does
+not exist everywhere. Moreover, it only allows @emph{trapping}
+instructions to throw exceptions, i.e.@: memory references or floating-point
+instructions. It does not allow exceptions to be thrown from
+arbitrary signal handlers such as @code{SIGALRM}.
+
+@item -fdelete-dead-exceptions
+@opindex fdelete-dead-exceptions
+Consider that instructions that may throw exceptions but don't otherwise
+contribute to the execution of the program can be optimized away.
+This option is enabled by default for the Ada front end, as permitted by
+the Ada language specification.
+Optimization passes that cause dead exceptions to be removed are enabled independently at different optimization levels.
+
+@item -funwind-tables
+@opindex funwind-tables
+Similar to @option{-fexceptions}, except that it just generates any needed
+static data, but does not affect the generated code in any other way.
+You normally do not need to enable this option; instead, a language processor
+that needs this handling enables it on your behalf.
+
+@item -fasynchronous-unwind-tables
+@opindex fasynchronous-unwind-tables
+Generate unwind table in DWARF 2 format, if supported by target machine. The
+table is exact at each instruction boundary, so it can be used for stack
+unwinding from asynchronous events (such as debugger or garbage collector).
+
+@item -fno-gnu-unique
+@opindex fno-gnu-unique
+On systems with recent GNU assembler and C library, the C++ compiler
+uses the @code{STB_GNU_UNIQUE} binding to make sure that definitions
+of template static data members and static local variables in inline
+functions are unique even in the presence of @code{RTLD_LOCAL}; this
+is necessary to avoid problems with a library used by two different
+@code{RTLD_LOCAL} plugins depending on a definition in one of them and
+therefore disagreeing with the other one about the binding of the
+symbol. But this causes @code{dlclose} to be ignored for affected
+DSOs; if your program relies on reinitialization of a DSO via
+@code{dlclose} and @code{dlopen}, you can use
+@option{-fno-gnu-unique}.
+
+@item -fpcc-struct-return
+@opindex fpcc-struct-return
+Return ``short'' @code{struct} and @code{union} values in memory like
+longer ones, rather than in registers. This convention is less
+efficient, but it has the advantage of allowing intercallability between
+GCC-compiled files and files compiled with other compilers, particularly
+the Portable C Compiler (pcc).
+
+The precise convention for returning structures in memory depends
+on the target configuration macros.
+
+Short structures and unions are those whose size and alignment match
+that of some integer type.
+
+@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
+switch is not binary compatible with code compiled with the
+@option{-freg-struct-return} switch.
+Use it to conform to a non-default application binary interface.
+
+@item -freg-struct-return
+@opindex freg-struct-return
+Return @code{struct} and @code{union} values in registers when possible.
+This is more efficient for small structures than
+@option{-fpcc-struct-return}.
+
+If you specify neither @option{-fpcc-struct-return} nor
+@option{-freg-struct-return}, GCC defaults to whichever convention is
+standard for the target. If there is no standard convention, GCC
+defaults to @option{-fpcc-struct-return}, except on targets where GCC is
+the principal compiler. In those cases, we can choose the standard, and
+we chose the more efficient register return alternative.
+
+@strong{Warning:} code compiled with the @option{-freg-struct-return}
+switch is not binary compatible with code compiled with the
+@option{-fpcc-struct-return} switch.
+Use it to conform to a non-default application binary interface.
+
+@item -fshort-enums
+@opindex fshort-enums
+Allocate to an @code{enum} type only as many bytes as it needs for the
+declared range of possible values. Specifically, the @code{enum} type
+is equivalent to the smallest integer type that has enough room.
+
+@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
+code that is not binary compatible with code generated without that switch.
+Use it to conform to a non-default application binary interface.
+
+@item -fshort-double
+@opindex fshort-double
+Use the same size for @code{double} as for @code{float}.
+
+@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
+code that is not binary compatible with code generated without that switch.
+Use it to conform to a non-default application binary interface.
+
+@item -fshort-wchar
+@opindex fshort-wchar
+Override the underlying type for @code{wchar_t} to be @code{short
+unsigned int} instead of the default for the target. This option is
+useful for building programs to run under WINE@.
+
+@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
+code that is not binary compatible with code generated without that switch.
+Use it to conform to a non-default application binary interface.
+
+@item -fno-common
+@opindex fno-common
+In C code, controls the placement of uninitialized global variables.
+Unix C compilers have traditionally permitted multiple definitions of
+such variables in different compilation units by placing the variables
+in a common block.
+This is the behavior specified by @option{-fcommon}, and is the default
+for GCC on most targets.
+On the other hand, this behavior is not required by ISO C, and on some
+targets may carry a speed or code size penalty on variable references.
+The @option{-fno-common} option specifies that the compiler should place
+uninitialized global variables in the data section of the object file,
+rather than generating them as common blocks.
+This has the effect that if the same variable is declared
+(without @code{extern}) in two different compilations,
+you get a multiple-definition error when you link them.
+In this case, you must compile with @option{-fcommon} instead.
+Compiling with @option{-fno-common} is useful on targets for which
+it provides better performance, or if you wish to verify that the
+program will work on other systems that always treat uninitialized
+variable declarations this way.
+
+@item -fno-ident
+@opindex fno-ident
+Ignore the @code{#ident} directive.
+
+@item -finhibit-size-directive
+@opindex finhibit-size-directive
+Don't output a @code{.size} assembler directive, or anything else that
+would cause trouble if the function is split in the middle, and the
+two halves are placed at locations far apart in memory. This option is
+used when compiling @file{crtstuff.c}; you should not need to use it
+for anything else.
+
+@item -fverbose-asm
+@opindex fverbose-asm
+Put extra commentary information in the generated assembly code to
+make it more readable. This option is generally only of use to those
+who actually need to read the generated assembly code (perhaps while
+debugging the compiler itself).
+
+@option{-fno-verbose-asm}, the default, causes the
+extra information to be omitted and is useful when comparing two assembler
+files.
+
+@item -frecord-gcc-switches
+@opindex frecord-gcc-switches
+This switch causes the command line used to invoke the
+compiler to be recorded into the object file that is being created.
+This switch is only implemented on some targets and the exact format
+of the recording is target and binary file format dependent, but it
+usually takes the form of a section containing ASCII text. This
+switch is related to the @option{-fverbose-asm} switch, but that
+switch only records information in the assembler output file as
+comments, so it never reaches the object file.
+See also @option{-grecord-gcc-switches} for another
+way of storing compiler options into the object file.
+
+@item -fpic
+@opindex fpic
+@cindex global offset table
+@cindex PIC
+Generate position-independent code (PIC) suitable for use in a shared
+library, if supported for the target machine. Such code accesses all
+constant addresses through a global offset table (GOT)@. The dynamic
+loader resolves the GOT entries when the program starts (the dynamic
+loader is not part of GCC; it is part of the operating system). If
+the GOT size for the linked executable exceeds a machine-specific
+maximum size, you get an error message from the linker indicating that
+@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
+instead. (These maximums are 8k on the SPARC, 28k on AArch64 and 32k
+on the m68k and RS/6000. The x86 has no such limit.)
+
+Position-independent code requires special support, and therefore works
+only on certain machines. For the x86, GCC supports PIC for System V
+but not for the Sun 386i. Code generated for the IBM RS/6000 is always
+position-independent.
+
+When this flag is set, the macros @code{__pic__} and @code{__PIC__}
+are defined to 1.
+
+@item -fPIC
+@opindex fPIC
+If supported for the target machine, emit position-independent code,
+suitable for dynamic linking and avoiding any limit on the size of the
+global offset table. This option makes a difference on AArch64, m68k,
+PowerPC and SPARC@.
+
+Position-independent code requires special support, and therefore works
+only on certain machines.
+
+When this flag is set, the macros @code{__pic__} and @code{__PIC__}
+are defined to 2.
+
+@item -fpie
+@itemx -fPIE
+@opindex fpie
+@opindex fPIE
+These options are similar to @option{-fpic} and @option{-fPIC}, but
+generated position independent code can be only linked into executables.
+Usually these options are used when @option{-pie} GCC option is
+used during linking.
+
+@option{-fpie} and @option{-fPIE} both define the macros
+@code{__pie__} and @code{__PIE__}. The macros have the value 1
+for @option{-fpie} and 2 for @option{-fPIE}.
+
+@item -fno-plt
+@opindex fno-plt
+Do not use the PLT for external function calls in position-independent code.
+Instead, load the callee address at call sites from the GOT and branch to it.
+This leads to more efficient code by eliminating PLT stubs and exposing
+GOT loads to optimizations. On architectures such as 32-bit x86 where
+PLT stubs expect the GOT pointer in a specific register, this gives more
+register allocation freedom to the compiler.
+Lazy binding requires use of the PLT;
+with @option{-fno-plt} all external symbols are resolved at load time.
+
+Alternatively, the function attribute @code{noplt} can be used to avoid calls
+through the PLT for specific external functions.
+
+In position-dependent code, a few targets also convert calls to
+functions that are marked to not use the PLT to use the GOT instead.
+
+@item -fno-jump-tables
+@opindex fno-jump-tables
+Do not use jump tables for switch statements even where it would be
+more efficient than other code generation strategies. This option is
+of use in conjunction with @option{-fpic} or @option{-fPIC} for
+building code that forms part of a dynamic linker and cannot
+reference the address of a jump table. On some targets, jump tables
+do not require a GOT and this option is not needed.
+
+@item -ffixed-@var{reg}
+@opindex ffixed
+Treat the register named @var{reg} as a fixed register; generated code
+should never refer to it (except perhaps as a stack pointer, frame
+pointer or in some other fixed role).
+
+@var{reg} must be the name of a register. The register names accepted
+are machine-specific and are defined in the @code{REGISTER_NAMES}
+macro in the machine description macro file.
+
+This flag does not have a negative form, because it specifies a
+three-way choice.
+
+@item -fcall-used-@var{reg}
+@opindex fcall-used
+Treat the register named @var{reg} as an allocable register that is
+clobbered by function calls. It may be allocated for temporaries or
+variables that do not live across a call. Functions compiled this way
+do not save and restore the register @var{reg}.
+
+It is an error to use this flag with the frame pointer or stack pointer.
+Use of this flag for other registers that have fixed pervasive roles in
+the machine's execution model produces disastrous results.
+
+This flag does not have a negative form, because it specifies a
+three-way choice.
+
+@item -fcall-saved-@var{reg}
+@opindex fcall-saved
+Treat the register named @var{reg} as an allocable register saved by
+functions. It may be allocated even for temporaries or variables that
+live across a call. Functions compiled this way save and restore
+the register @var{reg} if they use it.
+
+It is an error to use this flag with the frame pointer or stack pointer.
+Use of this flag for other registers that have fixed pervasive roles in
+the machine's execution model produces disastrous results.
+
+A different sort of disaster results from the use of this flag for
+a register in which function values may be returned.
+
+This flag does not have a negative form, because it specifies a
+three-way choice.
+
+@item -fpack-struct[=@var{n}]
+@opindex fpack-struct
+Without a value specified, pack all structure members together without
+holes. When a value is specified (which must be a small power of two), pack
+structure members according to this value, representing the maximum
+alignment (that is, objects with default alignment requirements larger than
+this are output potentially unaligned at the next fitting location.
+
+@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
+code that is not binary compatible with code generated without that switch.
+Additionally, it makes the code suboptimal.
+Use it to conform to a non-default application binary interface.
+
+@item -finstrument-functions
+@opindex finstrument-functions
+Generate instrumentation calls for entry and exit to functions. Just
+after function entry and just before function exit, the following
+profiling functions are called with the address of the current
+function and its call site. (On some platforms,
+@code{__builtin_return_address} does not work beyond the current
+function, so the call site information may not be available to the
+profiling functions otherwise.)
+
+@smallexample
+void __cyg_profile_func_enter (void *this_fn,
+ void *call_site);
+void __cyg_profile_func_exit (void *this_fn,
+ void *call_site);
+@end smallexample
+
+The first argument is the address of the start of the current function,
+which may be looked up exactly in the symbol table.
+
+This instrumentation is also done for functions expanded inline in other
+functions. The profiling calls indicate where, conceptually, the
+inline function is entered and exited. This means that addressable
+versions of such functions must be available. If all your uses of a
+function are expanded inline, this may mean an additional expansion of
+code size. If you use @code{extern inline} in your C code, an
+addressable version of such functions must be provided. (This is
+normally the case anyway, but if you get lucky and the optimizer always
+expands the functions inline, you might have gotten away without
+providing static copies.)
+
+A function may be given the attribute @code{no_instrument_function}, in
+which case this instrumentation is not done. This can be used, for
+example, for the profiling functions listed above, high-priority
+interrupt routines, and any functions from which the profiling functions
+cannot safely be called (perhaps signal handlers, if the profiling
+routines generate output or allocate memory).
+
+@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
+@opindex finstrument-functions-exclude-file-list
+
+Set the list of functions that are excluded from instrumentation (see
+the description of @option{-finstrument-functions}). If the file that
+contains a function definition matches with one of @var{file}, then
+that function is not instrumented. The match is done on substrings:
+if the @var{file} parameter is a substring of the file name, it is
+considered to be a match.
+
+For example:
+
+@smallexample
+-finstrument-functions-exclude-file-list=/bits/stl,include/sys
+@end smallexample
+
+@noindent
+excludes any inline function defined in files whose pathnames
+contain @file{/bits/stl} or @file{include/sys}.
+
+If, for some reason, you want to include letter @samp{,} in one of
+@var{sym}, write @samp{\,}. For example,
+@option{-finstrument-functions-exclude-file-list='\,\,tmp'}
+(note the single quote surrounding the option).
+
+@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
+@opindex finstrument-functions-exclude-function-list
+
+This is similar to @option{-finstrument-functions-exclude-file-list},
+but this option sets the list of function names to be excluded from
+instrumentation. The function name to be matched is its user-visible
+name, such as @code{vector<int> blah(const vector<int> &)}, not the
+internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
+match is done on substrings: if the @var{sym} parameter is a substring
+of the function name, it is considered to be a match. For C99 and C++
+extended identifiers, the function name must be given in UTF-8, not
+using universal character names.
+
+@item -fstack-check
+@opindex fstack-check
+Generate code to verify that you do not go beyond the boundary of the
+stack. You should specify this flag if you are running in an
+environment with multiple threads, but you only rarely need to specify it in
+a single-threaded environment since stack overflow is automatically
+detected on nearly all systems if there is only one stack.
+
+Note that this switch does not actually cause checking to be done; the
+operating system or the language runtime must do that. The switch causes
+generation of code to ensure that they see the stack being extended.
+
+You can additionally specify a string parameter: @samp{no} means no
+checking, @samp{generic} means force the use of old-style checking,
+@samp{specific} means use the best checking method and is equivalent
+to bare @option{-fstack-check}.
+
+Old-style checking is a generic mechanism that requires no specific
+target support in the compiler but comes with the following drawbacks:
+
+@enumerate
+@item
+Modified allocation strategy for large objects: they are always
+allocated dynamically if their size exceeds a fixed threshold.
+
+@item
+Fixed limit on the size of the static frame of functions: when it is
+topped by a particular function, stack checking is not reliable and
+a warning is issued by the compiler.
+
+@item
+Inefficiency: because of both the modified allocation strategy and the
+generic implementation, code performance is hampered.
+@end enumerate
+
+Note that old-style stack checking is also the fallback method for
+@samp{specific} if no target support has been added in the compiler.
+
+@item -fstack-limit-register=@var{reg}
+@itemx -fstack-limit-symbol=@var{sym}
+@itemx -fno-stack-limit
+@opindex fstack-limit-register
+@opindex fstack-limit-symbol
+@opindex fno-stack-limit
+Generate code to ensure that the stack does not grow beyond a certain value,
+either the value of a register or the address of a symbol. If a larger
+stack is required, a signal is raised at run time. For most targets,
+the signal is raised before the stack overruns the boundary, so
+it is possible to catch the signal without taking special precautions.
+
+For instance, if the stack starts at absolute address @samp{0x80000000}
+and grows downwards, you can use the flags
+@option{-fstack-limit-symbol=__stack_limit} and
+@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
+of 128KB@. Note that this may only work with the GNU linker.
+
+You can locally override stack limit checking by using the
+@code{no_stack_limit} function attribute (@pxref{Function Attributes}).
+
+@item -fsplit-stack
+@opindex fsplit-stack
+Generate code to automatically split the stack before it overflows.
+The resulting program has a discontiguous stack which can only
+overflow if the program is unable to allocate any more memory. This
+is most useful when running threaded programs, as it is no longer
+necessary to calculate a good stack size to use for each thread. This
+is currently only implemented for the x86 targets running
+GNU/Linux.
+
+When code compiled with @option{-fsplit-stack} calls code compiled
+without @option{-fsplit-stack}, there may not be much stack space
+available for the latter code to run. If compiling all code,
+including library code, with @option{-fsplit-stack} is not an option,
+then the linker can fix up these calls so that the code compiled
+without @option{-fsplit-stack} always has a large stack. Support for
+this is implemented in the gold linker in GNU binutils release 2.21
+and later.
+
+@item -fleading-underscore
+@opindex fleading-underscore
+This option and its counterpart, @option{-fno-leading-underscore}, forcibly
+change the way C symbols are represented in the object file. One use
+is to help link with legacy assembly code.
+
+@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
+generate code that is not binary compatible with code generated without that
+switch. Use it to conform to a non-default application binary interface.
+Not all targets provide complete support for this switch.
+
+@item -ftls-model=@var{model}
+@opindex ftls-model
+Alter the thread-local storage model to be used (@pxref{Thread-Local}).
+The @var{model} argument should be one of @samp{global-dynamic},
+@samp{local-dynamic}, @samp{initial-exec} or @samp{local-exec}.
+Note that the choice is subject to optimization: the compiler may use
+a more efficient model for symbols not visible outside of the translation
+unit, or if @option{-fpic} is not given on the command line.
+
+The default without @option{-fpic} is @samp{initial-exec}; with
+@option{-fpic} the default is @samp{global-dynamic}.
+
+@item -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]}
+@opindex fvisibility
+Set the default ELF image symbol visibility to the specified option---all
+symbols are marked with this unless overridden within the code.
+Using this feature can very substantially improve linking and
+load times of shared object libraries, produce more optimized
+code, provide near-perfect API export and prevent symbol clashes.
+It is @strong{strongly} recommended that you use this in any shared objects
+you distribute.
+
+Despite the nomenclature, @samp{default} always means public; i.e.,
+available to be linked against from outside the shared object.
+@samp{protected} and @samp{internal} are pretty useless in real-world
+usage so the only other commonly used option is @samp{hidden}.
+The default if @option{-fvisibility} isn't specified is
+@samp{default}, i.e., make every symbol public.
+
+A good explanation of the benefits offered by ensuring ELF
+symbols have the correct visibility is given by ``How To Write
+Shared Libraries'' by Ulrich Drepper (which can be found at
+@w{@uref{http://www.akkadia.org/drepper/}})---however a superior
+solution made possible by this option to marking things hidden when
+the default is public is to make the default hidden and mark things
+public. This is the norm with DLLs on Windows and with @option{-fvisibility=hidden}
+and @code{__attribute__ ((visibility("default")))} instead of
+@code{__declspec(dllexport)} you get almost identical semantics with
+identical syntax. This is a great boon to those working with
+cross-platform projects.
+
+For those adding visibility support to existing code, you may find
+@code{#pragma GCC visibility} of use. This works by you enclosing
+the declarations you wish to set visibility for with (for example)
+@code{#pragma GCC visibility push(hidden)} and
+@code{#pragma GCC visibility pop}.
+Bear in mind that symbol visibility should be viewed @strong{as
+part of the API interface contract} and thus all new code should
+always specify visibility when it is not the default; i.e., declarations
+only for use within the local DSO should @strong{always} be marked explicitly
+as hidden as so to avoid PLT indirection overheads---making this
+abundantly clear also aids readability and self-documentation of the code.
+Note that due to ISO C++ specification requirements, @code{operator new} and
+@code{operator delete} must always be of default visibility.
+
+Be aware that headers from outside your project, in particular system
+headers and headers from any other library you use, may not be
+expecting to be compiled with visibility other than the default. You
+may need to explicitly say @code{#pragma GCC visibility push(default)}
+before including any such headers.
+
+@code{extern} declarations are not affected by @option{-fvisibility}, so
+a lot of code can be recompiled with @option{-fvisibility=hidden} with
+no modifications. However, this means that calls to @code{extern}
+functions with no explicit visibility use the PLT, so it is more
+effective to use @code{__attribute ((visibility))} and/or
+@code{#pragma GCC visibility} to tell the compiler which @code{extern}
+declarations should be treated as hidden.
+
+Note that @option{-fvisibility} does affect C++ vague linkage
+entities. This means that, for instance, an exception class that is
+be thrown between DSOs must be explicitly marked with default
+visibility so that the @samp{type_info} nodes are unified between
+the DSOs.
+
+An overview of these techniques, their benefits and how to use them
+is at @uref{http://gcc.gnu.org/@/wiki/@/Visibility}.
+
+@item -fstrict-volatile-bitfields
+@opindex fstrict-volatile-bitfields
+This option should be used if accesses to volatile bit-fields (or other
+structure fields, although the compiler usually honors those types
+anyway) should use a single access of the width of the
+field's type, aligned to a natural alignment if possible. For
+example, targets with memory-mapped peripheral registers might require
+all such accesses to be 16 bits wide; with this flag you can
+declare all peripheral bit-fields as @code{unsigned short} (assuming short
+is 16 bits on these targets) to force GCC to use 16-bit accesses
+instead of, perhaps, a more efficient 32-bit access.
+
+If this option is disabled, the compiler uses the most efficient
+instruction. In the previous example, that might be a 32-bit load
+instruction, even though that accesses bytes that do not contain
+any portion of the bit-field, or memory-mapped registers unrelated to
+the one being updated.
+
+In some cases, such as when the @code{packed} attribute is applied to a
+structure field, it may not be possible to access the field with a single
+read or write that is correctly aligned for the target machine. In this
+case GCC falls back to generating multiple accesses rather than code that
+will fault or truncate the result at run time.
+
+Note: Due to restrictions of the C/C++11 memory model, write accesses are
+not allowed to touch non bit-field members. It is therefore recommended
+to define all bits of the field's type as bit-field members.
+
+The default value of this option is determined by the application binary
+interface for the target processor.
+
+@item -fsync-libcalls
+@opindex fsync-libcalls
+This option controls whether any out-of-line instance of the @code{__sync}
+family of functions may be used to implement the C++11 @code{__atomic}
+family of functions.
+
+The default value of this option is enabled, thus the only useful form
+of the option is @option{-fno-sync-libcalls}. This option is used in
+the implementation of the @file{libatomic} runtime library.
+
+@end table
+
@node Submodel Options
@section Hardware Models and Configurations
@cindex submodel options
@@ -23516,728 +24239,6 @@ every cross-file call, not just those th
These are listed under @xref{S/390 and zSeries Options}.
-@node Code Gen Options
-@section Options for Code Generation Conventions
-@cindex code generation conventions
-@cindex options, code generation
-@cindex run-time options
-
-These machine-independent options control the interface conventions
-used in code generation.
-
-Most of them have both positive and negative forms; the negative form
-of @option{-ffoo} is @option{-fno-foo}. In the table below, only
-one of the forms is listed---the one that is not the default. You
-can figure out the other form by either removing @samp{no-} or adding
-it.
-
-@table @gcctabopt
-@item -fbounds-check
-@opindex fbounds-check
-For front ends that support it, generate additional code to check that
-indices used to access arrays are within the declared range. This is
-currently only supported by the Java and Fortran front ends, where
-this option defaults to true and false respectively.
-
-@item -fstack-reuse=@var{reuse-level}
-@opindex fstack_reuse
-This option controls stack space reuse for user declared local/auto variables
-and compiler generated temporaries. @var{reuse_level} can be @samp{all},
-@samp{named_vars}, or @samp{none}. @samp{all} enables stack reuse for all
-local variables and temporaries, @samp{named_vars} enables the reuse only for
-user defined local variables with names, and @samp{none} disables stack reuse
-completely. The default value is @samp{all}. The option is needed when the
-program extends the lifetime of a scoped local variable or a compiler generated
-temporary beyond the end point defined by the language. When a lifetime of
-a variable ends, and if the variable lives in memory, the optimizing compiler
-has the freedom to reuse its stack space with other temporaries or scoped
-local variables whose live range does not overlap with it. Legacy code extending
-local lifetime is likely to break with the stack reuse optimization.
-
-For example,
-
-@smallexample
- int *p;
- @{
- int local1;
-
- p = &local1;
- local1 = 10;
- ....
- @}
- @{
- int local2;
- local2 = 20;
- ...
- @}
-
- if (*p == 10) // out of scope use of local1
- @{
-
- @}
-@end smallexample
-
-Another example:
-@smallexample
-
- struct A
- @{
- A(int k) : i(k), j(k) @{ @}
- int i;
- int j;
- @};
-
- A *ap;
-
- void foo(const A& ar)
- @{
- ap = &ar;
- @}
-
- void bar()
- @{
- foo(A(10)); // temp object's lifetime ends when foo returns
-
- @{
- A a(20);
- ....
- @}
- ap->i+= 10; // ap references out of scope temp whose space
- // is reused with a. What is the value of ap->i?
- @}
-
-@end smallexample
-
-The lifetime of a compiler generated temporary is well defined by the C++
-standard. When a lifetime of a temporary ends, and if the temporary lives
-in memory, the optimizing compiler has the freedom to reuse its stack
-space with other temporaries or scoped local variables whose live range
-does not overlap with it. However some of the legacy code relies on
-the behavior of older compilers in which temporaries' stack space is
-not reused, the aggressive stack reuse can lead to runtime errors. This
-option is used to control the temporary stack reuse optimization.
-
-@item -ftrapv
-@opindex ftrapv
-This option generates traps for signed overflow on addition, subtraction,
-multiplication operations.
-The options @option{-ftrapv} and @option{-fwrapv} override each other, so using
-@option{-ftrapv} @option{-fwrapv} on the command-line results in
-@option{-fwrapv} being effective. Note that only active options override, so
-using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line
-results in @option{-ftrapv} being effective.
-
-@item -fwrapv
-@opindex fwrapv
-This option instructs the compiler to assume that signed arithmetic
-overflow of addition, subtraction and multiplication wraps around
-using twos-complement representation. This flag enables some optimizations
-and disables others. This option is enabled by default for the Java
-front end, as required by the Java language specification.
-The options @option{-ftrapv} and @option{-fwrapv} override each other, so using
-@option{-ftrapv} @option{-fwrapv} on the command-line results in
-@option{-fwrapv} being effective. Note that only active options override, so
-using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line
-results in @option{-ftrapv} being effective.
-
-@item -fexceptions
-@opindex fexceptions
-Enable exception handling. Generates extra code needed to propagate
-exceptions. For some targets, this implies GCC generates frame
-unwind information for all functions, which can produce significant data
-size overhead, although it does not affect execution. If you do not
-specify this option, GCC enables it by default for languages like
-C++ that normally require exception handling, and disables it for
-languages like C that do not normally require it. However, you may need
-to enable this option when compiling C code that needs to interoperate
-properly with exception handlers written in C++. You may also wish to
-disable this option if you are compiling older C++ programs that don't
-use exception handling.
-
-@item -fnon-call-exceptions
-@opindex fnon-call-exceptions
-Generate code that allows trapping instructions to throw exceptions.
-Note that this requires platform-specific runtime support that does
-not exist everywhere. Moreover, it only allows @emph{trapping}
-instructions to throw exceptions, i.e.@: memory references or floating-point
-instructions. It does not allow exceptions to be thrown from
-arbitrary signal handlers such as @code{SIGALRM}.
-
-@item -fdelete-dead-exceptions
-@opindex fdelete-dead-exceptions
-Consider that instructions that may throw exceptions but don't otherwise
-contribute to the execution of the program can be optimized away.
-This option is enabled by default for the Ada front end, as permitted by
-the Ada language specification.
-Optimization passes that cause dead exceptions to be removed are enabled independently at different optimization levels.
-
-@item -funwind-tables
-@opindex funwind-tables
-Similar to @option{-fexceptions}, except that it just generates any needed
-static data, but does not affect the generated code in any other way.
-You normally do not need to enable this option; instead, a language processor
-that needs this handling enables it on your behalf.
-
-@item -fasynchronous-unwind-tables
-@opindex fasynchronous-unwind-tables
-Generate unwind table in DWARF 2 format, if supported by target machine. The
-table is exact at each instruction boundary, so it can be used for stack
-unwinding from asynchronous events (such as debugger or garbage collector).
-
-@item -fno-gnu-unique
-@opindex fno-gnu-unique
-On systems with recent GNU assembler and C library, the C++ compiler
-uses the @code{STB_GNU_UNIQUE} binding to make sure that definitions
-of template static data members and static local variables in inline
-functions are unique even in the presence of @code{RTLD_LOCAL}; this
-is necessary to avoid problems with a library used by two different
-@code{RTLD_LOCAL} plugins depending on a definition in one of them and
-therefore disagreeing with the other one about the binding of the
-symbol. But this causes @code{dlclose} to be ignored for affected
-DSOs; if your program relies on reinitialization of a DSO via
-@code{dlclose} and @code{dlopen}, you can use
-@option{-fno-gnu-unique}.
-
-@item -fpcc-struct-return
-@opindex fpcc-struct-return
-Return ``short'' @code{struct} and @code{union} values in memory like
-longer ones, rather than in registers. This convention is less
-efficient, but it has the advantage of allowing intercallability between
-GCC-compiled files and files compiled with other compilers, particularly
-the Portable C Compiler (pcc).
-
-The precise convention for returning structures in memory depends
-on the target configuration macros.
-
-Short structures and unions are those whose size and alignment match
-that of some integer type.
-
-@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
-switch is not binary compatible with code compiled with the
-@option{-freg-struct-return} switch.
-Use it to conform to a non-default application binary interface.
-
-@item -freg-struct-return
-@opindex freg-struct-return
-Return @code{struct} and @code{union} values in registers when possible.
-This is more efficient for small structures than
-@option{-fpcc-struct-return}.
-
-If you specify neither @option{-fpcc-struct-return} nor
-@option{-freg-struct-return}, GCC defaults to whichever convention is
-standard for the target. If there is no standard convention, GCC
-defaults to @option{-fpcc-struct-return}, except on targets where GCC is
-the principal compiler. In those cases, we can choose the standard, and
-we chose the more efficient register return alternative.
-
-@strong{Warning:} code compiled with the @option{-freg-struct-return}
-switch is not binary compatible with code compiled with the
-@option{-fpcc-struct-return} switch.
-Use it to conform to a non-default application binary interface.
-
-@item -fshort-enums
-@opindex fshort-enums
-Allocate to an @code{enum} type only as many bytes as it needs for the
-declared range of possible values. Specifically, the @code{enum} type
-is equivalent to the smallest integer type that has enough room.
-
-@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
-code that is not binary compatible with code generated without that switch.
-Use it to conform to a non-default application binary interface.
-
-@item -fshort-double
-@opindex fshort-double
-Use the same size for @code{double} as for @code{float}.
-
-@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
-code that is not binary compatible with code generated without that switch.
-Use it to conform to a non-default application binary interface.
-
-@item -fshort-wchar
-@opindex fshort-wchar
-Override the underlying type for @code{wchar_t} to be @code{short
-unsigned int} instead of the default for the target. This option is
-useful for building programs to run under WINE@.
-
-@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
-code that is not binary compatible with code generated without that switch.
-Use it to conform to a non-default application binary interface.
-
-@item -fno-common
-@opindex fno-common
-In C code, controls the placement of uninitialized global variables.
-Unix C compilers have traditionally permitted multiple definitions of
-such variables in different compilation units by placing the variables
-in a common block.
-This is the behavior specified by @option{-fcommon}, and is the default
-for GCC on most targets.
-On the other hand, this behavior is not required by ISO C, and on some
-targets may carry a speed or code size penalty on variable references.
-The @option{-fno-common} option specifies that the compiler should place
-uninitialized global variables in the data section of the object file,
-rather than generating them as common blocks.
-This has the effect that if the same variable is declared
-(without @code{extern}) in two different compilations,
-you get a multiple-definition error when you link them.
-In this case, you must compile with @option{-fcommon} instead.
-Compiling with @option{-fno-common} is useful on targets for which
-it provides better performance, or if you wish to verify that the
-program will work on other systems that always treat uninitialized
-variable declarations this way.
-
-@item -fno-ident
-@opindex fno-ident
-Ignore the @code{#ident} directive.
-
-@item -finhibit-size-directive
-@opindex finhibit-size-directive
-Don't output a @code{.size} assembler directive, or anything else that
-would cause trouble if the function is split in the middle, and the
-two halves are placed at locations far apart in memory. This option is
-used when compiling @file{crtstuff.c}; you should not need to use it
-for anything else.
-
-@item -fverbose-asm
-@opindex fverbose-asm
-Put extra commentary information in the generated assembly code to
-make it more readable. This option is generally only of use to those
-who actually need to read the generated assembly code (perhaps while
-debugging the compiler itself).
-
-@option{-fno-verbose-asm}, the default, causes the
-extra information to be omitted and is useful when comparing two assembler
-files.
-
-@item -frecord-gcc-switches
-@opindex frecord-gcc-switches
-This switch causes the command line used to invoke the
-compiler to be recorded into the object file that is being created.
-This switch is only implemented on some targets and the exact format
-of the recording is target and binary file format dependent, but it
-usually takes the form of a section containing ASCII text. This
-switch is related to the @option{-fverbose-asm} switch, but that
-switch only records information in the assembler output file as
-comments, so it never reaches the object file.
-See also @option{-grecord-gcc-switches} for another
-way of storing compiler options into the object file.
-
-@item -fpic
-@opindex fpic
-@cindex global offset table
-@cindex PIC
-Generate position-independent code (PIC) suitable for use in a shared
-library, if supported for the target machine. Such code accesses all
-constant addresses through a global offset table (GOT)@. The dynamic
-loader resolves the GOT entries when the program starts (the dynamic
-loader is not part of GCC; it is part of the operating system). If
-the GOT size for the linked executable exceeds a machine-specific
-maximum size, you get an error message from the linker indicating that
-@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
-instead. (These maximums are 8k on the SPARC, 28k on AArch64 and 32k
-on the m68k and RS/6000. The x86 has no such limit.)
-
-Position-independent code requires special support, and therefore works
-only on certain machines. For the x86, GCC supports PIC for System V
-but not for the Sun 386i. Code generated for the IBM RS/6000 is always
-position-independent.
-
-When this flag is set, the macros @code{__pic__} and @code{__PIC__}
-are defined to 1.
-
-@item -fPIC
-@opindex fPIC
-If supported for the target machine, emit position-independent code,
-suitable for dynamic linking and avoiding any limit on the size of the
-global offset table. This option makes a difference on AArch64, m68k,
-PowerPC and SPARC@.
-
-Position-independent code requires special support, and therefore works
-only on certain machines.
-
-When this flag is set, the macros @code{__pic__} and @code{__PIC__}
-are defined to 2.
-
-@item -fpie
-@itemx -fPIE
-@opindex fpie
-@opindex fPIE
-These options are similar to @option{-fpic} and @option{-fPIC}, but
-generated position independent code can be only linked into executables.
-Usually these options are used when @option{-pie} GCC option is
-used during linking.
-
-@option{-fpie} and @option{-fPIE} both define the macros
-@code{__pie__} and @code{__PIE__}. The macros have the value 1
-for @option{-fpie} and 2 for @option{-fPIE}.
-
-@item -fno-plt
-@opindex fno-plt
-Do not use the PLT for external function calls in position-independent code.
-Instead, load the callee address at call sites from the GOT and branch to it.
-This leads to more efficient code by eliminating PLT stubs and exposing
-GOT loads to optimizations. On architectures such as 32-bit x86 where
-PLT stubs expect the GOT pointer in a specific register, this gives more
-register allocation freedom to the compiler.
-Lazy binding requires use of the PLT;
-with @option{-fno-plt} all external symbols are resolved at load time.
-
-Alternatively, the function attribute @code{noplt} can be used to avoid calls
-through the PLT for specific external functions.
-
-In position-dependent code, a few targets also convert calls to
-functions that are marked to not use the PLT to use the GOT instead.
-
-@item -fno-jump-tables
-@opindex fno-jump-tables
-Do not use jump tables for switch statements even where it would be
-more efficient than other code generation strategies. This option is
-of use in conjunction with @option{-fpic} or @option{-fPIC} for
-building code that forms part of a dynamic linker and cannot
-reference the address of a jump table. On some targets, jump tables
-do not require a GOT and this option is not needed.
-
-@item -ffixed-@var{reg}
-@opindex ffixed
-Treat the register named @var{reg} as a fixed register; generated code
-should never refer to it (except perhaps as a stack pointer, frame
-pointer or in some other fixed role).
-
-@var{reg} must be the name of a register. The register names accepted
-are machine-specific and are defined in the @code{REGISTER_NAMES}
-macro in the machine description macro file.
-
-This flag does not have a negative form, because it specifies a
-three-way choice.
-
-@item -fcall-used-@var{reg}
-@opindex fcall-used
-Treat the register named @var{reg} as an allocable register that is
-clobbered by function calls. It may be allocated for temporaries or
-variables that do not live across a call. Functions compiled this way
-do not save and restore the register @var{reg}.
-
-It is an error to use this flag with the frame pointer or stack pointer.
-Use of this flag for other registers that have fixed pervasive roles in
-the machine's execution model produces disastrous results.
-
-This flag does not have a negative form, because it specifies a
-three-way choice.
-
-@item -fcall-saved-@var{reg}
-@opindex fcall-saved
-Treat the register named @var{reg} as an allocable register saved by
-functions. It may be allocated even for temporaries or variables that
-live across a call. Functions compiled this way save and restore
-the register @var{reg} if they use it.
-
-It is an error to use this flag with the frame pointer or stack pointer.
-Use of this flag for other registers that have fixed pervasive roles in
-the machine's execution model produces disastrous results.
-
-A different sort of disaster results from the use of this flag for
-a register in which function values may be returned.
-
-This flag does not have a negative form, because it specifies a
-three-way choice.
-
-@item -fpack-struct[=@var{n}]
-@opindex fpack-struct
-Without a value specified, pack all structure members together without
-holes. When a value is specified (which must be a small power of two), pack
-structure members according to this value, representing the maximum
-alignment (that is, objects with default alignment requirements larger than
-this are output potentially unaligned at the next fitting location.
-
-@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
-code that is not binary compatible with code generated without that switch.
-Additionally, it makes the code suboptimal.
-Use it to conform to a non-default application binary interface.
-
-@item -finstrument-functions
-@opindex finstrument-functions
-Generate instrumentation calls for entry and exit to functions. Just
-after function entry and just before function exit, the following
-profiling functions are called with the address of the current
-function and its call site. (On some platforms,
-@code{__builtin_return_address} does not work beyond the current
-function, so the call site information may not be available to the
-profiling functions otherwise.)
-
-@smallexample
-void __cyg_profile_func_enter (void *this_fn,
- void *call_site);
-void __cyg_profile_func_exit (void *this_fn,
- void *call_site);
-@end smallexample
-
-The first argument is the address of the start of the current function,
-which may be looked up exactly in the symbol table.
-
-This instrumentation is also done for functions expanded inline in other
-functions. The profiling calls indicate where, conceptually, the
-inline function is entered and exited. This means that addressable
-versions of such functions must be available. If all your uses of a
-function are expanded inline, this may mean an additional expansion of
-code size. If you use @code{extern inline} in your C code, an
-addressable version of such functions must be provided. (This is
-normally the case anyway, but if you get lucky and the optimizer always
-expands the functions inline, you might have gotten away without
-providing static copies.)
-
-A function may be given the attribute @code{no_instrument_function}, in
-which case this instrumentation is not done. This can be used, for
-example, for the profiling functions listed above, high-priority
-interrupt routines, and any functions from which the profiling functions
-cannot safely be called (perhaps signal handlers, if the profiling
-routines generate output or allocate memory).
-
-@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
-@opindex finstrument-functions-exclude-file-list
-
-Set the list of functions that are excluded from instrumentation (see
-the description of @option{-finstrument-functions}). If the file that
-contains a function definition matches with one of @var{file}, then
-that function is not instrumented. The match is done on substrings:
-if the @var{file} parameter is a substring of the file name, it is
-considered to be a match.
-
-For example:
-
-@smallexample
--finstrument-functions-exclude-file-list=/bits/stl,include/sys
-@end smallexample
-
-@noindent
-excludes any inline function defined in files whose pathnames
-contain @file{/bits/stl} or @file{include/sys}.
-
-If, for some reason, you want to include letter @samp{,} in one of
-@var{sym}, write @samp{\,}. For example,
-@option{-finstrument-functions-exclude-file-list='\,\,tmp'}
-(note the single quote surrounding the option).
-
-@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
-@opindex finstrument-functions-exclude-function-list
-
-This is similar to @option{-finstrument-functions-exclude-file-list},
-but this option sets the list of function names to be excluded from
-instrumentation. The function name to be matched is its user-visible
-name, such as @code{vector<int> blah(const vector<int> &)}, not the
-internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
-match is done on substrings: if the @var{sym} parameter is a substring
-of the function name, it is considered to be a match. For C99 and C++
-extended identifiers, the function name must be given in UTF-8, not
-using universal character names.
-
-@item -fstack-check
-@opindex fstack-check
-Generate code to verify that you do not go beyond the boundary of the
-stack. You should specify this flag if you are running in an
-environment with multiple threads, but you only rarely need to specify it in
-a single-threaded environment since stack overflow is automatically
-detected on nearly all systems if there is only one stack.
-
-Note that this switch does not actually cause checking to be done; the
-operating system or the language runtime must do that. The switch causes
-generation of code to ensure that they see the stack being extended.
-
-You can additionally specify a string parameter: @samp{no} means no
-checking, @samp{generic} means force the use of old-style checking,
-@samp{specific} means use the best checking method and is equivalent
-to bare @option{-fstack-check}.
-
-Old-style checking is a generic mechanism that requires no specific
-target support in the compiler but comes with the following drawbacks:
-
-@enumerate
-@item
-Modified allocation strategy for large objects: they are always
-allocated dynamically if their size exceeds a fixed threshold.
-
-@item
-Fixed limit on the size of the static frame of functions: when it is
-topped by a particular function, stack checking is not reliable and
-a warning is issued by the compiler.
-
-@item
-Inefficiency: because of both the modified allocation strategy and the
-generic implementation, code performance is hampered.
-@end enumerate
-
-Note that old-style stack checking is also the fallback method for
-@samp{specific} if no target support has been added in the compiler.
-
-@item -fstack-limit-register=@var{reg}
-@itemx -fstack-limit-symbol=@var{sym}
-@itemx -fno-stack-limit
-@opindex fstack-limit-register
-@opindex fstack-limit-symbol
-@opindex fno-stack-limit
-Generate code to ensure that the stack does not grow beyond a certain value,
-either the value of a register or the address of a symbol. If a larger
-stack is required, a signal is raised at run time. For most targets,
-the signal is raised before the stack overruns the boundary, so
-it is possible to catch the signal without taking special precautions.
-
-For instance, if the stack starts at absolute address @samp{0x80000000}
-and grows downwards, you can use the flags
-@option{-fstack-limit-symbol=__stack_limit} and
-@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
-of 128KB@. Note that this may only work with the GNU linker.
-
-You can locally override stack limit checking by using the
-@code{no_stack_limit} function attribute (@pxref{Function Attributes}).
-
-@item -fsplit-stack
-@opindex fsplit-stack
-Generate code to automatically split the stack before it overflows.
-The resulting program has a discontiguous stack which can only
-overflow if the program is unable to allocate any more memory. This
-is most useful when running threaded programs, as it is no longer
-necessary to calculate a good stack size to use for each thread. This
-is currently only implemented for the x86 targets running
-GNU/Linux.
-
-When code compiled with @option{-fsplit-stack} calls code compiled
-without @option{-fsplit-stack}, there may not be much stack space
-available for the latter code to run. If compiling all code,
-including library code, with @option{-fsplit-stack} is not an option,
-then the linker can fix up these calls so that the code compiled
-without @option{-fsplit-stack} always has a large stack. Support for
-this is implemented in the gold linker in GNU binutils release 2.21
-and later.
-
-@item -fleading-underscore
-@opindex fleading-underscore
-This option and its counterpart, @option{-fno-leading-underscore}, forcibly
-change the way C symbols are represented in the object file. One use
-is to help link with legacy assembly code.
-
-@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
-generate code that is not binary compatible with code generated without that
-switch. Use it to conform to a non-default application binary interface.
-Not all targets provide complete support for this switch.
-
-@item -ftls-model=@var{model}
-@opindex ftls-model
-Alter the thread-local storage model to be used (@pxref{Thread-Local}).
-The @var{model} argument should be one of @samp{global-dynamic},
-@samp{local-dynamic}, @samp{initial-exec} or @samp{local-exec}.
-Note that the choice is subject to optimization: the compiler may use
-a more efficient model for symbols not visible outside of the translation
-unit, or if @option{-fpic} is not given on the command line.
-
-The default without @option{-fpic} is @samp{initial-exec}; with
-@option{-fpic} the default is @samp{global-dynamic}.
-
-@item -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]}
-@opindex fvisibility
-Set the default ELF image symbol visibility to the specified option---all
-symbols are marked with this unless overridden within the code.
-Using this feature can very substantially improve linking and
-load times of shared object libraries, produce more optimized
-code, provide near-perfect API export and prevent symbol clashes.
-It is @strong{strongly} recommended that you use this in any shared objects
-you distribute.
-
-Despite the nomenclature, @samp{default} always means public; i.e.,
-available to be linked against from outside the shared object.
-@samp{protected} and @samp{internal} are pretty useless in real-world
-usage so the only other commonly used option is @samp{hidden}.
-The default if @option{-fvisibility} isn't specified is
-@samp{default}, i.e., make every symbol public.
-
-A good explanation of the benefits offered by ensuring ELF
-symbols have the correct visibility is given by ``How To Write
-Shared Libraries'' by Ulrich Drepper (which can be found at
-@w{@uref{http://www.akkadia.org/drepper/}})---however a superior
-solution made possible by this option to marking things hidden when
-the default is public is to make the default hidden and mark things
-public. This is the norm with DLLs on Windows and with @option{-fvisibility=hidden}
-and @code{__attribute__ ((visibility("default")))} instead of
-@code{__declspec(dllexport)} you get almost identical semantics with
-identical syntax. This is a great boon to those working with
-cross-platform projects.
-
-For those adding visibility support to existing code, you may find
-@code{#pragma GCC visibility} of use. This works by you enclosing
-the declarations you wish to set visibility for with (for example)
-@code{#pragma GCC visibility push(hidden)} and
-@code{#pragma GCC visibility pop}.
-Bear in mind that symbol visibility should be viewed @strong{as
-part of the API interface contract} and thus all new code should
-always specify visibility when it is not the default; i.e., declarations
-only for use within the local DSO should @strong{always} be marked explicitly
-as hidden as so to avoid PLT indirection overheads---making this
-abundantly clear also aids readability and self-documentation of the code.
-Note that due to ISO C++ specification requirements, @code{operator new} and
-@code{operator delete} must always be of default visibility.
-
-Be aware that headers from outside your project, in particular system
-headers and headers from any other library you use, may not be
-expecting to be compiled with visibility other than the default. You
-may need to explicitly say @code{#pragma GCC visibility push(default)}
-before including any such headers.
-
-@code{extern} declarations are not affected by @option{-fvisibility}, so
-a lot of code can be recompiled with @option{-fvisibility=hidden} with
-no modifications. However, this means that calls to @code{extern}
-functions with no explicit visibility use the PLT, so it is more
-effective to use @code{__attribute ((visibility))} and/or
-@code{#pragma GCC visibility} to tell the compiler which @code{extern}
-declarations should be treated as hidden.
-
-Note that @option{-fvisibility} does affect C++ vague linkage
-entities. This means that, for instance, an exception class that is
-be thrown between DSOs must be explicitly marked with default
-visibility so that the @samp{type_info} nodes are unified between
-the DSOs.
-
-An overview of these techniques, their benefits and how to use them
-is at @uref{http://gcc.gnu.org/@/wiki/@/Visibility}.
-
-@item -fstrict-volatile-bitfields
-@opindex fstrict-volatile-bitfields
-This option should be used if accesses to volatile bit-fields (or other
-structure fields, although the compiler usually honors those types
-anyway) should use a single access of the width of the
-field's type, aligned to a natural alignment if possible. For
-example, targets with memory-mapped peripheral registers might require
-all such accesses to be 16 bits wide; with this flag you can
-declare all peripheral bit-fields as @code{unsigned short} (assuming short
-is 16 bits on these targets) to force GCC to use 16-bit accesses
-instead of, perhaps, a more efficient 32-bit access.
-
-If this option is disabled, the compiler uses the most efficient
-instruction. In the previous example, that might be a 32-bit load
-instruction, even though that accesses bytes that do not contain
-any portion of the bit-field, or memory-mapped registers unrelated to
-the one being updated.
-
-In some cases, such as when the @code{packed} attribute is applied to a
-structure field, it may not be possible to access the field with a single
-read or write that is correctly aligned for the target machine. In this
-case GCC falls back to generating multiple accesses rather than code that
-will fault or truncate the result at run time.
-
-Note: Due to restrictions of the C/C++11 memory model, write accesses are
-not allowed to touch non bit-field members. It is therefore recommended
-to define all bits of the field's type as bit-field members.
-
-The default value of this option is determined by the application binary
-interface for the target processor.
-
-@item -fsync-libcalls
-@opindex fsync-libcalls
-This option controls whether any out-of-line instance of the @code{__sync}
-family of functions may be used to implement the C++11 @code{__atomic}
-family of functions.
-
-The default value of this option is enabled, thus the only useful form
-of the option is @option{-fno-sync-libcalls}. This option is used in
-the implementation of the @file{libatomic} runtime library.
-
-@end table
@c man end
^ permalink raw reply [flat|nested] 12+ messages in thread* [doc, 3.5/n] invoke.texi: rename "Machine-Dependent Options" section
2016-01-10 23:50 [doc, 0/n] improve organization of invoke.texi Sandra Loosemore
` (3 preceding siblings ...)
2016-01-13 21:08 ` [doc, 3/n] invoke.texi: move "Code Gen Options" before target-specific options Sandra Loosemore
@ 2016-01-13 23:38 ` Sandra Loosemore
2016-01-15 2:00 ` [doc, 4/n] invoke.texi: there is no part 4 Sandra Loosemore
` (2 subsequent siblings)
7 siblings, 0 replies; 12+ messages in thread
From: Sandra Loosemore @ 2016-01-13 23:38 UTC (permalink / raw)
To: GCC Patches
[-- Attachment #1: Type: text/plain, Size: 804 bytes --]
This is another "extra" patch in my series to improve the organization
of invoke.texi and make it easier for users to find things.
It seemed to me that "Hardware Models and Configurations" was not an
obvious name for the section on machine-dependent options. The "Option
Summary" section already used "Machine-Dependent Options" (minus the
hyphen) to describe this group of options, so I went with that instead.
I also thought that using 30+-year-old processor names like "68010 vs
68020" as an example seemed pretty archaic, so I also rewrote the @menu
description and introductory blurb for the section to be more generic
and better reflect that nowadays target-specific options do a lot more
than just let you choose the hardware model to compile for.
I've committed this patch.
-Sandra
[-- Attachment #2: gccdoc.log --]
[-- Type: text/x-log, Size: 255 bytes --]
2016-01-13 Sandra Loosemore <sandra@codesourcery.com>
gcc/
* doc/invoke.texi (Submodel Options): Rename section to
"Machine-Dependent Options" to better reflect its content.
Rewrite introductory text to remove archaic CPU names.
Update references.
[-- Attachment #3: gccdoc.patch --]
[-- Type: text/x-patch, Size: 2694 bytes --]
Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi (revision 232352)
+++ gcc/doc/invoke.texi (working copy)
@@ -148,8 +148,8 @@ only one of these two forms, whichever o
Where to find the compiler executable files.
* Code Gen Options:: Specifying conventions for function calls, data layout
and register usage.
-* Submodel Options:: Specifying minor hardware or convention variations,
- such as 68010 vs 68020.
+* Submodel Options:: Target-specific options, such as compiling for a
+ specific processor variant.
* Spec Files:: How to pass switches to sub-processes.
* Environment Variables:: Env vars that affect GCC.
* Precompiled Headers:: Compiling a header once, and using it many times.
@@ -541,8 +541,8 @@ Objective-C and Objective-C++ Dialects}.
-fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} @gol
-fstrict-volatile-bitfields -fsync-libcalls}
-@item Machine Dependent Options
-@xref{Submodel Options,,Hardware Models and Configurations}.
+@item Machine-Dependent Options
+@xref{Submodel Options,,Machine-Dependent Options}.
@c This list is ordered alphanumerically by subsection name.
@c Try and put the significant identifier (CPU or system) first,
@c so users have a clue at guessing where the ones they want will be.
@@ -12569,20 +12569,20 @@ the implementation of the @file{libatomi
@end table
@node Submodel Options
-@section Hardware Models and Configurations
+@section Machine-Dependent Options
@cindex submodel options
@cindex specifying hardware config
@cindex hardware models and configurations, specifying
-@cindex machine dependent options
+@cindex target-dependent options
+@cindex machine-dependent options
-Each target machine types can have its own
-special options, starting with @samp{-m}, to choose among various
-hardware models or configurations---for example, 68010 vs 68020,
-floating coprocessor or none. A single installed version of the
-compiler can compile for any model or configuration, according to the
-options specified.
+Each target machine supported by GCC can have its own options---for
+example, to allow you to compile for a particular processor variant or
+ABI, or to control optimizations specific to that machine. By
+convention, the names of machine-specific options start with
+@samp{-m}.
-Some configurations of the compiler also support additional special
+Some configurations of the compiler also support additional target-specific
options, usually for compatibility with other compilers on the same
platform.
^ permalink raw reply [flat|nested] 12+ messages in thread* [doc, 4/n] invoke.texi: there is no part 4
2016-01-10 23:50 [doc, 0/n] improve organization of invoke.texi Sandra Loosemore
` (4 preceding siblings ...)
2016-01-13 23:38 ` [doc, 3.5/n] invoke.texi: rename "Machine-Dependent Options" section Sandra Loosemore
@ 2016-01-15 2:00 ` Sandra Loosemore
2016-01-15 2:18 ` [doc, 5/n] invoke.texi: add new "Program Instrumentation Options" section Sandra Loosemore
2016-01-17 4:12 ` [doc, 6/n] invoke.texi: split debugging options into programmer vs developer sections Sandra Loosemore
7 siblings, 0 replies; 12+ messages in thread
From: Sandra Loosemore @ 2016-01-15 2:00 UTC (permalink / raw)
To: GCC Patches
Part 4 of this series was originally intended to move the section "Using
Precompiled Headers" from invoke.texi to extend.texi. But, as I started
to dig around to decide exactly where its should go, I didn't see a good
place to put it there, either -- extend.texi is still very disorganized.
I've decided to leave the section where it is for now.
In the long run, I think maybe it should be grouped with other
documentation describing preprocessor extensions, since it is
essentially describing an extension to #include.
-Sandra
^ permalink raw reply [flat|nested] 12+ messages in thread* [doc, 5/n] invoke.texi: add new "Program Instrumentation Options" section
2016-01-10 23:50 [doc, 0/n] improve organization of invoke.texi Sandra Loosemore
` (5 preceding siblings ...)
2016-01-15 2:00 ` [doc, 4/n] invoke.texi: there is no part 4 Sandra Loosemore
@ 2016-01-15 2:18 ` Sandra Loosemore
2016-01-15 8:39 ` Mikhail Maltsev
2016-01-17 4:12 ` [doc, 6/n] invoke.texi: split debugging options into programmer vs developer sections Sandra Loosemore
7 siblings, 1 reply; 12+ messages in thread
From: Sandra Loosemore @ 2016-01-15 2:18 UTC (permalink / raw)
To: GCC Patches
[-- Attachment #1: Type: text/plain, Size: 2203 bytes --]
This patch consolidates the documentation of GCC options that add runtime profiling, error checking, or other instrumentation into a single section. Currently these are scattered all over, variously classified as debugging options, code generation options, optimization options, etc.
Here is the list of options that I moved into the new section:
@gccoptlist{-p -pg -fprofile-arcs --coverage -ftest-coverage @gol
-fprofile-dir=@var{path} -fprofile-generate -fprofile-generate=@var{path} @gol
-fsanitize=@var{style} -fsanitize-recover -fsanitize-recover=@var{style} @gol
-fasan-shadow-offset=@var{number} -fsanitize-sections=@var{s1},@var{s2},... @gol
-fsanitize-undefined-trap-on-error -fbounds-check @gol
-fcheck-pointer-bounds -fchecking -fchkp-check-incomplete-type @gol
-fchkp-first-field-has-own-bounds -fchkp-narrow-bounds @gol
-fchkp-narrow-to-innermost-array -fchkp-optimize @gol
-fchkp-use-fast-string-functions -fchkp-use-nochk-string-functions @gol
-fchkp-use-static-bounds -fchkp-use-static-const-bounds @gol
-fchkp-treat-zero-dynamic-size-as-infinite -fchkp-check-read @gol
-fchkp-check-read -fchkp-check-write -fchkp-store-bounds @gol
-fchkp-instrument-calls -fchkp-instrument-marked-only @gol
-fchkp-use-wrappers @gol
-fstack-protector -fstack-protector-all -fstack-protector-strong @gol
-fstack-protector-explicit fstack-check @gol
-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
-fno-stack-limit -fsplit-stack @gol
-fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} @gol
-fvtv-counts -fvtv-debug @gol
-finstrument-functions @gol
-finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol
-finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}}
Note that I moved -fprofile-generate here, but left -fprofile-use and the options that control specific profile-guided optimizations in the optimization section.
Except for the introductory paragraph for the new section and added cross-references between -fprofile-generate and -fprofile-use, I did not touch any of the option descriptions, just moved them around.
I will commit this patch in a day or two if I don't get any suggestions for improving it meanwhile.
-Sandra
[-- Attachment #2: gccdoc.log --]
[-- Type: text/x-log, Size: 649 bytes --]
2016-01-14 Sandra Loosemore <sandra@codesourcery.com>
gcc/
* doc/invoke.texi (Invoking GCC): Add new section to menu.
(Option Summary): Update to reflect new section and moved options.
(C++ Dialect Options): Move -fvtable-verify and related options.
(Debugging Options): Move Sanitizer, Pointer Bounds Checker,
and profiling-related options.
(Optimization Options): Move profile generation options and
-fstack-protector and related options.
(Instrumentation Options): New section incorporating moved options.
(Code Generation Options): Move -finstrument-functions and
related options, -fstack-check, -fstack-limit*, and -fbounds-check.
[-- Attachment #3: gccdoc.patch --]
[-- Type: text/x-patch, Size: 80467 bytes --]
Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi (revision 232370)
+++ gcc/doc/invoke.texi (working copy)
@@ -140,6 +140,7 @@ only one of these two forms, whichever o
* Warning Options:: How picky should the compiler be?
* Debugging Options:: Symbol tables, measurements, and debugging dumps.
* Optimize Options:: How much optimization?
+* Instrumentation Options:: Enabling profiling and extra run-time error checking.
* Preprocessor Options:: Controlling header files and macro definitions.
Also, getting dependency information for Make.
* Assembler Options:: Passing options to the assembler.
@@ -203,8 +204,6 @@ in the following sections.
-fno-threadsafe-statics -fuse-cxa-atexit @gol
-fno-weak -nostdinc++ @gol
-fvisibility-inlines-hidden @gol
--fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} @gol
--fvtv-counts -fvtv-debug @gol
-fvisibility-ms-compat @gol
-fext-numeric-literals @gol
-Wabi=@var{n} -Wabi-tag -Wconversion-null -Wctor-dtor-privacy @gol
@@ -316,18 +315,6 @@ Objective-C and Objective-C++ Dialects}.
@item Debugging Options
@xref{Debugging Options,,Options for Debugging Your Program or GCC}.
@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
--fsanitize=@var{style} -fsanitize-recover -fsanitize-recover=@var{style} @gol
--fasan-shadow-offset=@var{number} -fsanitize-sections=@var{s1},@var{s2},... @gol
--fsanitize-undefined-trap-on-error @gol
--fcheck-pointer-bounds -fchecking -fchkp-check-incomplete-type @gol
--fchkp-first-field-has-own-bounds -fchkp-narrow-bounds @gol
--fchkp-narrow-to-innermost-array -fchkp-optimize @gol
--fchkp-use-fast-string-functions -fchkp-use-nochk-string-functions @gol
--fchkp-use-static-bounds -fchkp-use-static-const-bounds @gol
--fchkp-treat-zero-dynamic-size-as-infinite -fchkp-check-read @gol
--fchkp-check-read -fchkp-check-write -fchkp-store-bounds @gol
--fchkp-instrument-calls -fchkp-instrument-marked-only @gol
--fchkp-use-wrappers @gol
-fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol
-fdisable-ipa-@var{pass_name} @gol
-fdisable-rtl-@var{pass_name} @gol
@@ -370,12 +357,13 @@ Objective-C and Objective-C++ Dialects}.
-fenable-@var{kind}-@var{pass} @gol
-fenable-@var{kind}-@var{pass}=@var{range-list} @gol
-fdebug-types-section -fmem-report-wpa @gol
--fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report -fprofile-arcs @gol
+-fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report @gol
-fopt-info @gol
-fopt-info-@var{options}@r{[}=@var{file}@r{]} @gol
+-fprofile-report @gol
-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
-fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol
--fstack-usage -ftest-coverage -ftime-report -fvar-tracking @gol
+-fstack-usage -ftime-report -fvar-tracking @gol
-fvar-tracking-assignments -fvar-tracking-assignments-toggle @gol
-g -g@var{level} -gtoggle -gcoff -gdwarf-@var{version} @gol
-ggdb -grecord-gcc-switches -gno-record-gcc-switches @gol
@@ -385,7 +373,7 @@ Objective-C and Objective-C++ Dialects}.
-fdebug-prefix-map=@var{old}=@var{new} @gol
-femit-struct-debug-baseonly -femit-struct-debug-reduced @gol
-femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol
--p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
+-print-file-name=@var{library} -print-libgcc-file-name @gol
-print-multi-directory -print-multi-lib -print-multi-os-directory @gol
-print-prog-name=@var{program} -print-search-dirs -Q @gol
-print-sysroot -print-sysroot-headers-suffix @gol
@@ -435,9 +423,8 @@ Objective-C and Objective-C++ Dialects}.
-fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
-fomit-frame-pointer -foptimize-sibling-calls @gol
-fpartial-inlining -fpeel-loops -fpredictive-commoning @gol
--fprefetch-loop-arrays -fprofile-report @gol
--fprofile-correction -fprofile-dir=@var{path} -fprofile-generate @gol
--fprofile-generate=@var{path} @gol
+-fprefetch-loop-arrays @gol
+-fprofile-correction @gol
-fprofile-use -fprofile-use=@var{path} -fprofile-values @gol
-fprofile-reorder-functions @gol
-freciprocal-math -free -frename-registers -freorder-blocks @gol
@@ -458,8 +445,7 @@ Objective-C and Objective-C++ Dialects}.
-fsingle-precision-constant -fsplit-ivs-in-unroller @gol
-fsplit-paths @gol
-fsplit-wide-types -fssa-backprop -fssa-phiopt @gol
--fstack-protector -fstack-protector-all -fstack-protector-strong @gol
--fstack-protector-explicit -fstdarg-opt -fstrict-aliasing @gol
+-fstdarg-opt -fstrict-aliasing @gol
-fstrict-overflow -fthread-jumps -ftracer -ftree-bit-ccp @gol
-ftree-builtin-call-dce -ftree-ccp -ftree-ch @gol
-ftree-coalesce-vars -ftree-copy-prop -ftree-dce -ftree-dominator-opts @gol
@@ -479,6 +465,32 @@ Objective-C and Objective-C++ Dialects}.
--param @var{name}=@var{value}
-O -O0 -O1 -O2 -O3 -Os -Ofast -Og}
+@item Program Instrumentation Options
+@xref{Instrumentation Options,,Program Instrumentation Options}.
+@gccoptlist{-p -pg -fprofile-arcs --coverage -ftest-coverage @gol
+-fprofile-dir=@var{path} -fprofile-generate -fprofile-generate=@var{path} @gol
+-fsanitize=@var{style} -fsanitize-recover -fsanitize-recover=@var{style} @gol
+-fasan-shadow-offset=@var{number} -fsanitize-sections=@var{s1},@var{s2},... @gol
+-fsanitize-undefined-trap-on-error -fbounds-check @gol
+-fcheck-pointer-bounds -fchecking -fchkp-check-incomplete-type @gol
+-fchkp-first-field-has-own-bounds -fchkp-narrow-bounds @gol
+-fchkp-narrow-to-innermost-array -fchkp-optimize @gol
+-fchkp-use-fast-string-functions -fchkp-use-nochk-string-functions @gol
+-fchkp-use-static-bounds -fchkp-use-static-const-bounds @gol
+-fchkp-treat-zero-dynamic-size-as-infinite -fchkp-check-read @gol
+-fchkp-check-read -fchkp-check-write -fchkp-store-bounds @gol
+-fchkp-instrument-calls -fchkp-instrument-marked-only @gol
+-fchkp-use-wrappers @gol
+-fstack-protector -fstack-protector-all -fstack-protector-strong @gol
+-fstack-protector-explicit fstack-check @gol
+-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
+-fno-stack-limit -fsplit-stack @gol
+-fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} @gol
+-fvtv-counts -fvtv-debug @gol
+-finstrument-functions @gol
+-finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol
+-finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}}
+
@item Preprocessor Options
@xref{Preprocessor Options,,Options Controlling the Preprocessor}.
@gccoptlist{-A@var{question}=@var{answer} @gol
@@ -523,21 +535,16 @@ Objective-C and Objective-C++ Dialects}.
-fnon-call-exceptions -fdelete-dead-exceptions -funwind-tables @gol
-fasynchronous-unwind-tables @gol
-fno-gnu-unique @gol
--finhibit-size-directive -finstrument-functions @gol
--finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol
--finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} @gol
--fno-common -fno-ident @gol
+-finhibit-size-directive -fno-common -fno-ident @gol
-fpcc-struct-return -fpic -fPIC -fpie -fPIE -fno-plt @gol
-fno-jump-tables @gol
-frecord-gcc-switches @gol
-freg-struct-return -fshort-enums @gol
-fshort-double -fshort-wchar @gol
--fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
--fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
--fno-stack-limit -fsplit-stack @gol
+-fverbose-asm -fpack-struct[=@var{n}] @gol
-fleading-underscore -ftls-model=@var{model} @gol
-fstack-reuse=@var{reuse_level} @gol
--ftrapv -fwrapv -fbounds-check @gol
+-ftrapv -fwrapv @gol
-fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} @gol
-fstrict-volatile-bitfields -fsync-libcalls}
@@ -2537,61 +2544,6 @@ and that pointers to function members de
objects may not compare equal. When this flag is given, it is a
violation of the ODR to define types with the same name differently.
-@item -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]}
-@opindex fvtable-verify
-Turn on (or off, if using @option{-fvtable-verify=none}) the security
-feature that verifies at run time, for every virtual call, that
-the vtable pointer through which the call is made is valid for the type of
-the object, and has not been corrupted or overwritten. If an invalid vtable
-pointer is detected at run time, an error is reported and execution of the
-program is immediately halted.
-
-This option causes run-time data structures to be built at program startup,
-which are used for verifying the vtable pointers.
-The options @samp{std} and @samp{preinit}
-control the timing of when these data structures are built. In both cases the
-data structures are built before execution reaches @code{main}. Using
-@option{-fvtable-verify=std} causes the data structures to be built after
-shared libraries have been loaded and initialized.
-@option{-fvtable-verify=preinit} causes them to be built before shared
-libraries have been loaded and initialized.
-
-If this option appears multiple times in the command line with different
-values specified, @samp{none} takes highest priority over both @samp{std} and
-@samp{preinit}; @samp{preinit} takes priority over @samp{std}.
-
-@item -fvtv-debug
-@opindex fvtv-debug
-When used in conjunction with @option{-fvtable-verify=std} or
-@option{-fvtable-verify=preinit}, causes debug versions of the
-runtime functions for the vtable verification feature to be called.
-This flag also causes the compiler to log information about which
-vtable pointers it finds for each class.
-This information is written to a file named @file{vtv_set_ptr_data.log}
-in the directory named by the environment variable @env{VTV_LOGS_DIR}
-if that is defined or the current working directory otherwise.
-
-Note: This feature @emph{appends} data to the log file. If you want a fresh log
-file, be sure to delete any existing one.
-
-@item -fvtv-counts
-@opindex fvtv-counts
-This is a debugging flag. When used in conjunction with
-@option{-fvtable-verify=std} or @option{-fvtable-verify=preinit}, this
-causes the compiler to keep track of the total number of virtual calls
-it encounters and the number of verifications it inserts. It also
-counts the number of calls to certain run-time library functions
-that it inserts and logs this information for each compilation unit.
-The compiler writes this information to a file named
-@file{vtv_count_data.log} in the directory named by the environment
-variable @env{VTV_LOGS_DIR} if that is defined or the current working
-directory otherwise. It also counts the size of the vtable pointer sets
-for each class, and writes this information to @file{vtv_class_set_sizes.log}
-in the same directory.
-
-Note: This feature @emph{appends} data to the log files. To get fresh log
-files, be sure to delete any existing ones.
-
@item -fno-weak
@opindex fno-weak
Do not use weak symbol support, even if it is provided by the linker.
@@ -5954,403 +5906,6 @@ other options are processed, and it does
many times it is given. This is mainly intended to be used with
@option{-fcompare-debug}.
-@item -fsanitize=address
-@opindex fsanitize=address
-Enable AddressSanitizer, a fast memory error detector.
-Memory access instructions are instrumented to detect
-out-of-bounds and use-after-free bugs.
-See @uref{https://github.com/google/sanitizers/wiki/AddressSanitizer} for
-more details. The run-time behavior can be influenced using the
-@env{ASAN_OPTIONS} environment variable. When set to @code{help=1},
-the available options are shown at startup of the instrumended program. See
-@url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags}
-for a list of supported options.
-
-@item -fsanitize=kernel-address
-@opindex fsanitize=kernel-address
-Enable AddressSanitizer for Linux kernel.
-See @uref{https://github.com/google/kasan/wiki} for more details.
-
-@item -fsanitize=thread
-@opindex fsanitize=thread
-Enable ThreadSanitizer, a fast data race detector.
-Memory access instructions are instrumented to detect
-data race bugs. See @uref{https://github.com/google/sanitizers/wiki#threadsanitizer} for more
-details. The run-time behavior can be influenced using the @env{TSAN_OPTIONS}
-environment variable; see
-@url{https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags} for a list of
-supported options.
-
-@item -fsanitize=leak
-@opindex fsanitize=leak
-Enable LeakSanitizer, a memory leak detector.
-This option only matters for linking of executables and if neither
-@option{-fsanitize=address} nor @option{-fsanitize=thread} is used. In that
-case the executable is linked against a library that overrides @code{malloc}
-and other allocator functions. See
-@uref{https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer} for more
-details. The run-time behavior can be influenced using the
-@env{LSAN_OPTIONS} environment variable.
-
-@item -fsanitize=undefined
-@opindex fsanitize=undefined
-Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector.
-Various computations are instrumented to detect undefined behavior
-at runtime. Current suboptions are:
-
-@table @gcctabopt
-
-@item -fsanitize=shift
-@opindex fsanitize=shift
-This option enables checking that the result of a shift operation is
-not undefined. Note that what exactly is considered undefined differs
-slightly between C and C++, as well as between ISO C90 and C99, etc.
-
-@item -fsanitize=integer-divide-by-zero
-@opindex fsanitize=integer-divide-by-zero
-Detect integer division by zero as well as @code{INT_MIN / -1} division.
-
-@item -fsanitize=unreachable
-@opindex fsanitize=unreachable
-With this option, the compiler turns the @code{__builtin_unreachable}
-call into a diagnostics message call instead. When reaching the
-@code{__builtin_unreachable} call, the behavior is undefined.
-
-@item -fsanitize=vla-bound
-@opindex fsanitize=vla-bound
-This option instructs the compiler to check that the size of a variable
-length array is positive.
-
-@item -fsanitize=null
-@opindex fsanitize=null
-This option enables pointer checking. Particularly, the application
-built with this option turned on will issue an error message when it
-tries to dereference a NULL pointer, or if a reference (possibly an
-rvalue reference) is bound to a NULL pointer, or if a method is invoked
-on an object pointed by a NULL pointer.
-
-@item -fsanitize=return
-@opindex fsanitize=return
-This option enables return statement checking. Programs
-built with this option turned on will issue an error message
-when the end of a non-void function is reached without actually
-returning a value. This option works in C++ only.
-
-@item -fsanitize=signed-integer-overflow
-@opindex fsanitize=signed-integer-overflow
-This option enables signed integer overflow checking. We check that
-the result of @code{+}, @code{*}, and both unary and binary @code{-}
-does not overflow in the signed arithmetics. Note, integer promotion
-rules must be taken into account. That is, the following is not an
-overflow:
-@smallexample
-signed char a = SCHAR_MAX;
-a++;
-@end smallexample
-
-@item -fsanitize=bounds
-@opindex fsanitize=bounds
-This option enables instrumentation of array bounds. Various out of bounds
-accesses are detected. Flexible array members, flexible array member-like
-arrays, and initializers of variables with static storage are not instrumented.
-
-@item -fsanitize=bounds-strict
-@opindex fsanitize=bounds-strict
-This option enables strict instrumentation of array bounds. Most out of bounds
-accesses are detected, including flexible array members and flexible array
-member-like arrays. Initializers of variables with static storage are not
-instrumented.
-
-@item -fsanitize=alignment
-@opindex fsanitize=alignment
-
-This option enables checking of alignment of pointers when they are
-dereferenced, or when a reference is bound to insufficiently aligned target,
-or when a method or constructor is invoked on insufficiently aligned object.
-
-@item -fsanitize=object-size
-@opindex fsanitize=object-size
-This option enables instrumentation of memory references using the
-@code{__builtin_object_size} function. Various out of bounds pointer
-accesses are detected.
-
-@item -fsanitize=float-divide-by-zero
-@opindex fsanitize=float-divide-by-zero
-Detect floating-point division by zero. Unlike other similar options,
-@option{-fsanitize=float-divide-by-zero} is not enabled by
-@option{-fsanitize=undefined}, since floating-point division by zero can
-be a legitimate way of obtaining infinities and NaNs.
-
-@item -fsanitize=float-cast-overflow
-@opindex fsanitize=float-cast-overflow
-This option enables floating-point type to integer conversion checking.
-We check that the result of the conversion does not overflow.
-Unlike other similar options, @option{-fsanitize=float-cast-overflow} is
-not enabled by @option{-fsanitize=undefined}.
-This option does not work well with @code{FE_INVALID} exceptions enabled.
-
-@item -fsanitize=nonnull-attribute
-@opindex fsanitize=nonnull-attribute
-
-This option enables instrumentation of calls, checking whether null values
-are not passed to arguments marked as requiring a non-null value by the
-@code{nonnull} function attribute.
-
-@item -fsanitize=returns-nonnull-attribute
-@opindex fsanitize=returns-nonnull-attribute
-
-This option enables instrumentation of return statements in functions
-marked with @code{returns_nonnull} function attribute, to detect returning
-of null values from such functions.
-
-@item -fsanitize=bool
-@opindex fsanitize=bool
-
-This option enables instrumentation of loads from bool. If a value other
-than 0/1 is loaded, a run-time error is issued.
-
-@item -fsanitize=enum
-@opindex fsanitize=enum
-
-This option enables instrumentation of loads from an enum type. If
-a value outside the range of values for the enum type is loaded,
-a run-time error is issued.
-
-@item -fsanitize=vptr
-@opindex fsanitize=vptr
-
-This option enables instrumentation of C++ member function calls, member
-accesses and some conversions between pointers to base and derived classes,
-to verify the referenced object has the correct dynamic type.
-
-@end table
-
-While @option{-ftrapv} causes traps for signed overflows to be emitted,
-@option{-fsanitize=undefined} gives a diagnostic message.
-This currently works only for the C family of languages.
-
-@item -fno-sanitize=all
-@opindex fno-sanitize=all
-
-This option disables all previously enabled sanitizers.
-@option{-fsanitize=all} is not allowed, as some sanitizers cannot be used
-together.
-
-@item -fasan-shadow-offset=@var{number}
-@opindex fasan-shadow-offset
-This option forces GCC to use custom shadow offset in AddressSanitizer checks.
-It is useful for experimenting with different shadow memory layouts in
-Kernel AddressSanitizer.
-
-@item -fsanitize-sections=@var{s1},@var{s2},...
-@opindex fsanitize-sections
-Sanitize global variables in selected user-defined sections. @var{si} may
-contain wildcards.
-
-@item -fsanitize-recover@r{[}=@var{opts}@r{]}
-@opindex fsanitize-recover
-@opindex fno-sanitize-recover
-@option{-fsanitize-recover=} controls error recovery mode for sanitizers
-mentioned in comma-separated list of @var{opts}. Enabling this option
-for a sanitizer component causes it to attempt to continue
-running the program as if no error happened. This means multiple
-runtime errors can be reported in a single program run, and the exit
-code of the program may indicate success even when errors
-have been reported. The @option{-fno-sanitize-recover=} option
-can be used to alter
-this behavior: only the first detected error is reported
-and program then exits with a non-zero exit code.
-
-Currently this feature only works for @option{-fsanitize=undefined} (and its suboptions
-except for @option{-fsanitize=unreachable} and @option{-fsanitize=return}),
-@option{-fsanitize=float-cast-overflow}, @option{-fsanitize=float-divide-by-zero},
-@option{-fsanitize=kernel-address} and @option{-fsanitize=address}.
-For these sanitizers error recovery is turned on by default, except @option{-fsanitize=address},
-for which this feature is experimental.
-@option{-fsanitize-recover=all} and @option{-fno-sanitize-recover=all} is also
-accepted, the former enables recovery for all sanitizers that support it,
-the latter disables recovery for all sanitizers that support it.
-
-Syntax without explicit @var{opts} parameter is deprecated. It is equivalent to
-@smallexample
--fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero
-@end smallexample
-@noindent
-Similarly @option{-fno-sanitize-recover} is equivalent to
-@smallexample
--fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero
-@end smallexample
-
-@item -fsanitize-undefined-trap-on-error
-@opindex fsanitize-undefined-trap-on-error
-The @option{-fsanitize-undefined-trap-on-error} option instructs the compiler to
-report undefined behavior using @code{__builtin_trap} rather than
-a @code{libubsan} library routine. The advantage of this is that the
-@code{libubsan} library is not needed and is not linked in, so this
-is usable even in freestanding environments.
-
-@item -fsanitize-coverage=trace-pc
-@opindex fsanitize-coverage=trace-pc
-Enable coverage-guided fuzzing code instrumentation.
-Inserts call to __sanitizer_cov_trace_pc into every basic block.
-
-@item -fcheck-pointer-bounds
-@opindex fcheck-pointer-bounds
-@opindex fno-check-pointer-bounds
-@cindex Pointer Bounds Checker options
-Enable Pointer Bounds Checker instrumentation. Each memory reference
-is instrumented with checks of the pointer used for memory access against
-bounds associated with that pointer.
-
-Currently there
-is only an implementation for Intel MPX available, thus x86 target
-and @option{-mmpx} are required to enable this feature.
-MPX-based instrumentation requires
-a runtime library to enable MPX in hardware and handle bounds
-violation signals. By default when @option{-fcheck-pointer-bounds}
-and @option{-mmpx} options are used to link a program, the GCC driver
-links against the @file{libmpx} runtime library and @file{libmpxwrappers}
-library. It also passes '-z bndplt' to a linker in case it supports this
-option (which is checked on libmpx configuration). Note that old versions
-of linker may ignore option. Gold linker doesn't support '-z bndplt'
-option. With no '-z bndplt' support in linker all calls to dynamic libraries
-lose passed bounds reducing overall protection level. It's highly
-recommended to use linker with '-z bndplt' support. In case such linker
-is not available it is adviced to always use @option{-static-libmpxwrappers}
-for better protection level or use @option{-static} to completely avoid
-external calls to dynamic libraries. MPX-based instrumentation
-may be used for debugging and also may be included in production code
-to increase program security. Depending on usage, you may
-have different requirements for the runtime library. The current version
-of the MPX runtime library is more oriented for use as a debugging
-tool. MPX runtime library usage implies @option{-lpthread}. See
-also @option{-static-libmpx}. The runtime library behavior can be
-influenced using various @env{CHKP_RT_*} environment variables. See
-@uref{https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler}
-for more details.
-
-Generated instrumentation may be controlled by various
-@option{-fchkp-*} options and by the @code{bnd_variable_size}
-structure field attribute (@pxref{Type Attributes}) and
-@code{bnd_legacy}, and @code{bnd_instrument} function attributes
-(@pxref{Function Attributes}). GCC also provides a number of built-in
-functions for controlling the Pointer Bounds Checker. @xref{Pointer
-Bounds Checker builtins}, for more information.
-
-@item -fchecking
-@opindex fchecking
-@opindex fno-checking
-Enable internal consistency checking. The default depends on
-the compiler configuration.
-
-@item -fchkp-check-incomplete-type
-@opindex fchkp-check-incomplete-type
-@opindex fno-chkp-check-incomplete-type
-Generate pointer bounds checks for variables with incomplete type.
-Enabled by default.
-
-@item -fchkp-narrow-bounds
-@opindex fchkp-narrow-bounds
-@opindex fno-chkp-narrow-bounds
-Controls bounds used by Pointer Bounds Checker for pointers to object
-fields. If narrowing is enabled then field bounds are used. Otherwise
-object bounds are used. See also @option{-fchkp-narrow-to-innermost-array}
-and @option{-fchkp-first-field-has-own-bounds}. Enabled by default.
-
-@item -fchkp-first-field-has-own-bounds
-@opindex fchkp-first-field-has-own-bounds
-@opindex fno-chkp-first-field-has-own-bounds
-Forces Pointer Bounds Checker to use narrowed bounds for the address of the
-first field in the structure. By default a pointer to the first field has
-the same bounds as a pointer to the whole structure.
-
-@item -fchkp-narrow-to-innermost-array
-@opindex fchkp-narrow-to-innermost-array
-@opindex fno-chkp-narrow-to-innermost-array
-Forces Pointer Bounds Checker to use bounds of the innermost arrays in
-case of nested static array access. By default this option is disabled and
-bounds of the outermost array are used.
-
-@item -fchkp-optimize
-@opindex fchkp-optimize
-@opindex fno-chkp-optimize
-Enables Pointer Bounds Checker optimizations. Enabled by default at
-optimization levels @option{-O}, @option{-O2}, @option{-O3}.
-
-@item -fchkp-use-fast-string-functions
-@opindex fchkp-use-fast-string-functions
-@opindex fno-chkp-use-fast-string-functions
-Enables use of @code{*_nobnd} versions of string functions (not copying bounds)
-by Pointer Bounds Checker. Disabled by default.
-
-@item -fchkp-use-nochk-string-functions
-@opindex fchkp-use-nochk-string-functions
-@opindex fno-chkp-use-nochk-string-functions
-Enables use of @code{*_nochk} versions of string functions (not checking bounds)
-by Pointer Bounds Checker. Disabled by default.
-
-@item -fchkp-use-static-bounds
-@opindex fchkp-use-static-bounds
-@opindex fno-chkp-use-static-bounds
-Allow Pointer Bounds Checker to generate static bounds holding
-bounds of static variables. Enabled by default.
-
-@item -fchkp-use-static-const-bounds
-@opindex fchkp-use-static-const-bounds
-@opindex fno-chkp-use-static-const-bounds
-Use statically-initialized bounds for constant bounds instead of
-generating them each time they are required. By default enabled when
-@option{-fchkp-use-static-bounds} is enabled.
-
-@item -fchkp-treat-zero-dynamic-size-as-infinite
-@opindex fchkp-treat-zero-dynamic-size-as-infinite
-@opindex fno-chkp-treat-zero-dynamic-size-as-infinite
-With this option, objects with incomplete type whose
-dynamically-obtained size is zero are treated as having infinite size
-instead by Pointer Bounds
-Checker. This option may be helpful if a program is linked with a library
-missing size information for some symbols. Disabled by default.
-
-@item -fchkp-check-read
-@opindex fchkp-check-read
-@opindex fno-chkp-check-read
-Instructs Pointer Bounds Checker to generate checks for all read
-accesses to memory. Enabled by default.
-
-@item -fchkp-check-write
-@opindex fchkp-check-write
-@opindex fno-chkp-check-write
-Instructs Pointer Bounds Checker to generate checks for all write
-accesses to memory. Enabled by default.
-
-@item -fchkp-store-bounds
-@opindex fchkp-store-bounds
-@opindex fno-chkp-store-bounds
-Instructs Pointer Bounds Checker to generate bounds stores for
-pointer writes. Enabled by default.
-
-@item -fchkp-instrument-calls
-@opindex fchkp-instrument-calls
-@opindex fno-chkp-instrument-calls
-Instructs Pointer Bounds Checker to pass pointer bounds to calls.
-Enabled by default.
-
-@item -fchkp-instrument-marked-only
-@opindex fchkp-instrument-marked-only
-@opindex fno-chkp-instrument-marked-only
-Instructs Pointer Bounds Checker to instrument only functions
-marked with the @code{bnd_instrument} attribute
-(@pxref{Function Attributes}). Disabled by default.
-
-@item -fchkp-use-wrappers
-@opindex fchkp-use-wrappers
-@opindex fno-chkp-use-wrappers
-Allows Pointer Bounds Checker to replace calls to built-in functions
-with calls to wrapper functions. When @option{-fchkp-use-wrappers}
-is used to link a program, the GCC driver automatically links
-against @file{libmpxwrappers}. See also @option{-static-libmpxwrappers}.
-Enabled by default.
-
@item -fdump-final-insns@r{[}=@var{file}@r{]}
@opindex fdump-final-insns
Dump the final internal representation (RTL) to @var{file}. If the
@@ -6501,22 +6056,6 @@ information describing them as in @file{
Emit DWARF 2 unwind info as compiler generated @code{.eh_frame} section
instead of using GAS @code{.cfi_*} directives.
-@cindex @command{prof}
-@item -p
-@opindex p
-Generate extra code to write profile information suitable for the
-analysis program @command{prof}. You must use this option when compiling
-the source files you want data about, and you must also use it when
-linking.
-
-@cindex @command{gprof}
-@item -pg
-@opindex pg
-Generate extra code to write profile information suitable for the
-analysis program @command{gprof}. You must use this option when compiling
-the source files you want data about, and you must also use it when
-linking.
-
@item -Q
@opindex Q
Makes the compiler print out each function name as it is compiled, and
@@ -6582,83 +6121,6 @@ the function. If it is not present, the
not bounded at compile time and the second field only represents the
bounded part.
-@item -fprofile-arcs
-@opindex fprofile-arcs
-Add code so that program flow @dfn{arcs} are instrumented. During
-execution the program records how many times each branch and call is
-executed and how many times it is taken or returns. When the compiled
-program exits it saves this data to a file called
-@file{@var{auxname}.gcda} for each source file. The data may be used for
-profile-directed optimizations (@option{-fbranch-probabilities}), or for
-test coverage analysis (@option{-ftest-coverage}). Each object file's
-@var{auxname} is generated from the name of the output file, if
-explicitly specified and it is not the final executable, otherwise it is
-the basename of the source file. In both cases any suffix is removed
-(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
-@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
-@xref{Cross-profiling}.
-
-@cindex @command{gcov}
-@item --coverage
-@opindex coverage
-
-This option is used to compile and link code instrumented for coverage
-analysis. The option is a synonym for @option{-fprofile-arcs}
-@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
-linking). See the documentation for those options for more details.
-
-@itemize
-
-@item
-Compile the source files with @option{-fprofile-arcs} plus optimization
-and code generation options. For test coverage analysis, use the
-additional @option{-ftest-coverage} option. You do not need to profile
-every source file in a program.
-
-@item
-Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
-(the latter implies the former).
-
-@item
-Run the program on a representative workload to generate the arc profile
-information. This may be repeated any number of times. You can run
-concurrent instances of your program, and provided that the file system
-supports locking, the data files will be correctly updated. Also
-@code{fork} calls are detected and correctly handled (double counting
-will not happen).
-
-@item
-For profile-directed optimizations, compile the source files again with
-the same optimization and code generation options plus
-@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
-Control Optimization}).
-
-@item
-For test coverage analysis, use @command{gcov} to produce human readable
-information from the @file{.gcno} and @file{.gcda} files. Refer to the
-@command{gcov} documentation for further information.
-
-@end itemize
-
-With @option{-fprofile-arcs}, for each function of your program GCC
-creates a program flow graph, then finds a spanning tree for the graph.
-Only arcs that are not on the spanning tree have to be instrumented: the
-compiler adds code to count the number of times that these arcs are
-executed. When an arc is the only exit or only entrance to a block, the
-instrumentation code can be added to the block; otherwise, a new basic
-block must be created to hold the instrumentation code.
-
-@need 2000
-@item -ftest-coverage
-@opindex ftest-coverage
-Produce a notes file that the @command{gcov} code-coverage utility
-(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
-show program coverage. Each source file's note file is called
-@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
-above for a description of @var{auxname} and instructions on how to
-generate test coverage data. Coverage data matches the source files
-more closely if you do not optimize.
-
@item -fdbg-cnt-list
@opindex fdbg-cnt-list
Print the name and the counter upper bound for all debug counters.
@@ -9838,31 +9300,6 @@ be inconsistent due to missed counter up
GCC uses heuristics to correct or smooth out such inconsistencies. By
default, GCC emits an error message when an inconsistent profile is detected.
-@item -fprofile-dir=@var{path}
-@opindex fprofile-dir
-
-Set the directory to search for the profile data files in to @var{path}.
-This option affects only the profile data generated by
-@option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs}
-and used by @option{-fprofile-use} and @option{-fbranch-probabilities}
-and its related options. Both absolute and relative paths can be used.
-By default, GCC uses the current directory as @var{path}, thus the
-profile data file appears in the same directory as the object file.
-
-@item -fprofile-generate
-@itemx -fprofile-generate=@var{path}
-@opindex fprofile-generate
-
-Enable options usually used for instrumenting application to produce
-profile useful for later recompilation with profile feedback based
-optimization. You must use @option{-fprofile-generate} both when
-compiling and when linking your program.
-
-The following options are enabled: @option{-fprofile-arcs}, @option{-fprofile-values}, @option{-fvpt}.
-
-If @var{path} is specified, GCC looks at the @var{path} to find
-the profile feedback data files. See @option{-fprofile-dir}.
-
@item -fprofile-use
@itemx -fprofile-use=@var{path}
@opindex fprofile-use
@@ -9873,6 +9310,10 @@ which are generally profitable only with
@option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer},
@option{-ftree-vectorize}, and @option{ftree-loop-distribute-patterns}.
+Before you can use this option, you must first generate profiling information.
+@xref{Optimize Options}, for information about the @option{-fprofile-generate}
+option.
+
By default, GCC emits an error message if the feedback profiles do not
match the source code. This error can be turned into a warning by using
@option{-Wcoverage-mismatch}. Note this may result in poorly optimized
@@ -10156,8 +9597,8 @@ section includes experimental options th
@item -fbranch-probabilities
@opindex fbranch-probabilities
After running a program compiled with @option{-fprofile-arcs}
-(@pxref{Debugging Options,, Options for Debugging Your Program or
-@command{gcc}}), you can compile it a second time using
+(@pxref{Instrumentation Options}),
+you can compile it a second time using
@option{-fbranch-probabilities}, to improve optimizations based on
the number of times each branch was taken. When a program
compiled with @option{-fprofile-arcs} exits, it saves arc execution
@@ -10304,30 +9745,6 @@ threading.
When performing branch target register load optimization, don't reuse
branch target registers within any basic block.
-@item -fstack-protector
-@opindex fstack-protector
-Emit extra code to check for buffer overflows, such as stack smashing
-attacks. This is done by adding a guard variable to functions with
-vulnerable objects. This includes functions that call @code{alloca}, and
-functions with buffers larger than 8 bytes. The guards are initialized
-when a function is entered and then checked when the function exits.
-If a guard check fails, an error message is printed and the program exits.
-
-@item -fstack-protector-all
-@opindex fstack-protector-all
-Like @option{-fstack-protector} except that all functions are protected.
-
-@item -fstack-protector-strong
-@opindex fstack-protector-strong
-Like @option{-fstack-protector} but includes additional functions to
-be protected --- those that have local array definitions, or have
-references to local frame addresses.
-
-@item -fstack-protector-explicit
-@opindex fstack-protector-explicit
-Like @option{-fstack-protector} but only protects those functions which
-have the @code{stack_protect} attribute.
-
@item -fstdarg-opt
@opindex fstdarg-opt
Optimize the prologue of variadic argument functions with respect to usage of
@@ -11283,6 +10700,792 @@ use-def chain.
@end table
@end table
+@node Instrumentation Options
+@section Program Instrumentation Options
+@cindex instrumentation options
+@cindex program instrumentation options
+@cindex run-time error checking options
+@cindex profiling options
+@cindex options, program instrumentation
+@cindex options, run-time error checking
+@cindex options, profiling
+
+GCC supports a number of command-line options that control adding
+run-time instrumentation to the code it normally generates.
+For example, one purpose of instrumentation is collect profiling
+statistics for use in finding program hot spots, code coverage
+analysis, or profile-guided optimizations.
+Another class of program instrumentation is adding run-time checking
+to detect programming errors like invalid pointer
+dereferences or out-of-bounds array accesses, as well as deliberately
+hostile attacks such as stack smashing or C++ vtable hijacking.
+There is also a general hook which can be used to implement other
+forms of tracing or function-level instrumentation for debug or
+program analysis purposes.
+
+@table @gcctabopt
+@cindex @command{prof}
+@item -p
+@opindex p
+Generate extra code to write profile information suitable for the
+analysis program @command{prof}. You must use this option when compiling
+the source files you want data about, and you must also use it when
+linking.
+
+@cindex @command{gprof}
+@item -pg
+@opindex pg
+Generate extra code to write profile information suitable for the
+analysis program @command{gprof}. You must use this option when compiling
+the source files you want data about, and you must also use it when
+linking.
+
+@item -fprofile-arcs
+@opindex fprofile-arcs
+Add code so that program flow @dfn{arcs} are instrumented. During
+execution the program records how many times each branch and call is
+executed and how many times it is taken or returns. When the compiled
+program exits it saves this data to a file called
+@file{@var{auxname}.gcda} for each source file. The data may be used for
+profile-directed optimizations (@option{-fbranch-probabilities}), or for
+test coverage analysis (@option{-ftest-coverage}). Each object file's
+@var{auxname} is generated from the name of the output file, if
+explicitly specified and it is not the final executable, otherwise it is
+the basename of the source file. In both cases any suffix is removed
+(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
+@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
+@xref{Cross-profiling}.
+
+@cindex @command{gcov}
+@item --coverage
+@opindex coverage
+
+This option is used to compile and link code instrumented for coverage
+analysis. The option is a synonym for @option{-fprofile-arcs}
+@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
+linking). See the documentation for those options for more details.
+
+@itemize
+
+@item
+Compile the source files with @option{-fprofile-arcs} plus optimization
+and code generation options. For test coverage analysis, use the
+additional @option{-ftest-coverage} option. You do not need to profile
+every source file in a program.
+
+@item
+Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
+(the latter implies the former).
+
+@item
+Run the program on a representative workload to generate the arc profile
+information. This may be repeated any number of times. You can run
+concurrent instances of your program, and provided that the file system
+supports locking, the data files will be correctly updated. Also
+@code{fork} calls are detected and correctly handled (double counting
+will not happen).
+
+@item
+For profile-directed optimizations, compile the source files again with
+the same optimization and code generation options plus
+@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
+Control Optimization}).
+
+@item
+For test coverage analysis, use @command{gcov} to produce human readable
+information from the @file{.gcno} and @file{.gcda} files. Refer to the
+@command{gcov} documentation for further information.
+
+@end itemize
+
+With @option{-fprofile-arcs}, for each function of your program GCC
+creates a program flow graph, then finds a spanning tree for the graph.
+Only arcs that are not on the spanning tree have to be instrumented: the
+compiler adds code to count the number of times that these arcs are
+executed. When an arc is the only exit or only entrance to a block, the
+instrumentation code can be added to the block; otherwise, a new basic
+block must be created to hold the instrumentation code.
+
+@need 2000
+@item -ftest-coverage
+@opindex ftest-coverage
+Produce a notes file that the @command{gcov} code-coverage utility
+(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
+show program coverage. Each source file's note file is called
+@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
+above for a description of @var{auxname} and instructions on how to
+generate test coverage data. Coverage data matches the source files
+more closely if you do not optimize.
+
+@item -fprofile-dir=@var{path}
+@opindex fprofile-dir
+
+Set the directory to search for the profile data files in to @var{path}.
+This option affects only the profile data generated by
+@option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs}
+and used by @option{-fprofile-use} and @option{-fbranch-probabilities}
+and its related options. Both absolute and relative paths can be used.
+By default, GCC uses the current directory as @var{path}, thus the
+profile data file appears in the same directory as the object file.
+
+@item -fprofile-generate
+@itemx -fprofile-generate=@var{path}
+@opindex fprofile-generate
+
+Enable options usually used for instrumenting application to produce
+profile useful for later recompilation with profile feedback based
+optimization. You must use @option{-fprofile-generate} both when
+compiling and when linking your program.
+
+The following options are enabled: @option{-fprofile-arcs}, @option{-fprofile-values}, @option{-fvpt}.
+
+If @var{path} is specified, GCC looks at the @var{path} to find
+the profile feedback data files. See @option{-fprofile-dir}.
+
+To optimize the program based on the collected profile information, use
+@option{-fprofile-use}. @xref{Optimize Options}, for more information.
+
+@item -fsanitize=address
+@opindex fsanitize=address
+Enable AddressSanitizer, a fast memory error detector.
+Memory access instructions are instrumented to detect
+out-of-bounds and use-after-free bugs.
+See @uref{https://github.com/google/sanitizers/wiki/AddressSanitizer} for
+more details. The run-time behavior can be influenced using the
+@env{ASAN_OPTIONS} environment variable. When set to @code{help=1},
+the available options are shown at startup of the instrumended program. See
+@url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags}
+for a list of supported options.
+
+@item -fsanitize=kernel-address
+@opindex fsanitize=kernel-address
+Enable AddressSanitizer for Linux kernel.
+See @uref{https://github.com/google/kasan/wiki} for more details.
+
+@item -fsanitize=thread
+@opindex fsanitize=thread
+Enable ThreadSanitizer, a fast data race detector.
+Memory access instructions are instrumented to detect
+data race bugs. See @uref{https://github.com/google/sanitizers/wiki#threadsanitizer} for more
+details. The run-time behavior can be influenced using the @env{TSAN_OPTIONS}
+environment variable; see
+@url{https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags} for a list of
+supported options.
+
+@item -fsanitize=leak
+@opindex fsanitize=leak
+Enable LeakSanitizer, a memory leak detector.
+This option only matters for linking of executables and if neither
+@option{-fsanitize=address} nor @option{-fsanitize=thread} is used. In that
+case the executable is linked against a library that overrides @code{malloc}
+and other allocator functions. See
+@uref{https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer} for more
+details. The run-time behavior can be influenced using the
+@env{LSAN_OPTIONS} environment variable.
+
+@item -fsanitize=undefined
+@opindex fsanitize=undefined
+Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector.
+Various computations are instrumented to detect undefined behavior
+at runtime. Current suboptions are:
+
+@table @gcctabopt
+
+@item -fsanitize=shift
+@opindex fsanitize=shift
+This option enables checking that the result of a shift operation is
+not undefined. Note that what exactly is considered undefined differs
+slightly between C and C++, as well as between ISO C90 and C99, etc.
+
+@item -fsanitize=integer-divide-by-zero
+@opindex fsanitize=integer-divide-by-zero
+Detect integer division by zero as well as @code{INT_MIN / -1} division.
+
+@item -fsanitize=unreachable
+@opindex fsanitize=unreachable
+With this option, the compiler turns the @code{__builtin_unreachable}
+call into a diagnostics message call instead. When reaching the
+@code{__builtin_unreachable} call, the behavior is undefined.
+
+@item -fsanitize=vla-bound
+@opindex fsanitize=vla-bound
+This option instructs the compiler to check that the size of a variable
+length array is positive.
+
+@item -fsanitize=null
+@opindex fsanitize=null
+This option enables pointer checking. Particularly, the application
+built with this option turned on will issue an error message when it
+tries to dereference a NULL pointer, or if a reference (possibly an
+rvalue reference) is bound to a NULL pointer, or if a method is invoked
+on an object pointed by a NULL pointer.
+
+@item -fsanitize=return
+@opindex fsanitize=return
+This option enables return statement checking. Programs
+built with this option turned on will issue an error message
+when the end of a non-void function is reached without actually
+returning a value. This option works in C++ only.
+
+@item -fsanitize=signed-integer-overflow
+@opindex fsanitize=signed-integer-overflow
+This option enables signed integer overflow checking. We check that
+the result of @code{+}, @code{*}, and both unary and binary @code{-}
+does not overflow in the signed arithmetics. Note, integer promotion
+rules must be taken into account. That is, the following is not an
+overflow:
+@smallexample
+signed char a = SCHAR_MAX;
+a++;
+@end smallexample
+
+@item -fsanitize=bounds
+@opindex fsanitize=bounds
+This option enables instrumentation of array bounds. Various out of bounds
+accesses are detected. Flexible array members, flexible array member-like
+arrays, and initializers of variables with static storage are not instrumented.
+
+@item -fsanitize=bounds-strict
+@opindex fsanitize=bounds-strict
+This option enables strict instrumentation of array bounds. Most out of bounds
+accesses are detected, including flexible array members and flexible array
+member-like arrays. Initializers of variables with static storage are not
+instrumented.
+
+@item -fsanitize=alignment
+@opindex fsanitize=alignment
+
+This option enables checking of alignment of pointers when they are
+dereferenced, or when a reference is bound to insufficiently aligned target,
+or when a method or constructor is invoked on insufficiently aligned object.
+
+@item -fsanitize=object-size
+@opindex fsanitize=object-size
+This option enables instrumentation of memory references using the
+@code{__builtin_object_size} function. Various out of bounds pointer
+accesses are detected.
+
+@item -fsanitize=float-divide-by-zero
+@opindex fsanitize=float-divide-by-zero
+Detect floating-point division by zero. Unlike other similar options,
+@option{-fsanitize=float-divide-by-zero} is not enabled by
+@option{-fsanitize=undefined}, since floating-point division by zero can
+be a legitimate way of obtaining infinities and NaNs.
+
+@item -fsanitize=float-cast-overflow
+@opindex fsanitize=float-cast-overflow
+This option enables floating-point type to integer conversion checking.
+We check that the result of the conversion does not overflow.
+Unlike other similar options, @option{-fsanitize=float-cast-overflow} is
+not enabled by @option{-fsanitize=undefined}.
+This option does not work well with @code{FE_INVALID} exceptions enabled.
+
+@item -fsanitize=nonnull-attribute
+@opindex fsanitize=nonnull-attribute
+
+This option enables instrumentation of calls, checking whether null values
+are not passed to arguments marked as requiring a non-null value by the
+@code{nonnull} function attribute.
+
+@item -fsanitize=returns-nonnull-attribute
+@opindex fsanitize=returns-nonnull-attribute
+
+This option enables instrumentation of return statements in functions
+marked with @code{returns_nonnull} function attribute, to detect returning
+of null values from such functions.
+
+@item -fsanitize=bool
+@opindex fsanitize=bool
+
+This option enables instrumentation of loads from bool. If a value other
+than 0/1 is loaded, a run-time error is issued.
+
+@item -fsanitize=enum
+@opindex fsanitize=enum
+
+This option enables instrumentation of loads from an enum type. If
+a value outside the range of values for the enum type is loaded,
+a run-time error is issued.
+
+@item -fsanitize=vptr
+@opindex fsanitize=vptr
+
+This option enables instrumentation of C++ member function calls, member
+accesses and some conversions between pointers to base and derived classes,
+to verify the referenced object has the correct dynamic type.
+
+@end table
+
+While @option{-ftrapv} causes traps for signed overflows to be emitted,
+@option{-fsanitize=undefined} gives a diagnostic message.
+This currently works only for the C family of languages.
+
+@item -fno-sanitize=all
+@opindex fno-sanitize=all
+
+This option disables all previously enabled sanitizers.
+@option{-fsanitize=all} is not allowed, as some sanitizers cannot be used
+together.
+
+@item -fasan-shadow-offset=@var{number}
+@opindex fasan-shadow-offset
+This option forces GCC to use custom shadow offset in AddressSanitizer checks.
+It is useful for experimenting with different shadow memory layouts in
+Kernel AddressSanitizer.
+
+@item -fsanitize-sections=@var{s1},@var{s2},...
+@opindex fsanitize-sections
+Sanitize global variables in selected user-defined sections. @var{si} may
+contain wildcards.
+
+@item -fsanitize-recover@r{[}=@var{opts}@r{]}
+@opindex fsanitize-recover
+@opindex fno-sanitize-recover
+@option{-fsanitize-recover=} controls error recovery mode for sanitizers
+mentioned in comma-separated list of @var{opts}. Enabling this option
+for a sanitizer component causes it to attempt to continue
+running the program as if no error happened. This means multiple
+runtime errors can be reported in a single program run, and the exit
+code of the program may indicate success even when errors
+have been reported. The @option{-fno-sanitize-recover=} option
+can be used to alter
+this behavior: only the first detected error is reported
+and program then exits with a non-zero exit code.
+
+Currently this feature only works for @option{-fsanitize=undefined} (and its suboptions
+except for @option{-fsanitize=unreachable} and @option{-fsanitize=return}),
+@option{-fsanitize=float-cast-overflow}, @option{-fsanitize=float-divide-by-zero},
+@option{-fsanitize=kernel-address} and @option{-fsanitize=address}.
+For these sanitizers error recovery is turned on by default, except @option{-fsanitize=address},
+for which this feature is experimental.
+@option{-fsanitize-recover=all} and @option{-fno-sanitize-recover=all} is also
+accepted, the former enables recovery for all sanitizers that support it,
+the latter disables recovery for all sanitizers that support it.
+
+Syntax without explicit @var{opts} parameter is deprecated. It is equivalent to
+@smallexample
+-fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero
+@end smallexample
+@noindent
+Similarly @option{-fno-sanitize-recover} is equivalent to
+@smallexample
+-fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero
+@end smallexample
+
+@item -fsanitize-undefined-trap-on-error
+@opindex fsanitize-undefined-trap-on-error
+The @option{-fsanitize-undefined-trap-on-error} option instructs the compiler to
+report undefined behavior using @code{__builtin_trap} rather than
+a @code{libubsan} library routine. The advantage of this is that the
+@code{libubsan} library is not needed and is not linked in, so this
+is usable even in freestanding environments.
+
+@item -fsanitize-coverage=trace-pc
+@opindex fsanitize-coverage=trace-pc
+Enable coverage-guided fuzzing code instrumentation.
+Inserts call to __sanitizer_cov_trace_pc into every basic block.
+
+@item -fbounds-check
+@opindex fbounds-check
+For front ends that support it, generate additional code to check that
+indices used to access arrays are within the declared range. This is
+currently only supported by the Java and Fortran front ends, where
+this option defaults to true and false respectively.
+
+@item -fcheck-pointer-bounds
+@opindex fcheck-pointer-bounds
+@opindex fno-check-pointer-bounds
+@cindex Pointer Bounds Checker options
+Enable Pointer Bounds Checker instrumentation. Each memory reference
+is instrumented with checks of the pointer used for memory access against
+bounds associated with that pointer.
+
+Currently there
+is only an implementation for Intel MPX available, thus x86 target
+and @option{-mmpx} are required to enable this feature.
+MPX-based instrumentation requires
+a runtime library to enable MPX in hardware and handle bounds
+violation signals. By default when @option{-fcheck-pointer-bounds}
+and @option{-mmpx} options are used to link a program, the GCC driver
+links against the @file{libmpx} runtime library and @file{libmpxwrappers}
+library. It also passes '-z bndplt' to a linker in case it supports this
+option (which is checked on libmpx configuration). Note that old versions
+of linker may ignore option. Gold linker doesn't support '-z bndplt'
+option. With no '-z bndplt' support in linker all calls to dynamic libraries
+lose passed bounds reducing overall protection level. It's highly
+recommended to use linker with '-z bndplt' support. In case such linker
+is not available it is adviced to always use @option{-static-libmpxwrappers}
+for better protection level or use @option{-static} to completely avoid
+external calls to dynamic libraries. MPX-based instrumentation
+may be used for debugging and also may be included in production code
+to increase program security. Depending on usage, you may
+have different requirements for the runtime library. The current version
+of the MPX runtime library is more oriented for use as a debugging
+tool. MPX runtime library usage implies @option{-lpthread}. See
+also @option{-static-libmpx}. The runtime library behavior can be
+influenced using various @env{CHKP_RT_*} environment variables. See
+@uref{https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler}
+for more details.
+
+Generated instrumentation may be controlled by various
+@option{-fchkp-*} options and by the @code{bnd_variable_size}
+structure field attribute (@pxref{Type Attributes}) and
+@code{bnd_legacy}, and @code{bnd_instrument} function attributes
+(@pxref{Function Attributes}). GCC also provides a number of built-in
+functions for controlling the Pointer Bounds Checker. @xref{Pointer
+Bounds Checker builtins}, for more information.
+
+@item -fchecking
+@opindex fchecking
+@opindex fno-checking
+Enable internal consistency checking. The default depends on
+the compiler configuration.
+
+@item -fchkp-check-incomplete-type
+@opindex fchkp-check-incomplete-type
+@opindex fno-chkp-check-incomplete-type
+Generate pointer bounds checks for variables with incomplete type.
+Enabled by default.
+
+@item -fchkp-narrow-bounds
+@opindex fchkp-narrow-bounds
+@opindex fno-chkp-narrow-bounds
+Controls bounds used by Pointer Bounds Checker for pointers to object
+fields. If narrowing is enabled then field bounds are used. Otherwise
+object bounds are used. See also @option{-fchkp-narrow-to-innermost-array}
+and @option{-fchkp-first-field-has-own-bounds}. Enabled by default.
+
+@item -fchkp-first-field-has-own-bounds
+@opindex fchkp-first-field-has-own-bounds
+@opindex fno-chkp-first-field-has-own-bounds
+Forces Pointer Bounds Checker to use narrowed bounds for the address of the
+first field in the structure. By default a pointer to the first field has
+the same bounds as a pointer to the whole structure.
+
+@item -fchkp-narrow-to-innermost-array
+@opindex fchkp-narrow-to-innermost-array
+@opindex fno-chkp-narrow-to-innermost-array
+Forces Pointer Bounds Checker to use bounds of the innermost arrays in
+case of nested static array access. By default this option is disabled and
+bounds of the outermost array are used.
+
+@item -fchkp-optimize
+@opindex fchkp-optimize
+@opindex fno-chkp-optimize
+Enables Pointer Bounds Checker optimizations. Enabled by default at
+optimization levels @option{-O}, @option{-O2}, @option{-O3}.
+
+@item -fchkp-use-fast-string-functions
+@opindex fchkp-use-fast-string-functions
+@opindex fno-chkp-use-fast-string-functions
+Enables use of @code{*_nobnd} versions of string functions (not copying bounds)
+by Pointer Bounds Checker. Disabled by default.
+
+@item -fchkp-use-nochk-string-functions
+@opindex fchkp-use-nochk-string-functions
+@opindex fno-chkp-use-nochk-string-functions
+Enables use of @code{*_nochk} versions of string functions (not checking bounds)
+by Pointer Bounds Checker. Disabled by default.
+
+@item -fchkp-use-static-bounds
+@opindex fchkp-use-static-bounds
+@opindex fno-chkp-use-static-bounds
+Allow Pointer Bounds Checker to generate static bounds holding
+bounds of static variables. Enabled by default.
+
+@item -fchkp-use-static-const-bounds
+@opindex fchkp-use-static-const-bounds
+@opindex fno-chkp-use-static-const-bounds
+Use statically-initialized bounds for constant bounds instead of
+generating them each time they are required. By default enabled when
+@option{-fchkp-use-static-bounds} is enabled.
+
+@item -fchkp-treat-zero-dynamic-size-as-infinite
+@opindex fchkp-treat-zero-dynamic-size-as-infinite
+@opindex fno-chkp-treat-zero-dynamic-size-as-infinite
+With this option, objects with incomplete type whose
+dynamically-obtained size is zero are treated as having infinite size
+instead by Pointer Bounds
+Checker. This option may be helpful if a program is linked with a library
+missing size information for some symbols. Disabled by default.
+
+@item -fchkp-check-read
+@opindex fchkp-check-read
+@opindex fno-chkp-check-read
+Instructs Pointer Bounds Checker to generate checks for all read
+accesses to memory. Enabled by default.
+
+@item -fchkp-check-write
+@opindex fchkp-check-write
+@opindex fno-chkp-check-write
+Instructs Pointer Bounds Checker to generate checks for all write
+accesses to memory. Enabled by default.
+
+@item -fchkp-store-bounds
+@opindex fchkp-store-bounds
+@opindex fno-chkp-store-bounds
+Instructs Pointer Bounds Checker to generate bounds stores for
+pointer writes. Enabled by default.
+
+@item -fchkp-instrument-calls
+@opindex fchkp-instrument-calls
+@opindex fno-chkp-instrument-calls
+Instructs Pointer Bounds Checker to pass pointer bounds to calls.
+Enabled by default.
+
+@item -fchkp-instrument-marked-only
+@opindex fchkp-instrument-marked-only
+@opindex fno-chkp-instrument-marked-only
+Instructs Pointer Bounds Checker to instrument only functions
+marked with the @code{bnd_instrument} attribute
+(@pxref{Function Attributes}). Disabled by default.
+
+@item -fchkp-use-wrappers
+@opindex fchkp-use-wrappers
+@opindex fno-chkp-use-wrappers
+Allows Pointer Bounds Checker to replace calls to built-in functions
+with calls to wrapper functions. When @option{-fchkp-use-wrappers}
+is used to link a program, the GCC driver automatically links
+against @file{libmpxwrappers}. See also @option{-static-libmpxwrappers}.
+Enabled by default.
+
+@item -fstack-protector
+@opindex fstack-protector
+Emit extra code to check for buffer overflows, such as stack smashing
+attacks. This is done by adding a guard variable to functions with
+vulnerable objects. This includes functions that call @code{alloca}, and
+functions with buffers larger than 8 bytes. The guards are initialized
+when a function is entered and then checked when the function exits.
+If a guard check fails, an error message is printed and the program exits.
+
+@item -fstack-protector-all
+@opindex fstack-protector-all
+Like @option{-fstack-protector} except that all functions are protected.
+
+@item -fstack-protector-strong
+@opindex fstack-protector-strong
+Like @option{-fstack-protector} but includes additional functions to
+be protected --- those that have local array definitions, or have
+references to local frame addresses.
+
+@item -fstack-protector-explicit
+@opindex fstack-protector-explicit
+Like @option{-fstack-protector} but only protects those functions which
+have the @code{stack_protect} attribute.
+
+@item -fstack-check
+@opindex fstack-check
+Generate code to verify that you do not go beyond the boundary of the
+stack. You should specify this flag if you are running in an
+environment with multiple threads, but you only rarely need to specify it in
+a single-threaded environment since stack overflow is automatically
+detected on nearly all systems if there is only one stack.
+
+Note that this switch does not actually cause checking to be done; the
+operating system or the language runtime must do that. The switch causes
+generation of code to ensure that they see the stack being extended.
+
+You can additionally specify a string parameter: @samp{no} means no
+checking, @samp{generic} means force the use of old-style checking,
+@samp{specific} means use the best checking method and is equivalent
+to bare @option{-fstack-check}.
+
+Old-style checking is a generic mechanism that requires no specific
+target support in the compiler but comes with the following drawbacks:
+
+@enumerate
+@item
+Modified allocation strategy for large objects: they are always
+allocated dynamically if their size exceeds a fixed threshold.
+
+@item
+Fixed limit on the size of the static frame of functions: when it is
+topped by a particular function, stack checking is not reliable and
+a warning is issued by the compiler.
+
+@item
+Inefficiency: because of both the modified allocation strategy and the
+generic implementation, code performance is hampered.
+@end enumerate
+
+Note that old-style stack checking is also the fallback method for
+@samp{specific} if no target support has been added in the compiler.
+
+@item -fstack-limit-register=@var{reg}
+@itemx -fstack-limit-symbol=@var{sym}
+@itemx -fno-stack-limit
+@opindex fstack-limit-register
+@opindex fstack-limit-symbol
+@opindex fno-stack-limit
+Generate code to ensure that the stack does not grow beyond a certain value,
+either the value of a register or the address of a symbol. If a larger
+stack is required, a signal is raised at run time. For most targets,
+the signal is raised before the stack overruns the boundary, so
+it is possible to catch the signal without taking special precautions.
+
+For instance, if the stack starts at absolute address @samp{0x80000000}
+and grows downwards, you can use the flags
+@option{-fstack-limit-symbol=__stack_limit} and
+@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
+of 128KB@. Note that this may only work with the GNU linker.
+
+You can locally override stack limit checking by using the
+@code{no_stack_limit} function attribute (@pxref{Function Attributes}).
+
+@item -fsplit-stack
+@opindex fsplit-stack
+Generate code to automatically split the stack before it overflows.
+The resulting program has a discontiguous stack which can only
+overflow if the program is unable to allocate any more memory. This
+is most useful when running threaded programs, as it is no longer
+necessary to calculate a good stack size to use for each thread. This
+is currently only implemented for the x86 targets running
+GNU/Linux.
+
+When code compiled with @option{-fsplit-stack} calls code compiled
+without @option{-fsplit-stack}, there may not be much stack space
+available for the latter code to run. If compiling all code,
+including library code, with @option{-fsplit-stack} is not an option,
+then the linker can fix up these calls so that the code compiled
+without @option{-fsplit-stack} always has a large stack. Support for
+this is implemented in the gold linker in GNU binutils release 2.21
+and later.
+
+@item -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]}
+@opindex fvtable-verify
+This option is only available when compiling C++ code.
+It turns on (or off, if using @option{-fvtable-verify=none}) the security
+feature that verifies at run time, for every virtual call, that
+the vtable pointer through which the call is made is valid for the type of
+the object, and has not been corrupted or overwritten. If an invalid vtable
+pointer is detected at run time, an error is reported and execution of the
+program is immediately halted.
+
+This option causes run-time data structures to be built at program startup,
+which are used for verifying the vtable pointers.
+The options @samp{std} and @samp{preinit}
+control the timing of when these data structures are built. In both cases the
+data structures are built before execution reaches @code{main}. Using
+@option{-fvtable-verify=std} causes the data structures to be built after
+shared libraries have been loaded and initialized.
+@option{-fvtable-verify=preinit} causes them to be built before shared
+libraries have been loaded and initialized.
+
+If this option appears multiple times in the command line with different
+values specified, @samp{none} takes highest priority over both @samp{std} and
+@samp{preinit}; @samp{preinit} takes priority over @samp{std}.
+
+@item -fvtv-debug
+@opindex fvtv-debug
+When used in conjunction with @option{-fvtable-verify=std} or
+@option{-fvtable-verify=preinit}, causes debug versions of the
+runtime functions for the vtable verification feature to be called.
+This flag also causes the compiler to log information about which
+vtable pointers it finds for each class.
+This information is written to a file named @file{vtv_set_ptr_data.log}
+in the directory named by the environment variable @env{VTV_LOGS_DIR}
+if that is defined or the current working directory otherwise.
+
+Note: This feature @emph{appends} data to the log file. If you want a fresh log
+file, be sure to delete any existing one.
+
+@item -fvtv-counts
+@opindex fvtv-counts
+This is a debugging flag. When used in conjunction with
+@option{-fvtable-verify=std} or @option{-fvtable-verify=preinit}, this
+causes the compiler to keep track of the total number of virtual calls
+it encounters and the number of verifications it inserts. It also
+counts the number of calls to certain run-time library functions
+that it inserts and logs this information for each compilation unit.
+The compiler writes this information to a file named
+@file{vtv_count_data.log} in the directory named by the environment
+variable @env{VTV_LOGS_DIR} if that is defined or the current working
+directory otherwise. It also counts the size of the vtable pointer sets
+for each class, and writes this information to @file{vtv_class_set_sizes.log}
+in the same directory.
+
+Note: This feature @emph{appends} data to the log files. To get fresh log
+files, be sure to delete any existing ones.
+
+@item -finstrument-functions
+@opindex finstrument-functions
+Generate instrumentation calls for entry and exit to functions. Just
+after function entry and just before function exit, the following
+profiling functions are called with the address of the current
+function and its call site. (On some platforms,
+@code{__builtin_return_address} does not work beyond the current
+function, so the call site information may not be available to the
+profiling functions otherwise.)
+
+@smallexample
+void __cyg_profile_func_enter (void *this_fn,
+ void *call_site);
+void __cyg_profile_func_exit (void *this_fn,
+ void *call_site);
+@end smallexample
+
+The first argument is the address of the start of the current function,
+which may be looked up exactly in the symbol table.
+
+This instrumentation is also done for functions expanded inline in other
+functions. The profiling calls indicate where, conceptually, the
+inline function is entered and exited. This means that addressable
+versions of such functions must be available. If all your uses of a
+function are expanded inline, this may mean an additional expansion of
+code size. If you use @code{extern inline} in your C code, an
+addressable version of such functions must be provided. (This is
+normally the case anyway, but if you get lucky and the optimizer always
+expands the functions inline, you might have gotten away without
+providing static copies.)
+
+A function may be given the attribute @code{no_instrument_function}, in
+which case this instrumentation is not done. This can be used, for
+example, for the profiling functions listed above, high-priority
+interrupt routines, and any functions from which the profiling functions
+cannot safely be called (perhaps signal handlers, if the profiling
+routines generate output or allocate memory).
+
+@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
+@opindex finstrument-functions-exclude-file-list
+
+Set the list of functions that are excluded from instrumentation (see
+the description of @option{-finstrument-functions}). If the file that
+contains a function definition matches with one of @var{file}, then
+that function is not instrumented. The match is done on substrings:
+if the @var{file} parameter is a substring of the file name, it is
+considered to be a match.
+
+For example:
+
+@smallexample
+-finstrument-functions-exclude-file-list=/bits/stl,include/sys
+@end smallexample
+
+@noindent
+excludes any inline function defined in files whose pathnames
+contain @file{/bits/stl} or @file{include/sys}.
+
+If, for some reason, you want to include letter @samp{,} in one of
+@var{sym}, write @samp{\,}. For example,
+@option{-finstrument-functions-exclude-file-list='\,\,tmp'}
+(note the single quote surrounding the option).
+
+@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
+@opindex finstrument-functions-exclude-function-list
+
+This is similar to @option{-finstrument-functions-exclude-file-list},
+but this option sets the list of function names to be excluded from
+instrumentation. The function name to be matched is its user-visible
+name, such as @code{vector<int> blah(const vector<int> &)}, not the
+internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
+match is done on substrings: if the @var{sym} parameter is a substring
+of the function name, it is considered to be a match. For C99 and C++
+extended identifiers, the function name must be given in UTF-8, not
+using universal character names.
+
+@end table
+
+
@node Preprocessor Options
@section Options Controlling the Preprocessor
@cindex preprocessor options
@@ -11861,13 +12064,6 @@ can figure out the other form by either
it.
@table @gcctabopt
-@item -fbounds-check
-@opindex fbounds-check
-For front ends that support it, generate additional code to check that
-indices used to access arrays are within the declared range. This is
-currently only supported by the Java and Fortran front ends, where
-this option defaults to true and false respectively.
-
@item -fstack-reuse=@var{reuse-level}
@opindex fstack_reuse
This option controls stack space reuse for user declared local/auto variables
@@ -12282,160 +12478,6 @@ code that is not binary compatible with
Additionally, it makes the code suboptimal.
Use it to conform to a non-default application binary interface.
-@item -finstrument-functions
-@opindex finstrument-functions
-Generate instrumentation calls for entry and exit to functions. Just
-after function entry and just before function exit, the following
-profiling functions are called with the address of the current
-function and its call site. (On some platforms,
-@code{__builtin_return_address} does not work beyond the current
-function, so the call site information may not be available to the
-profiling functions otherwise.)
-
-@smallexample
-void __cyg_profile_func_enter (void *this_fn,
- void *call_site);
-void __cyg_profile_func_exit (void *this_fn,
- void *call_site);
-@end smallexample
-
-The first argument is the address of the start of the current function,
-which may be looked up exactly in the symbol table.
-
-This instrumentation is also done for functions expanded inline in other
-functions. The profiling calls indicate where, conceptually, the
-inline function is entered and exited. This means that addressable
-versions of such functions must be available. If all your uses of a
-function are expanded inline, this may mean an additional expansion of
-code size. If you use @code{extern inline} in your C code, an
-addressable version of such functions must be provided. (This is
-normally the case anyway, but if you get lucky and the optimizer always
-expands the functions inline, you might have gotten away without
-providing static copies.)
-
-A function may be given the attribute @code{no_instrument_function}, in
-which case this instrumentation is not done. This can be used, for
-example, for the profiling functions listed above, high-priority
-interrupt routines, and any functions from which the profiling functions
-cannot safely be called (perhaps signal handlers, if the profiling
-routines generate output or allocate memory).
-
-@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
-@opindex finstrument-functions-exclude-file-list
-
-Set the list of functions that are excluded from instrumentation (see
-the description of @option{-finstrument-functions}). If the file that
-contains a function definition matches with one of @var{file}, then
-that function is not instrumented. The match is done on substrings:
-if the @var{file} parameter is a substring of the file name, it is
-considered to be a match.
-
-For example:
-
-@smallexample
--finstrument-functions-exclude-file-list=/bits/stl,include/sys
-@end smallexample
-
-@noindent
-excludes any inline function defined in files whose pathnames
-contain @file{/bits/stl} or @file{include/sys}.
-
-If, for some reason, you want to include letter @samp{,} in one of
-@var{sym}, write @samp{\,}. For example,
-@option{-finstrument-functions-exclude-file-list='\,\,tmp'}
-(note the single quote surrounding the option).
-
-@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
-@opindex finstrument-functions-exclude-function-list
-
-This is similar to @option{-finstrument-functions-exclude-file-list},
-but this option sets the list of function names to be excluded from
-instrumentation. The function name to be matched is its user-visible
-name, such as @code{vector<int> blah(const vector<int> &)}, not the
-internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
-match is done on substrings: if the @var{sym} parameter is a substring
-of the function name, it is considered to be a match. For C99 and C++
-extended identifiers, the function name must be given in UTF-8, not
-using universal character names.
-
-@item -fstack-check
-@opindex fstack-check
-Generate code to verify that you do not go beyond the boundary of the
-stack. You should specify this flag if you are running in an
-environment with multiple threads, but you only rarely need to specify it in
-a single-threaded environment since stack overflow is automatically
-detected on nearly all systems if there is only one stack.
-
-Note that this switch does not actually cause checking to be done; the
-operating system or the language runtime must do that. The switch causes
-generation of code to ensure that they see the stack being extended.
-
-You can additionally specify a string parameter: @samp{no} means no
-checking, @samp{generic} means force the use of old-style checking,
-@samp{specific} means use the best checking method and is equivalent
-to bare @option{-fstack-check}.
-
-Old-style checking is a generic mechanism that requires no specific
-target support in the compiler but comes with the following drawbacks:
-
-@enumerate
-@item
-Modified allocation strategy for large objects: they are always
-allocated dynamically if their size exceeds a fixed threshold.
-
-@item
-Fixed limit on the size of the static frame of functions: when it is
-topped by a particular function, stack checking is not reliable and
-a warning is issued by the compiler.
-
-@item
-Inefficiency: because of both the modified allocation strategy and the
-generic implementation, code performance is hampered.
-@end enumerate
-
-Note that old-style stack checking is also the fallback method for
-@samp{specific} if no target support has been added in the compiler.
-
-@item -fstack-limit-register=@var{reg}
-@itemx -fstack-limit-symbol=@var{sym}
-@itemx -fno-stack-limit
-@opindex fstack-limit-register
-@opindex fstack-limit-symbol
-@opindex fno-stack-limit
-Generate code to ensure that the stack does not grow beyond a certain value,
-either the value of a register or the address of a symbol. If a larger
-stack is required, a signal is raised at run time. For most targets,
-the signal is raised before the stack overruns the boundary, so
-it is possible to catch the signal without taking special precautions.
-
-For instance, if the stack starts at absolute address @samp{0x80000000}
-and grows downwards, you can use the flags
-@option{-fstack-limit-symbol=__stack_limit} and
-@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
-of 128KB@. Note that this may only work with the GNU linker.
-
-You can locally override stack limit checking by using the
-@code{no_stack_limit} function attribute (@pxref{Function Attributes}).
-
-@item -fsplit-stack
-@opindex fsplit-stack
-Generate code to automatically split the stack before it overflows.
-The resulting program has a discontiguous stack which can only
-overflow if the program is unable to allocate any more memory. This
-is most useful when running threaded programs, as it is no longer
-necessary to calculate a good stack size to use for each thread. This
-is currently only implemented for the x86 targets running
-GNU/Linux.
-
-When code compiled with @option{-fsplit-stack} calls code compiled
-without @option{-fsplit-stack}, there may not be much stack space
-available for the latter code to run. If compiling all code,
-including library code, with @option{-fsplit-stack} is not an option,
-then the linker can fix up these calls so that the code compiled
-without @option{-fsplit-stack} always has a large stack. Support for
-this is implemented in the gold linker in GNU binutils release 2.21
-and later.
-
@item -fleading-underscore
@opindex fleading-underscore
This option and its counterpart, @option{-fno-leading-underscore}, forcibly
^ permalink raw reply [flat|nested] 12+ messages in thread* Re: [doc, 5/n] invoke.texi: add new "Program Instrumentation Options" section
2016-01-15 2:18 ` [doc, 5/n] invoke.texi: add new "Program Instrumentation Options" section Sandra Loosemore
@ 2016-01-15 8:39 ` Mikhail Maltsev
2016-01-15 15:52 ` Sandra Loosemore
0 siblings, 1 reply; 12+ messages in thread
From: Mikhail Maltsev @ 2016-01-15 8:39 UTC (permalink / raw)
To: Sandra Loosemore, GCC Patches
On 01/15/2016 05:17 AM, Sandra Loosemore wrote:
> This patch consolidates the documentation of GCC options that add runtime profiling, error checking, or other instrumentation into a single section. Currently these are scattered all over, variously classified as debugging options, code generation options, optimization options, etc.
>
> Here is the list of options that I moved into the new section:
>
> @gccoptlist{-p -pg -fprofile-arcs --coverage -ftest-coverage @gol
(snip)
The list mentions "-fchecking", but this option is not related to
instrumentation. In just enables consistency checks of the compiler's
internal state, i.e. it is more related to debugging GCC itself.
--
Regards,
Mikhail Maltsev
^ permalink raw reply [flat|nested] 12+ messages in thread* Re: [doc, 5/n] invoke.texi: add new "Program Instrumentation Options" section
2016-01-15 8:39 ` Mikhail Maltsev
@ 2016-01-15 15:52 ` Sandra Loosemore
0 siblings, 0 replies; 12+ messages in thread
From: Sandra Loosemore @ 2016-01-15 15:52 UTC (permalink / raw)
To: Mikhail Maltsev, GCC Patches
On 01/15/2016 01:39 AM, Mikhail Maltsev wrote:
> On 01/15/2016 05:17 AM, Sandra Loosemore wrote:
>> This patch consolidates the documentation of GCC options that add runtime profiling, error checking, or other instrumentation into a single section. Currently these are scattered all over, variously classified as debugging options, code generation options, optimization options, etc.
>>
>> Here is the list of options that I moved into the new section:
>>
>> @gccoptlist{-p -pg -fprofile-arcs --coverage -ftest-coverage @gol
> (snip)
>
> The list mentions "-fchecking", but this option is not related to
> instrumentation. In just enables consistency checks of the compiler's
> internal state, i.e. it is more related to debugging GCC itself.
Yes, you're right -- I was confused by it being buried in the middle of
the pointer bounds checking options. :-( I'll move it back to its
previous category.
-Sandra
^ permalink raw reply [flat|nested] 12+ messages in thread
* [doc, 6/n] invoke.texi: split debugging options into programmer vs developer sections
2016-01-10 23:50 [doc, 0/n] improve organization of invoke.texi Sandra Loosemore
` (6 preceding siblings ...)
2016-01-15 2:18 ` [doc, 5/n] invoke.texi: add new "Program Instrumentation Options" section Sandra Loosemore
@ 2016-01-17 4:12 ` Sandra Loosemore
7 siblings, 0 replies; 12+ messages in thread
From: Sandra Loosemore @ 2016-01-17 4:12 UTC (permalink / raw)
To: GCC Patches
[-- Attachment #1: Type: text/plain, Size: 4197 bytes --]
This is the last planned part of my series to try to make it easier for
users to find information about command-line options (although as I've
been going through this chapter I've been finding places that need
copy-editing or technical corrections, which I'll handle separately).
In this part, I've split the options relating to debugging GCC itself
into a new section, separate from the one about producing debuggable code.
Here's the list of options remaining in the "Debugging Options" section:
@gccoptlist{-g -g@var{level} -gcoff -gdwarf-@var{version} @gol
-ggdb -grecord-gcc-switches -gno-record-gcc-switches @gol
-gstabs -gstabs+ -gstrict-dwarf -gno-strict-dwarf @gol
-gvms -gxcoff -gxcoff+ -gz@r{[}=@var{type}@r{]} @gol
-fdebug-prefix-map=@var{old}=@var{new} -fdebug-types-section @gol
-feliminate-dwarf2-dups -fno-eliminate-unused-debug-types @gol
-femit-struct-debug-baseonly -femit-struct-debug-reduced @gol
-femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol
-feliminate-unused-debug-symbols -femit-class-debug-always @gol
-fno-merge-debug-strings -fno-dwarf2-cfi-asm @gol
-fvar-tracking -fvar-tracking-assignments}
And here's the list in the new "GCC Developer Options" section:
@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
-fchecking -fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol
-fdisable-ipa-@var{pass_name} @gol
-fdisable-rtl-@var{pass_name} @gol
-fdisable-rtl-@var{pass-name}=@var{range-list} @gol
-fdisable-tree-@var{pass_name} @gol
-fdisable-tree-@var{pass-name}=@var{range-list} @gol
-fdump-noaddr -fdump-unnumbered -fdump-unnumbered-links @gol
-fdump-translation-unit@r{[}-@var{n}@r{]} @gol
-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
-fdump-ipa-all -fdump-ipa-cgraph -fdump-ipa-inline @gol
-fdump-passes @gol
-fdump-rtl-@var{pass} -fdump-rtl-@var{pass}=@var{filename} @gol
-fdump-statistics @gol
-fdump-tree-all @gol
-fdump-tree-original@r{[}-@var{n}@r{]} @gol
-fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
-fdump-tree-cfg -fdump-tree-alias @gol
-fdump-tree-ch @gol
-fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
-fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
-fdump-tree-gimple@r{[}-raw@r{]} @gol
-fdump-tree-dom@r{[}-@var{n}@r{]} @gol
-fdump-tree-dse@r{[}-@var{n}@r{]} @gol
-fdump-tree-phiprop@r{[}-@var{n}@r{]} @gol
-fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
-fdump-tree-backprop@r{[}-@var{n}@r{]} @gol
-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
-fdump-tree-nrv -fdump-tree-vect @gol
-fdump-tree-sink @gol
-fdump-tree-sra@r{[}-@var{n}@r{]} @gol
-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
-fdump-tree-fre@r{[}-@var{n}@r{]} @gol
-fdump-tree-vtable-verify @gol
-fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
-fdump-tree-split-paths@r{[}-@var{n}@r{]} @gol
-fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
-fdump-final-insns=@var{file} @gol
-fcompare-debug@r{[}=@var{opts}@r{]} -fcompare-debug-second @gol
-fenable-@var{kind}-@var{pass} @gol
-fenable-@var{kind}-@var{pass}=@var{range-list} @gol
-fira-verbose=@var{n} @gol
-flto-report -flto-report-wpa -fmem-report-wpa @gol
-fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report @gol
-fopt-info -fopt-info-@var{options}@r{[}=@var{file}@r{]} @gol
-fprofile-report @gol
-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
-fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol
-fstats -fstack-usage -ftime-report @gol
-fvar-tracking-assignments-toggle -gtoggle @gol
-print-file-name=@var{library} -print-libgcc-file-name @gol
-print-multi-directory -print-multi-lib -print-multi-os-directory @gol
-print-prog-name=@var{program} -print-search-dirs -Q @gol
-print-sysroot -print-sysroot-headers-suffix @gol
-save-temps -save-temps=cwd -save-temps=obj -time@r{[}=@var{file}@r{]}}
I've generally not touched the option descriptions, just moved them
around. The exception is that I incorporated some of the material from
the -g description into the section introduction, and also added a
pointer to -Og to the discussion about the interaction between -O and -g
(having previously run into PR62225 myself).
I'll commit this in a couple days unless I hear complaints meanwhile.
-Sandra
[-- Attachment #2: gccdoc.log --]
[-- Type: text/x-log, Size: 630 bytes --]
2016-01-16 Sandra Loosemore <sandra@codesourcery.com>
gcc/
* doc/invoke.texi (Invoking GCC): Add new section to menu.
(Option Summary): Update to reflect new section and moved options.
(C++ Dialect Options): Move -fstats to new section.
(Debugging Options): Move all dump, statistics, and other GCC
developer options to new section. Rewrite section introduction
and re-order remaining options to put the more basic ones first.
(Optimization Options): Move -fira-verbose and -flto-report* to
new section.
(Developer Options): New section incorporating moved options.
* doc/cppopts.texi (-dM): Update cross-reference.
[-- Attachment #3: gccdoc.patch --]
[-- Type: text/x-patch, Size: 114747 bytes --]
Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi (revision 232475)
+++ gcc/doc/invoke.texi (working copy)
@@ -138,7 +138,7 @@ only one of these two forms, whichever o
* Diagnostic Message Formatting Options:: Controlling how diagnostics should
be formatted.
* Warning Options:: How picky should the compiler be?
-* Debugging Options:: Symbol tables, measurements, and debugging dumps.
+* Debugging Options:: Producing debuggable code.
* Optimize Options:: How much optimization?
* Instrumentation Options:: Enabling profiling and extra run-time error checking.
* Preprocessor Options:: Controlling header files and macro definitions.
@@ -149,6 +149,8 @@ only one of these two forms, whichever o
Where to find the compiler executable files.
* Code Gen Options:: Specifying conventions for function calls, data layout
and register usage.
+* Developer Options:: Printing GCC configuration info, statistics, and
+ debugging dumps.
* Submodel Options:: Target-specific options, such as compiling for a
specific processor variant.
* Spec Files:: How to pass switches to sub-processes.
@@ -199,7 +201,7 @@ in the following sections.
-fno-optional-diags -fpermissive @gol
-fno-pretty-templates @gol
-frepo -fno-rtti -fsized-deallocation @gol
--fstats -ftemplate-backtrace-limit=@var{n} @gol
+-ftemplate-backtrace-limit=@var{n} @gol
-ftemplate-depth=@var{n} @gol
-fno-threadsafe-statics -fuse-cxa-atexit @gol
-fno-weak -nostdinc++ @gol
@@ -313,71 +315,18 @@ Objective-C and Objective-C++ Dialects}.
-Wdeclaration-after-statement -Wpointer-sign}
@item Debugging Options
-@xref{Debugging Options,,Options for Debugging Your Program or GCC}.
-@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
--fchecking -fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol
--fdisable-ipa-@var{pass_name} @gol
--fdisable-rtl-@var{pass_name} @gol
--fdisable-rtl-@var{pass-name}=@var{range-list} @gol
--fdisable-tree-@var{pass_name} @gol
--fdisable-tree-@var{pass-name}=@var{range-list} @gol
--fdump-noaddr -fdump-unnumbered -fdump-unnumbered-links @gol
--fdump-translation-unit@r{[}-@var{n}@r{]} @gol
--fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
--fdump-ipa-all -fdump-ipa-cgraph -fdump-ipa-inline @gol
--fdump-passes @gol
--fdump-statistics @gol
--fdump-tree-all @gol
--fdump-tree-original@r{[}-@var{n}@r{]} @gol
--fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
--fdump-tree-cfg -fdump-tree-alias @gol
--fdump-tree-ch @gol
--fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
--fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
--fdump-tree-gimple@r{[}-raw@r{]} @gol
--fdump-tree-dom@r{[}-@var{n}@r{]} @gol
--fdump-tree-dse@r{[}-@var{n}@r{]} @gol
--fdump-tree-phiprop@r{[}-@var{n}@r{]} @gol
--fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
--fdump-tree-backprop@r{[}-@var{n}@r{]} @gol
--fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
--fdump-tree-nrv -fdump-tree-vect @gol
--fdump-tree-sink @gol
--fdump-tree-sra@r{[}-@var{n}@r{]} @gol
--fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
--fdump-tree-fre@r{[}-@var{n}@r{]} @gol
--fdump-tree-vtable-verify @gol
--fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
--fdump-tree-split-paths@r{[}-@var{n}@r{]} @gol
--fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
--fdump-final-insns=@var{file} @gol
--fcompare-debug@r{[}=@var{opts}@r{]} -fcompare-debug-second @gol
--feliminate-dwarf2-dups -fno-eliminate-unused-debug-types @gol
--feliminate-unused-debug-symbols -femit-class-debug-always @gol
--fenable-@var{kind}-@var{pass} @gol
--fenable-@var{kind}-@var{pass}=@var{range-list} @gol
--fdebug-types-section -fmem-report-wpa @gol
--fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report @gol
--fopt-info @gol
--fopt-info-@var{options}@r{[}=@var{file}@r{]} @gol
--fprofile-report @gol
--frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
--fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol
--fstack-usage -ftime-report -fvar-tracking @gol
--fvar-tracking-assignments -fvar-tracking-assignments-toggle @gol
--g -g@var{level} -gtoggle -gcoff -gdwarf-@var{version} @gol
+@xref{Debugging Options,,Options for Debugging Your Program}.
+@gccoptlist{-g -g@var{level} -gcoff -gdwarf-@var{version} @gol
-ggdb -grecord-gcc-switches -gno-record-gcc-switches @gol
-gstabs -gstabs+ -gstrict-dwarf -gno-strict-dwarf @gol
-gvms -gxcoff -gxcoff+ -gz@r{[}=@var{type}@r{]} @gol
--fno-merge-debug-strings -fno-dwarf2-cfi-asm @gol
--fdebug-prefix-map=@var{old}=@var{new} @gol
+-fdebug-prefix-map=@var{old}=@var{new} -fdebug-types-section @gol
+-feliminate-dwarf2-dups -fno-eliminate-unused-debug-types @gol
-femit-struct-debug-baseonly -femit-struct-debug-reduced @gol
-femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol
--print-file-name=@var{library} -print-libgcc-file-name @gol
--print-multi-directory -print-multi-lib -print-multi-os-directory @gol
--print-prog-name=@var{program} -print-search-dirs -Q @gol
--print-sysroot -print-sysroot-headers-suffix @gol
--save-temps -save-temps=cwd -save-temps=obj -time@r{[}=@var{file}@r{]}}
+-feliminate-unused-debug-symbols -femit-class-debug-always @gol
+-fno-merge-debug-strings -fno-dwarf2-cfi-asm @gol
+-fvar-tracking -fvar-tracking-assignments}
@item Optimization Options
@xref{Optimize Options,,Options that Control Optimization}.
@@ -407,14 +356,14 @@ Objective-C and Objective-C++ Dialects}.
-fira-algorithm=@var{algorithm} @gol
-fira-region=@var{region} -fira-hoist-pressure @gol
-fira-loop-pressure -fno-ira-share-save-slots @gol
--fno-ira-share-spill-slots -fira-verbose=@var{n} @gol
+-fno-ira-share-spill-slots @gol
-fisolate-erroneous-paths-dereference -fisolate-erroneous-paths-attribute @gol
-fivopts -fkeep-inline-functions -fkeep-static-functions @gol
-fkeep-static-consts -flive-range-shrinkage @gol
-floop-block -floop-interchange -floop-strip-mine @gol
-floop-unroll-and-jam -floop-nest-optimize @gol
-floop-parallelize-all -flra-remat -flto -flto-compression-level @gol
--flto-partition=@var{alg} -flto-report -flto-report-wpa -fmerge-all-constants @gol
+-flto-partition=@var{alg} -fmerge-all-constants @gol
-fmerge-constants -fmodulo-sched -fmodulo-sched-allow-regmoves @gol
-fmove-loop-invariants -fno-branch-count-reg @gol
-fno-defer-pop -fno-function-cse -fno-guess-branch-probability @gol
@@ -548,6 +497,64 @@ Objective-C and Objective-C++ Dialects}.
-fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} @gol
-fstrict-volatile-bitfields -fsync-libcalls}
+@item Developer Options
+@xref{Developer Options,,GCC Developer Options}
+@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
+-fchecking -fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol
+-fdisable-ipa-@var{pass_name} @gol
+-fdisable-rtl-@var{pass_name} @gol
+-fdisable-rtl-@var{pass-name}=@var{range-list} @gol
+-fdisable-tree-@var{pass_name} @gol
+-fdisable-tree-@var{pass-name}=@var{range-list} @gol
+-fdump-noaddr -fdump-unnumbered -fdump-unnumbered-links @gol
+-fdump-translation-unit@r{[}-@var{n}@r{]} @gol
+-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
+-fdump-ipa-all -fdump-ipa-cgraph -fdump-ipa-inline @gol
+-fdump-passes @gol
+-fdump-rtl-@var{pass} -fdump-rtl-@var{pass}=@var{filename} @gol
+-fdump-statistics @gol
+-fdump-tree-all @gol
+-fdump-tree-original@r{[}-@var{n}@r{]} @gol
+-fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
+-fdump-tree-cfg -fdump-tree-alias @gol
+-fdump-tree-ch @gol
+-fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
+-fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
+-fdump-tree-gimple@r{[}-raw@r{]} @gol
+-fdump-tree-dom@r{[}-@var{n}@r{]} @gol
+-fdump-tree-dse@r{[}-@var{n}@r{]} @gol
+-fdump-tree-phiprop@r{[}-@var{n}@r{]} @gol
+-fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
+-fdump-tree-backprop@r{[}-@var{n}@r{]} @gol
+-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
+-fdump-tree-nrv -fdump-tree-vect @gol
+-fdump-tree-sink @gol
+-fdump-tree-sra@r{[}-@var{n}@r{]} @gol
+-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
+-fdump-tree-fre@r{[}-@var{n}@r{]} @gol
+-fdump-tree-vtable-verify @gol
+-fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
+-fdump-tree-split-paths@r{[}-@var{n}@r{]} @gol
+-fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
+-fdump-final-insns=@var{file} @gol
+-fcompare-debug@r{[}=@var{opts}@r{]} -fcompare-debug-second @gol
+-fenable-@var{kind}-@var{pass} @gol
+-fenable-@var{kind}-@var{pass}=@var{range-list} @gol
+-fira-verbose=@var{n} @gol
+-flto-report -flto-report-wpa -fmem-report-wpa @gol
+-fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report @gol
+-fopt-info -fopt-info-@var{options}@r{[}=@var{file}@r{]} @gol
+-fprofile-report @gol
+-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
+-fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol
+-fstats -fstack-usage -ftime-report @gol
+-fvar-tracking-assignments-toggle -gtoggle @gol
+-print-file-name=@var{library} -print-libgcc-file-name @gol
+-print-multi-directory -print-multi-lib -print-multi-os-directory @gol
+-print-prog-name=@var{program} -print-search-dirs -Q @gol
+-print-sysroot -print-sysroot-headers-suffix @gol
+-save-temps -save-temps=cwd -save-temps=obj -time@r{[}=@var{file}@r{]}}
+
@item Machine-Dependent Options
@xref{Submodel Options,,Machine-Dependent Options}.
@c This list is ordered alphanumerically by subsection name.
@@ -2433,11 +2440,6 @@ to make deallocation faster. Enabled by
@option{-std=c++14} and above. The flag @option{-Wsized-deallocation}
warns about places that might want to add a definition.
-@item -fstats
-@opindex fstats
-Emit statistics about front-end processing at the end of the compilation.
-This information is generally only useful to the G++ development team.
-
@item -fstrict-enums
@opindex fstrict-enums
Allow the compiler to optimize using the assumption that a value of
@@ -5694,12 +5696,28 @@ attribute.
@end table
@node Debugging Options
-@section Options for Debugging Your Program or GCC
+@section Options for Debugging Your Program
@cindex options, debugging
@cindex debugging information options
-GCC has various special options that are used for debugging
-either your program or GCC:
+To tell GCC to emit extra information for use by a debugger, in almost
+all cases you need only to add @option{-g} to your other options.
+
+GCC allows you to use @option{-g} with
+@option{-O}. The shortcuts taken by optimized code may occasionally
+be surprising: some variables you declared may not exist
+at all; flow of control may briefly move where you did not expect it;
+some statements may not be executed because they compute constant
+results or their values are already at hand; some statements may
+execute in different places because they have been moved out of loops.
+Nevertheless it is possible to debug optimized output. This makes
+it reasonable to use the optimizer for programs that might have bugs.
+
+If you are not using some other optimization option, consider
+using @option{-Og} (@pxref{Optimize Options}) with @option{-g}.
+With no @option{-O} option at all, some compiler passes that collect
+information useful for debugging do not run at all, so that
+@option{-Og} may result in a better debugging experience.
@table @gcctabopt
@item -g
@@ -5716,28 +5734,6 @@ refuse to read the program. If you want
to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
-GCC allows you to use @option{-g} with
-@option{-O}. The shortcuts taken by optimized code may occasionally
-produce surprising results: some variables you declared may not exist
-at all; flow of control may briefly move where you did not expect it;
-some statements may not be executed because they compute constant
-results or their values are already at hand; some statements may
-execute in different places because they have been moved out of loops.
-
-Nevertheless it proves possible to debug optimized output. This makes
-it reasonable to use the optimizer for programs that might have bugs.
-
-The following options are useful when GCC is generated with the
-capability for more than one debugging format.
-
-@item -gsplit-dwarf
-@opindex gsplit-dwarf
-Separate as much dwarf debugging information as possible into a
-separate output file with the extension .dwo. This option allows
-the build system to avoid linking files with debug information. To
-be useful, this option requires a debugger capable of reading .dwo
-files.
-
@item -ggdb
@opindex ggdb
Produce debugging information for use by GDB@. This means to use the
@@ -5745,15 +5741,17 @@ most expressive format available (DWARF
if neither of those are supported), including GDB extensions if at all
possible.
-@item -gpubnames
-@opindex gpubnames
-Generate dwarf .debug_pubnames and .debug_pubtypes sections.
+@item -gdwarf-@var{version}
+@opindex gdwarf-@var{version}
+Produce debugging information in DWARF format (if that is supported).
+The value of @var{version} may be either 2, 3, 4 or 5; the default version
+for most targets is 4. DWARF Version 5 is only experimental.
-@item -ggnu-pubnames
-@opindex ggnu-pubnames
-Generate .debug_pubnames and .debug_pubtypes sections in a format
-suitable for conversion into a GDB@ index. This option is only useful
-with a linker that can produce GDB@ index version 7.
+Note that with DWARF Version 2, some ports require and always
+use some non-conflicting DWARF 3 extensions in the unwind tables.
+
+Version 4 may require GDB 7.0 and @option{-fvar-tracking-assignments}
+for maximum benefit.
@item -gstabs
@opindex gstabs
@@ -5763,31 +5761,6 @@ systems. On MIPS, Alpha and System V Re
produces stabs debugging output that is not understood by DBX or SDB@.
On System V Release 4 systems this option requires the GNU assembler.
-@item -feliminate-unused-debug-symbols
-@opindex feliminate-unused-debug-symbols
-Produce debugging information in stabs format (if that is supported),
-for only symbols that are actually used.
-
-@item -femit-class-debug-always
-@opindex femit-class-debug-always
-Instead of emitting debugging information for a C++ class in only one
-object file, emit it in all object files using the class. This option
-should be used only with debuggers that are unable to handle the way GCC
-normally emits debugging information for classes because using this
-option increases the size of debugging information by as much as a
-factor of two.
-
-@item -fdebug-types-section
-@opindex fdebug-types-section
-@opindex fno-debug-types-section
-When using DWARF Version 4 or higher, type DIEs can be put into
-their own @code{.debug_types} section instead of making them part of the
-@code{.debug_info} section. It is more efficient to put them in a separate
-comdat sections since the linker can then remove duplicates.
-But not all DWARF consumers support @code{.debug_types} sections yet
-and on some objects @code{.debug_types} produces larger instead of smaller
-debugging information.
-
@item -gstabs+
@opindex gstabs+
Produce debugging information in stabs format (if that is supported),
@@ -5814,55 +5787,6 @@ use of these extensions is likely to mak
refuse to read the program, and may cause assemblers other than the GNU
assembler (GAS) to fail with an error.
-@item -gdwarf-@var{version}
-@opindex gdwarf-@var{version}
-Produce debugging information in DWARF format (if that is supported).
-The value of @var{version} may be either 2, 3, 4 or 5; the default version
-for most targets is 4. DWARF Version 5 is only experimental.
-
-Note that with DWARF Version 2, some ports require and always
-use some non-conflicting DWARF 3 extensions in the unwind tables.
-
-Version 4 may require GDB 7.0 and @option{-fvar-tracking-assignments}
-for maximum benefit.
-
-@item -grecord-gcc-switches
-@opindex grecord-gcc-switches
-This switch causes the command-line options used to invoke the
-compiler that may affect code generation to be appended to the
-DW_AT_producer attribute in DWARF debugging information. The options
-are concatenated with spaces separating them from each other and from
-the compiler version. See also @option{-frecord-gcc-switches} for another
-way of storing compiler options into the object file. This is the default.
-
-@item -gno-record-gcc-switches
-@opindex gno-record-gcc-switches
-Disallow appending command-line options to the DW_AT_producer attribute
-in DWARF debugging information.
-
-@item -gstrict-dwarf
-@opindex gstrict-dwarf
-Disallow using extensions of later DWARF standard version than selected
-with @option{-gdwarf-@var{version}}. On most targets using non-conflicting
-DWARF extensions from later standard versions is allowed.
-
-@item -gno-strict-dwarf
-@opindex gno-strict-dwarf
-Allow using extensions of later DWARF standard version than selected with
-@option{-gdwarf-@var{version}}.
-
-@item -gz@r{[}=@var{type}@r{]}
-@opindex gz
-Produce compressed debug sections in DWARF format, if that is supported.
-If @var{type} is not given, the default type depends on the capabilities
-of the assembler and linker used. @var{type} may be one of
-@samp{none} (don't compress debug sections), @samp{zlib} (use zlib
-compression in ELF gABI format), or @samp{zlib-gnu} (use zlib
-compression in traditional GNU format). If the linker doesn't support
-writing compressed debug sections, the option is rejected. Otherwise,
-if the assembler does not support them, @option{-gz} is silently ignored
-when producing object files.
-
@item -gvms
@opindex gvms
Produce debugging information in Alpha/VMS debug format (if that is
@@ -5897,69 +5821,122 @@ debug format is long obsolete, but the o
Instead use an additional @option{-g@var{level}} option to change the
debug level for DWARF.
-@item -gtoggle
-@opindex gtoggle
-Turn off generation of debug info, if leaving out this option
-generates it, or turn it on at level 2 otherwise. The position of this
-argument in the command line does not matter; it takes effect after all
-other options are processed, and it does so only once, no matter how
-many times it is given. This is mainly intended to be used with
-@option{-fcompare-debug}.
+@item -feliminate-unused-debug-symbols
+@opindex feliminate-unused-debug-symbols
+Produce debugging information in stabs format (if that is supported),
+for only symbols that are actually used.
-@item -fchecking
-@opindex fchecking
-@opindex fno-checking
-Enable internal consistency checking. The default depends on
-the compiler configuration.
+@item -femit-class-debug-always
+@opindex femit-class-debug-always
+Instead of emitting debugging information for a C++ class in only one
+object file, emit it in all object files using the class. This option
+should be used only with debuggers that are unable to handle the way GCC
+normally emits debugging information for classes because using this
+option increases the size of debugging information by as much as a
+factor of two.
-@item -fdump-final-insns@r{[}=@var{file}@r{]}
-@opindex fdump-final-insns
-Dump the final internal representation (RTL) to @var{file}. If the
-optional argument is omitted (or if @var{file} is @code{.}), the name
-of the dump file is determined by appending @code{.gkd} to the
-compilation output file name.
+@item -fno-merge-debug-strings
+@opindex fmerge-debug-strings
+@opindex fno-merge-debug-strings
+Direct the linker to not merge together strings in the debugging
+information that are identical in different object files. Merging is
+not supported by all assemblers or linkers. Merging decreases the size
+of the debug information in the output file at the cost of increasing
+link processing time. Merging is enabled by default.
-@item -fcompare-debug@r{[}=@var{opts}@r{]}
-@opindex fcompare-debug
-@opindex fno-compare-debug
-If no error occurs during compilation, run the compiler a second time,
-adding @var{opts} and @option{-fcompare-debug-second} to the arguments
-passed to the second compilation. Dump the final internal
-representation in both compilations, and print an error if they differ.
+@item -fdebug-prefix-map=@var{old}=@var{new}
+@opindex fdebug-prefix-map
+When compiling files in directory @file{@var{old}}, record debugging
+information describing them as in @file{@var{new}} instead.
-If the equal sign is omitted, the default @option{-gtoggle} is used.
+@item -fvar-tracking
+@opindex fvar-tracking
+Run variable tracking pass. It computes where variables are stored at each
+position in code. Better debugging information is then generated
+(if the debugging information format supports this information).
-The environment variable @env{GCC_COMPARE_DEBUG}, if defined, non-empty
-and nonzero, implicitly enables @option{-fcompare-debug}. If
-@env{GCC_COMPARE_DEBUG} is defined to a string starting with a dash,
-then it is used for @var{opts}, otherwise the default @option{-gtoggle}
-is used.
+It is enabled by default when compiling with optimization (@option{-Os},
+@option{-O}, @option{-O2}, @dots{}), debugging information (@option{-g}) and
+the debug info format supports it.
-@option{-fcompare-debug=}, with the equal sign but without @var{opts},
-is equivalent to @option{-fno-compare-debug}, which disables the dumping
-of the final representation and the second compilation, preventing even
-@env{GCC_COMPARE_DEBUG} from taking effect.
+@item -fvar-tracking-assignments
+@opindex fvar-tracking-assignments
+@opindex fno-var-tracking-assignments
+Annotate assignments to user variables early in the compilation and
+attempt to carry the annotations over throughout the compilation all the
+way to the end, in an attempt to improve debug information while
+optimizing. Use of @option{-gdwarf-4} is recommended along with it.
-To verify full coverage during @option{-fcompare-debug} testing, set
-@env{GCC_COMPARE_DEBUG} to say @option{-fcompare-debug-not-overridden},
-which GCC rejects as an invalid option in any actual compilation
-(rather than preprocessing, assembly or linking). To get just a
-warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug
-not overridden} will do.
+It can be enabled even if var-tracking is disabled, in which case
+annotations are created and maintained, but discarded at the end.
+By default, this flag is enabled together with @option{-fvar-tracking},
+except when selective scheduling is enabled.
-@item -fcompare-debug-second
-@opindex fcompare-debug-second
-This option is implicitly passed to the compiler for the second
-compilation requested by @option{-fcompare-debug}, along with options to
-silence warnings, and omitting other options that would cause
-side-effect compiler outputs to files or to the standard output. Dump
-files and preserved temporary files are renamed so as to contain the
-@code{.gk} additional extension during the second compilation, to avoid
-overwriting those generated by the first.
+@item -gsplit-dwarf
+@opindex gsplit-dwarf
+Separate as much dwarf debugging information as possible into a
+separate output file with the extension .dwo. This option allows
+the build system to avoid linking files with debug information. To
+be useful, this option requires a debugger capable of reading .dwo
+files.
-When this option is passed to the compiler driver, it causes the
-@emph{first} compilation to be skipped, which makes it useful for little
-other than debugging the compiler proper.
+@item -gpubnames
+@opindex gpubnames
+Generate dwarf .debug_pubnames and .debug_pubtypes sections.
+
+@item -ggnu-pubnames
+@opindex ggnu-pubnames
+Generate .debug_pubnames and .debug_pubtypes sections in a format
+suitable for conversion into a GDB@ index. This option is only useful
+with a linker that can produce GDB@ index version 7.
+
+@item -fdebug-types-section
+@opindex fdebug-types-section
+@opindex fno-debug-types-section
+When using DWARF Version 4 or higher, type DIEs can be put into
+their own @code{.debug_types} section instead of making them part of the
+@code{.debug_info} section. It is more efficient to put them in a separate
+comdat sections since the linker can then remove duplicates.
+But not all DWARF consumers support @code{.debug_types} sections yet
+and on some objects @code{.debug_types} produces larger instead of smaller
+debugging information.
+
+@item -grecord-gcc-switches
+@opindex grecord-gcc-switches
+This switch causes the command-line options used to invoke the
+compiler that may affect code generation to be appended to the
+DW_AT_producer attribute in DWARF debugging information. The options
+are concatenated with spaces separating them from each other and from
+the compiler version. See also @option{-frecord-gcc-switches} for another
+way of storing compiler options into the object file. This is the default.
+
+@item -gno-record-gcc-switches
+@opindex gno-record-gcc-switches
+Disallow appending command-line options to the DW_AT_producer attribute
+in DWARF debugging information.
+
+@item -gstrict-dwarf
+@opindex gstrict-dwarf
+Disallow using extensions of later DWARF standard version than selected
+with @option{-gdwarf-@var{version}}. On most targets using non-conflicting
+DWARF extensions from later standard versions is allowed.
+
+@item -gno-strict-dwarf
+@opindex gno-strict-dwarf
+Allow using extensions of later DWARF standard version than selected with
+@option{-gdwarf-@var{version}}.
+
+@item -gz@r{[}=@var{type}@r{]}
+@opindex gz
+Produce compressed debug sections in DWARF format, if that is supported.
+If @var{type} is not given, the default type depends on the capabilities
+of the assembler and linker used. @var{type} may be one of
+@samp{none} (don't compress debug sections), @samp{zlib} (use zlib
+compression in ELF gABI format), or @samp{zlib-gnu} (use zlib
+compression in traditional GNU format). If the linker doesn't support
+writing compressed debug sections, the option is rejected. Otherwise,
+if the assembler does not support them, @option{-gz} is silently ignored
+when producing object files.
@item -feliminate-dwarf2-dups
@opindex feliminate-dwarf2-dups
@@ -6042,1164 +6019,12 @@ The default is @option{-femit-struct-deb
This option works only with DWARF 2.
-@item -fno-merge-debug-strings
-@opindex fmerge-debug-strings
-@opindex fno-merge-debug-strings
-Direct the linker to not merge together strings in the debugging
-information that are identical in different object files. Merging is
-not supported by all assemblers or linkers. Merging decreases the size
-of the debug information in the output file at the cost of increasing
-link processing time. Merging is enabled by default.
-
-@item -fdebug-prefix-map=@var{old}=@var{new}
-@opindex fdebug-prefix-map
-When compiling files in directory @file{@var{old}}, record debugging
-information describing them as in @file{@var{new}} instead.
-
@item -fno-dwarf2-cfi-asm
@opindex fdwarf2-cfi-asm
@opindex fno-dwarf2-cfi-asm
Emit DWARF 2 unwind info as compiler generated @code{.eh_frame} section
instead of using GAS @code{.cfi_*} directives.
-@item -Q
-@opindex Q
-Makes the compiler print out each function name as it is compiled, and
-print some statistics about each pass when it finishes.
-
-@item -ftime-report
-@opindex ftime-report
-Makes the compiler print some statistics about the time consumed by each
-pass when it finishes.
-
-@item -fmem-report
-@opindex fmem-report
-Makes the compiler print some statistics about permanent memory
-allocation when it finishes.
-
-@item -fmem-report-wpa
-@opindex fmem-report-wpa
-Makes the compiler print some statistics about permanent memory
-allocation for the WPA phase only.
-
-@item -fpre-ipa-mem-report
-@opindex fpre-ipa-mem-report
-@item -fpost-ipa-mem-report
-@opindex fpost-ipa-mem-report
-Makes the compiler print some statistics about permanent memory
-allocation before or after interprocedural optimization.
-
-@item -fprofile-report
-@opindex fprofile-report
-Makes the compiler print some statistics about consistency of the
-(estimated) profile and effect of individual passes.
-
-@item -fstack-usage
-@opindex fstack-usage
-Makes the compiler output stack usage information for the program, on a
-per-function basis. The filename for the dump is made by appending
-@file{.su} to the @var{auxname}. @var{auxname} is generated from the name of
-the output file, if explicitly specified and it is not an executable,
-otherwise it is the basename of the source file. An entry is made up
-of three fields:
-
-@itemize
-@item
-The name of the function.
-@item
-A number of bytes.
-@item
-One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}.
-@end itemize
-
-The qualifier @code{static} means that the function manipulates the stack
-statically: a fixed number of bytes are allocated for the frame on function
-entry and released on function exit; no stack adjustments are otherwise made
-in the function. The second field is this fixed number of bytes.
-
-The qualifier @code{dynamic} means that the function manipulates the stack
-dynamically: in addition to the static allocation described above, stack
-adjustments are made in the body of the function, for example to push/pop
-arguments around function calls. If the qualifier @code{bounded} is also
-present, the amount of these adjustments is bounded at compile time and
-the second field is an upper bound of the total amount of stack used by
-the function. If it is not present, the amount of these adjustments is
-not bounded at compile time and the second field only represents the
-bounded part.
-
-@item -fdbg-cnt-list
-@opindex fdbg-cnt-list
-Print the name and the counter upper bound for all debug counters.
-
-
-@item -fdbg-cnt=@var{counter-value-list}
-@opindex fdbg-cnt
-Set the internal debug counter upper bound. @var{counter-value-list}
-is a comma-separated list of @var{name}:@var{value} pairs
-which sets the upper bound of each debug counter @var{name} to @var{value}.
-All debug counters have the initial upper bound of @code{UINT_MAX};
-thus @code{dbg_cnt} returns true always unless the upper bound
-is set by this option.
-For example, with @option{-fdbg-cnt=dce:10,tail_call:0},
-@code{dbg_cnt(dce)} returns true only for first 10 invocations.
-
-@item -fenable-@var{kind}-@var{pass}
-@itemx -fdisable-@var{kind}-@var{pass}=@var{range-list}
-@opindex fdisable-
-@opindex fenable-
-
-This is a set of options that are used to explicitly disable/enable
-optimization passes. These options are intended for use for debugging GCC.
-Compiler users should use regular options for enabling/disabling
-passes instead.
-
-@table @gcctabopt
-
-@item -fdisable-ipa-@var{pass}
-Disable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is
-statically invoked in the compiler multiple times, the pass name should be
-appended with a sequential number starting from 1.
-
-@item -fdisable-rtl-@var{pass}
-@itemx -fdisable-rtl-@var{pass}=@var{range-list}
-Disable RTL pass @var{pass}. @var{pass} is the pass name. If the same pass is
-statically invoked in the compiler multiple times, the pass name should be
-appended with a sequential number starting from 1. @var{range-list} is a
-comma-separated list of function ranges or assembler names. Each range is a number
-pair separated by a colon. The range is inclusive in both ends. If the range
-is trivial, the number pair can be simplified as a single number. If the
-function's call graph node's @var{uid} falls within one of the specified ranges,
-the @var{pass} is disabled for that function. The @var{uid} is shown in the
-function header of a dump file, and the pass names can be dumped by using
-option @option{-fdump-passes}.
-
-@item -fdisable-tree-@var{pass}
-@itemx -fdisable-tree-@var{pass}=@var{range-list}
-Disable tree pass @var{pass}. See @option{-fdisable-rtl} for the description of
-option arguments.
-
-@item -fenable-ipa-@var{pass}
-Enable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is
-statically invoked in the compiler multiple times, the pass name should be
-appended with a sequential number starting from 1.
-
-@item -fenable-rtl-@var{pass}
-@itemx -fenable-rtl-@var{pass}=@var{range-list}
-Enable RTL pass @var{pass}. See @option{-fdisable-rtl} for option argument
-description and examples.
-
-@item -fenable-tree-@var{pass}
-@itemx -fenable-tree-@var{pass}=@var{range-list}
-Enable tree pass @var{pass}. See @option{-fdisable-rtl} for the description
-of option arguments.
-
-@end table
-
-Here are some examples showing uses of these options.
-
-@smallexample
-
-# disable ccp1 for all functions
- -fdisable-tree-ccp1
-# disable complete unroll for function whose cgraph node uid is 1
- -fenable-tree-cunroll=1
-# disable gcse2 for functions at the following ranges [1,1],
-# [300,400], and [400,1000]
-# disable gcse2 for functions foo and foo2
- -fdisable-rtl-gcse2=foo,foo2
-# disable early inlining
- -fdisable-tree-einline
-# disable ipa inlining
- -fdisable-ipa-inline
-# enable tree full unroll
- -fenable-tree-unroll
-
-@end smallexample
-
-@item -d@var{letters}
-@itemx -fdump-rtl-@var{pass}
-@itemx -fdump-rtl-@var{pass}=@var{filename}
-@opindex d
-@opindex fdump-rtl-@var{pass}
-Says to make debugging dumps during compilation at times specified by
-@var{letters}. This is used for debugging the RTL-based passes of the
-compiler. The file names for most of the dumps are made by appending
-a pass number and a word to the @var{dumpname}, and the files are
-created in the directory of the output file. In case of
-@option{=@var{filename}} option, the dump is output on the given file
-instead of the pass numbered dump files. Note that the pass number is
-assigned as passes are registered into the pass manager. Most passes
-are registered in the order that they will execute and for these passes
-the number corresponds to the pass execution order. However, passes
-registered by plugins, passes specific to compilation targets, or
-passes that are otherwise registered after all the other passes are
-numbered higher than a pass named "final", even if they are executed
-earlier. @var{dumpname} is generated from the name of the output
-file if explicitly specified and not an executable, otherwise it is
-the basename of the source file. These switches may have different
-effects when @option{-E} is used for preprocessing.
-
-Debug dumps can be enabled with a @option{-fdump-rtl} switch or some
-@option{-d} option @var{letters}. Here are the possible
-letters for use in @var{pass} and @var{letters}, and their meanings:
-
-@table @gcctabopt
-
-@item -fdump-rtl-alignments
-@opindex fdump-rtl-alignments
-Dump after branch alignments have been computed.
-
-@item -fdump-rtl-asmcons
-@opindex fdump-rtl-asmcons
-Dump after fixing rtl statements that have unsatisfied in/out constraints.
-
-@item -fdump-rtl-auto_inc_dec
-@opindex fdump-rtl-auto_inc_dec
-Dump after auto-inc-dec discovery. This pass is only run on
-architectures that have auto inc or auto dec instructions.
-
-@item -fdump-rtl-barriers
-@opindex fdump-rtl-barriers
-Dump after cleaning up the barrier instructions.
-
-@item -fdump-rtl-bbpart
-@opindex fdump-rtl-bbpart
-Dump after partitioning hot and cold basic blocks.
-
-@item -fdump-rtl-bbro
-@opindex fdump-rtl-bbro
-Dump after block reordering.
-
-@item -fdump-rtl-btl1
-@itemx -fdump-rtl-btl2
-@opindex fdump-rtl-btl2
-@opindex fdump-rtl-btl2
-@option{-fdump-rtl-btl1} and @option{-fdump-rtl-btl2} enable dumping
-after the two branch
-target load optimization passes.
-
-@item -fdump-rtl-bypass
-@opindex fdump-rtl-bypass
-Dump after jump bypassing and control flow optimizations.
-
-@item -fdump-rtl-combine
-@opindex fdump-rtl-combine
-Dump after the RTL instruction combination pass.
-
-@item -fdump-rtl-compgotos
-@opindex fdump-rtl-compgotos
-Dump after duplicating the computed gotos.
-
-@item -fdump-rtl-ce1
-@itemx -fdump-rtl-ce2
-@itemx -fdump-rtl-ce3
-@opindex fdump-rtl-ce1
-@opindex fdump-rtl-ce2
-@opindex fdump-rtl-ce3
-@option{-fdump-rtl-ce1}, @option{-fdump-rtl-ce2}, and
-@option{-fdump-rtl-ce3} enable dumping after the three
-if conversion passes.
-
-@item -fdump-rtl-cprop_hardreg
-@opindex fdump-rtl-cprop_hardreg
-Dump after hard register copy propagation.
-
-@item -fdump-rtl-csa
-@opindex fdump-rtl-csa
-Dump after combining stack adjustments.
-
-@item -fdump-rtl-cse1
-@itemx -fdump-rtl-cse2
-@opindex fdump-rtl-cse1
-@opindex fdump-rtl-cse2
-@option{-fdump-rtl-cse1} and @option{-fdump-rtl-cse2} enable dumping after
-the two common subexpression elimination passes.
-
-@item -fdump-rtl-dce
-@opindex fdump-rtl-dce
-Dump after the standalone dead code elimination passes.
-
-@item -fdump-rtl-dbr
-@opindex fdump-rtl-dbr
-Dump after delayed branch scheduling.
-
-@item -fdump-rtl-dce1
-@itemx -fdump-rtl-dce2
-@opindex fdump-rtl-dce1
-@opindex fdump-rtl-dce2
-@option{-fdump-rtl-dce1} and @option{-fdump-rtl-dce2} enable dumping after
-the two dead store elimination passes.
-
-@item -fdump-rtl-eh
-@opindex fdump-rtl-eh
-Dump after finalization of EH handling code.
-
-@item -fdump-rtl-eh_ranges
-@opindex fdump-rtl-eh_ranges
-Dump after conversion of EH handling range regions.
-
-@item -fdump-rtl-expand
-@opindex fdump-rtl-expand
-Dump after RTL generation.
-
-@item -fdump-rtl-fwprop1
-@itemx -fdump-rtl-fwprop2
-@opindex fdump-rtl-fwprop1
-@opindex fdump-rtl-fwprop2
-@option{-fdump-rtl-fwprop1} and @option{-fdump-rtl-fwprop2} enable
-dumping after the two forward propagation passes.
-
-@item -fdump-rtl-gcse1
-@itemx -fdump-rtl-gcse2
-@opindex fdump-rtl-gcse1
-@opindex fdump-rtl-gcse2
-@option{-fdump-rtl-gcse1} and @option{-fdump-rtl-gcse2} enable dumping
-after global common subexpression elimination.
-
-@item -fdump-rtl-init-regs
-@opindex fdump-rtl-init-regs
-Dump after the initialization of the registers.
-
-@item -fdump-rtl-initvals
-@opindex fdump-rtl-initvals
-Dump after the computation of the initial value sets.
-
-@item -fdump-rtl-into_cfglayout
-@opindex fdump-rtl-into_cfglayout
-Dump after converting to cfglayout mode.
-
-@item -fdump-rtl-ira
-@opindex fdump-rtl-ira
-Dump after iterated register allocation.
-
-@item -fdump-rtl-jump
-@opindex fdump-rtl-jump
-Dump after the second jump optimization.
-
-@item -fdump-rtl-loop2
-@opindex fdump-rtl-loop2
-@option{-fdump-rtl-loop2} enables dumping after the rtl
-loop optimization passes.
-
-@item -fdump-rtl-mach
-@opindex fdump-rtl-mach
-Dump after performing the machine dependent reorganization pass, if that
-pass exists.
-
-@item -fdump-rtl-mode_sw
-@opindex fdump-rtl-mode_sw
-Dump after removing redundant mode switches.
-
-@item -fdump-rtl-rnreg
-@opindex fdump-rtl-rnreg
-Dump after register renumbering.
-
-@item -fdump-rtl-outof_cfglayout
-@opindex fdump-rtl-outof_cfglayout
-Dump after converting from cfglayout mode.
-
-@item -fdump-rtl-peephole2
-@opindex fdump-rtl-peephole2
-Dump after the peephole pass.
-
-@item -fdump-rtl-postreload
-@opindex fdump-rtl-postreload
-Dump after post-reload optimizations.
-
-@item -fdump-rtl-pro_and_epilogue
-@opindex fdump-rtl-pro_and_epilogue
-Dump after generating the function prologues and epilogues.
-
-@item -fdump-rtl-sched1
-@itemx -fdump-rtl-sched2
-@opindex fdump-rtl-sched1
-@opindex fdump-rtl-sched2
-@option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2} enable dumping
-after the basic block scheduling passes.
-
-@item -fdump-rtl-ree
-@opindex fdump-rtl-ree
-Dump after sign/zero extension elimination.
-
-@item -fdump-rtl-seqabstr
-@opindex fdump-rtl-seqabstr
-Dump after common sequence discovery.
-
-@item -fdump-rtl-shorten
-@opindex fdump-rtl-shorten
-Dump after shortening branches.
-
-@item -fdump-rtl-sibling
-@opindex fdump-rtl-sibling
-Dump after sibling call optimizations.
-
-@item -fdump-rtl-split1
-@itemx -fdump-rtl-split2
-@itemx -fdump-rtl-split3
-@itemx -fdump-rtl-split4
-@itemx -fdump-rtl-split5
-@opindex fdump-rtl-split1
-@opindex fdump-rtl-split2
-@opindex fdump-rtl-split3
-@opindex fdump-rtl-split4
-@opindex fdump-rtl-split5
-These options enable dumping after five rounds of
-instruction splitting.
-
-@item -fdump-rtl-sms
-@opindex fdump-rtl-sms
-Dump after modulo scheduling. This pass is only run on some
-architectures.
-
-@item -fdump-rtl-stack
-@opindex fdump-rtl-stack
-Dump after conversion from GCC's ``flat register file'' registers to the
-x87's stack-like registers. This pass is only run on x86 variants.
-
-@item -fdump-rtl-subreg1
-@itemx -fdump-rtl-subreg2
-@opindex fdump-rtl-subreg1
-@opindex fdump-rtl-subreg2
-@option{-fdump-rtl-subreg1} and @option{-fdump-rtl-subreg2} enable dumping after
-the two subreg expansion passes.
-
-@item -fdump-rtl-unshare
-@opindex fdump-rtl-unshare
-Dump after all rtl has been unshared.
-
-@item -fdump-rtl-vartrack
-@opindex fdump-rtl-vartrack
-Dump after variable tracking.
-
-@item -fdump-rtl-vregs
-@opindex fdump-rtl-vregs
-Dump after converting virtual registers to hard registers.
-
-@item -fdump-rtl-web
-@opindex fdump-rtl-web
-Dump after live range splitting.
-
-@item -fdump-rtl-regclass
-@itemx -fdump-rtl-subregs_of_mode_init
-@itemx -fdump-rtl-subregs_of_mode_finish
-@itemx -fdump-rtl-dfinit
-@itemx -fdump-rtl-dfinish
-@opindex fdump-rtl-regclass
-@opindex fdump-rtl-subregs_of_mode_init
-@opindex fdump-rtl-subregs_of_mode_finish
-@opindex fdump-rtl-dfinit
-@opindex fdump-rtl-dfinish
-These dumps are defined but always produce empty files.
-
-@item -da
-@itemx -fdump-rtl-all
-@opindex da
-@opindex fdump-rtl-all
-Produce all the dumps listed above.
-
-@item -dA
-@opindex dA
-Annotate the assembler output with miscellaneous debugging information.
-
-@item -dD
-@opindex dD
-Dump all macro definitions, at the end of preprocessing, in addition to
-normal output.
-
-@item -dH
-@opindex dH
-Produce a core dump whenever an error occurs.
-
-@item -dp
-@opindex dp
-Annotate the assembler output with a comment indicating which
-pattern and alternative is used. The length of each instruction is
-also printed.
-
-@item -dP
-@opindex dP
-Dump the RTL in the assembler output as a comment before each instruction.
-Also turns on @option{-dp} annotation.
-
-@item -dx
-@opindex dx
-Just generate RTL for a function instead of compiling it. Usually used
-with @option{-fdump-rtl-expand}.
-@end table
-
-@item -fdump-noaddr
-@opindex fdump-noaddr
-When doing debugging dumps, suppress address output. This makes it more
-feasible to use diff on debugging dumps for compiler invocations with
-different compiler binaries and/or different
-text / bss / data / heap / stack / dso start locations.
-
-@item -freport-bug
-@opindex freport-bug
-Collect and dump debug information into temporary file if ICE in C/C++
-compiler occured.
-
-@item -fdump-unnumbered
-@opindex fdump-unnumbered
-When doing debugging dumps, suppress instruction numbers and address output.
-This makes it more feasible to use diff on debugging dumps for compiler
-invocations with different options, in particular with and without
-@option{-g}.
-
-@item -fdump-unnumbered-links
-@opindex fdump-unnumbered-links
-When doing debugging dumps (see @option{-d} option above), suppress
-instruction numbers for the links to the previous and next instructions
-in a sequence.
-
-@item -fdump-translation-unit @r{(C++ only)}
-@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
-@opindex fdump-translation-unit
-Dump a representation of the tree structure for the entire translation
-unit to a file. The file name is made by appending @file{.tu} to the
-source file name, and the file is created in the same directory as the
-output file. If the @samp{-@var{options}} form is used, @var{options}
-controls the details of the dump as described for the
-@option{-fdump-tree} options.
-
-@item -fdump-class-hierarchy @r{(C++ only)}
-@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
-@opindex fdump-class-hierarchy
-Dump a representation of each class's hierarchy and virtual function
-table layout to a file. The file name is made by appending
-@file{.class} to the source file name, and the file is created in the
-same directory as the output file. If the @samp{-@var{options}} form
-is used, @var{options} controls the details of the dump as described
-for the @option{-fdump-tree} options.
-
-@item -fdump-ipa-@var{switch}
-@opindex fdump-ipa
-Control the dumping at various stages of inter-procedural analysis
-language tree to a file. The file name is generated by appending a
-switch specific suffix to the source file name, and the file is created
-in the same directory as the output file. The following dumps are
-possible:
-
-@table @samp
-@item all
-Enables all inter-procedural analysis dumps.
-
-@item cgraph
-Dumps information about call-graph optimization, unused function removal,
-and inlining decisions.
-
-@item inline
-Dump after function inlining.
-
-@end table
-
-@item -fdump-passes
-@opindex fdump-passes
-Dump the list of optimization passes that are turned on and off by
-the current command-line options.
-
-@item -fdump-statistics-@var{option}
-@opindex fdump-statistics
-Enable and control dumping of pass statistics in a separate file. The
-file name is generated by appending a suffix ending in
-@samp{.statistics} to the source file name, and the file is created in
-the same directory as the output file. If the @samp{-@var{option}}
-form is used, @samp{-stats} causes counters to be summed over the
-whole compilation unit while @samp{-details} dumps every event as
-the passes generate them. The default with no option is to sum
-counters for each function compiled.
-
-@item -fdump-tree-@var{switch}
-@itemx -fdump-tree-@var{switch}-@var{options}
-@itemx -fdump-tree-@var{switch}-@var{options}=@var{filename}
-@opindex fdump-tree
-Control the dumping at various stages of processing the intermediate
-language tree to a file. The file name is generated by appending a
-switch-specific suffix to the source file name, and the file is
-created in the same directory as the output file. In case of
-@option{=@var{filename}} option, the dump is output on the given file
-instead of the auto named dump files. If the @samp{-@var{options}}
-form is used, @var{options} is a list of @samp{-} separated options
-which control the details of the dump. Not all options are applicable
-to all dumps; those that are not meaningful are ignored. The
-following options are available
-
-@table @samp
-@item address
-Print the address of each node. Usually this is not meaningful as it
-changes according to the environment and source file. Its primary use
-is for tying up a dump file with a debug environment.
-@item asmname
-If @code{DECL_ASSEMBLER_NAME} has been set for a given decl, use that
-in the dump instead of @code{DECL_NAME}. Its primary use is ease of
-use working backward from mangled names in the assembly file.
-@item slim
-When dumping front-end intermediate representations, inhibit dumping
-of members of a scope or body of a function merely because that scope
-has been reached. Only dump such items when they are directly reachable
-by some other path.
-
-When dumping pretty-printed trees, this option inhibits dumping the
-bodies of control structures.
-
-When dumping RTL, print the RTL in slim (condensed) form instead of
-the default LISP-like representation.
-@item raw
-Print a raw representation of the tree. By default, trees are
-pretty-printed into a C-like representation.
-@item details
-Enable more detailed dumps (not honored by every dump option). Also
-include information from the optimization passes.
-@item stats
-Enable dumping various statistics about the pass (not honored by every dump
-option).
-@item blocks
-Enable showing basic block boundaries (disabled in raw dumps).
-@item graph
-For each of the other indicated dump files (@option{-fdump-rtl-@var{pass}}),
-dump a representation of the control flow graph suitable for viewing with
-GraphViz to @file{@var{file}.@var{passid}.@var{pass}.dot}. Each function in
-the file is pretty-printed as a subgraph, so that GraphViz can render them
-all in a single plot.
-
-This option currently only works for RTL dumps, and the RTL is always
-dumped in slim form.
-@item vops
-Enable showing virtual operands for every statement.
-@item lineno
-Enable showing line numbers for statements.
-@item uid
-Enable showing the unique ID (@code{DECL_UID}) for each variable.
-@item verbose
-Enable showing the tree dump for each statement.
-@item eh
-Enable showing the EH region number holding each statement.
-@item scev
-Enable showing scalar evolution analysis details.
-@item optimized
-Enable showing optimization information (only available in certain
-passes).
-@item missed
-Enable showing missed optimization information (only available in certain
-passes).
-@item note
-Enable other detailed optimization information (only available in
-certain passes).
-@item =@var{filename}
-Instead of an auto named dump file, output into the given file
-name. The file names @file{stdout} and @file{stderr} are treated
-specially and are considered already open standard streams. For
-example,
-
-@smallexample
-gcc -O2 -ftree-vectorize -fdump-tree-vect-blocks=foo.dump
- -fdump-tree-pre=stderr file.c
-@end smallexample
-
-outputs vectorizer dump into @file{foo.dump}, while the PRE dump is
-output on to @file{stderr}. If two conflicting dump filenames are
-given for the same pass, then the latter option overrides the earlier
-one.
-
-@item split-paths
-@opindex fdump-tree-split-paths
-Dump each function after splitting paths to loop backedges. The file
-name is made by appending @file{.split-paths} to the source file name.
-
-@item all
-Turn on all options, except @option{raw}, @option{slim}, @option{verbose}
-and @option{lineno}.
-
-@item optall
-Turn on all optimization options, i.e., @option{optimized},
-@option{missed}, and @option{note}.
-@end table
-
-The following tree dumps are possible:
-@table @samp
-
-@item original
-@opindex fdump-tree-original
-Dump before any tree based optimization, to @file{@var{file}.original}.
-
-@item optimized
-@opindex fdump-tree-optimized
-Dump after all tree based optimization, to @file{@var{file}.optimized}.
-
-@item gimple
-@opindex fdump-tree-gimple
-Dump each function before and after the gimplification pass to a file. The
-file name is made by appending @file{.gimple} to the source file name.
-
-@item cfg
-@opindex fdump-tree-cfg
-Dump the control flow graph of each function to a file. The file name is
-made by appending @file{.cfg} to the source file name.
-
-@item ch
-@opindex fdump-tree-ch
-Dump each function after copying loop headers. The file name is made by
-appending @file{.ch} to the source file name.
-
-@item ssa
-@opindex fdump-tree-ssa
-Dump SSA related information to a file. The file name is made by appending
-@file{.ssa} to the source file name.
-
-@item alias
-@opindex fdump-tree-alias
-Dump aliasing information for each function. The file name is made by
-appending @file{.alias} to the source file name.
-
-@item ccp
-@opindex fdump-tree-ccp
-Dump each function after CCP@. The file name is made by appending
-@file{.ccp} to the source file name.
-
-@item storeccp
-@opindex fdump-tree-storeccp
-Dump each function after STORE-CCP@. The file name is made by appending
-@file{.storeccp} to the source file name.
-
-@item pre
-@opindex fdump-tree-pre
-Dump trees after partial redundancy elimination. The file name is made
-by appending @file{.pre} to the source file name.
-
-@item fre
-@opindex fdump-tree-fre
-Dump trees after full redundancy elimination. The file name is made
-by appending @file{.fre} to the source file name.
-
-@item copyprop
-@opindex fdump-tree-copyprop
-Dump trees after copy propagation. The file name is made
-by appending @file{.copyprop} to the source file name.
-
-@item store_copyprop
-@opindex fdump-tree-store_copyprop
-Dump trees after store copy-propagation. The file name is made
-by appending @file{.store_copyprop} to the source file name.
-
-@item dce
-@opindex fdump-tree-dce
-Dump each function after dead code elimination. The file name is made by
-appending @file{.dce} to the source file name.
-
-@item sra
-@opindex fdump-tree-sra
-Dump each function after performing scalar replacement of aggregates. The
-file name is made by appending @file{.sra} to the source file name.
-
-@item sink
-@opindex fdump-tree-sink
-Dump each function after performing code sinking. The file name is made
-by appending @file{.sink} to the source file name.
-
-@item dom
-@opindex fdump-tree-dom
-Dump each function after applying dominator tree optimizations. The file
-name is made by appending @file{.dom} to the source file name.
-
-@item dse
-@opindex fdump-tree-dse
-Dump each function after applying dead store elimination. The file
-name is made by appending @file{.dse} to the source file name.
-
-@item phiopt
-@opindex fdump-tree-phiopt
-Dump each function after optimizing PHI nodes into straightline code. The file
-name is made by appending @file{.phiopt} to the source file name.
-
-@item backprop
-@opindex fdump-tree-backprop
-Dump each function after back-propagating use information up the definition
-chain. The file name is made by appending @file{.backprop} to the
-source file name.
-
-@item forwprop
-@opindex fdump-tree-forwprop
-Dump each function after forward propagating single use variables. The file
-name is made by appending @file{.forwprop} to the source file name.
-
-@item nrv
-@opindex fdump-tree-nrv
-Dump each function after applying the named return value optimization on
-generic trees. The file name is made by appending @file{.nrv} to the source
-file name.
-
-@item vect
-@opindex fdump-tree-vect
-Dump each function after applying vectorization of loops. The file name is
-made by appending @file{.vect} to the source file name.
-
-@item slp
-@opindex fdump-tree-slp
-Dump each function after applying vectorization of basic blocks. The file name
-is made by appending @file{.slp} to the source file name.
-
-@item vrp
-@opindex fdump-tree-vrp
-Dump each function after Value Range Propagation (VRP). The file name
-is made by appending @file{.vrp} to the source file name.
-
-@item oaccdevlow
-@opindex fdump-tree-oaccdevlow
-Dump each function after applying device-specific OpenACC transformations.
-The file name is made by appending @file{.oaccdevlow} to the source file name.
-
-@item all
-@opindex fdump-tree-all
-Enable all the available tree dumps with the flags provided in this option.
-@end table
-
-@item -fopt-info
-@itemx -fopt-info-@var{options}
-@itemx -fopt-info-@var{options}=@var{filename}
-@opindex fopt-info
-Controls optimization dumps from various optimization passes. If the
-@samp{-@var{options}} form is used, @var{options} is a list of
-@samp{-} separated option keywords to select the dump details and
-optimizations.
-
-The @var{options} can be divided into two groups: options describing the
-verbosity of the dump, and options describing which optimizations
-should be included. The options from both the groups can be freely
-mixed as they are non-overlapping. However, in case of any conflicts,
-the later options override the earlier options on the command
-line.
-
-The following options control the dump verbosity:
-
-@table @samp
-@item optimized
-Print information when an optimization is successfully applied. It is
-up to a pass to decide which information is relevant. For example, the
-vectorizer passes print the source location of loops which are
-successfully vectorized.
-@item missed
-Print information about missed optimizations. Individual passes
-control which information to include in the output.
-@item note
-Print verbose information about optimizations, such as certain
-transformations, more detailed messages about decisions etc.
-@item all
-Print detailed optimization information. This includes
-@samp{optimized}, @samp{missed}, and @samp{note}.
-@end table
-
-One or more of the following option keywords can be used to describe a
-group of optimizations:
-
-@table @samp
-@item ipa
-Enable dumps from all interprocedural optimizations.
-@item loop
-Enable dumps from all loop optimizations.
-@item inline
-Enable dumps from all inlining optimizations.
-@item vec
-Enable dumps from all vectorization optimizations.
-@item optall
-Enable dumps from all optimizations. This is a superset of
-the optimization groups listed above.
-@end table
-
-If @var{options} is
-omitted, it defaults to @samp{optimized-optall}, which means to dump all
-info about successful optimizations from all the passes.
-
-If the @var{filename} is provided, then the dumps from all the
-applicable optimizations are concatenated into the @var{filename}.
-Otherwise the dump is output onto @file{stderr}. Though multiple
-@option{-fopt-info} options are accepted, only one of them can include
-a @var{filename}. If other filenames are provided then all but the
-first such option are ignored.
-
-Note that the output @var{filename} is overwritten
-in case of multiple translation units. If a combined output from
-multiple translation units is desired, @file{stderr} should be used
-instead.
-
-In the following example, the optimization info is output to
-@file{stderr}:
-
-@smallexample
-gcc -O3 -fopt-info
-@end smallexample
-
-This example:
-@smallexample
-gcc -O3 -fopt-info-missed=missed.all
-@end smallexample
-
-@noindent
-outputs missed optimization report from all the passes into
-@file{missed.all}, and this one:
-
-@smallexample
-gcc -O2 -ftree-vectorize -fopt-info-vec-missed
-@end smallexample
-
-@noindent
-prints information about missed optimization opportunities from
-vectorization passes on @file{stderr}.
-Note that @option{-fopt-info-vec-missed} is equivalent to
-@option{-fopt-info-missed-vec}.
-
-As another example,
-@smallexample
-gcc -O3 -fopt-info-inline-optimized-missed=inline.txt
-@end smallexample
-
-@noindent
-outputs information about missed optimizations as well as
-optimized locations from all the inlining passes into
-@file{inline.txt}.
-
-Finally, consider:
-
-@smallexample
-gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt
-@end smallexample
-
-@noindent
-Here the two output filenames @file{vec.miss} and @file{loop.opt} are
-in conflict since only one output file is allowed. In this case, only
-the first option takes effect and the subsequent options are
-ignored. Thus only @file{vec.miss} is produced which contains
-dumps from the vectorizer about missed opportunities.
-
-@item -frandom-seed=@var{string}
-@opindex frandom-seed
-This option provides a seed that GCC uses in place of
-random numbers in generating certain symbol names
-that have to be different in every compiled file. It is also used to
-place unique stamps in coverage data files and the object files that
-produce them. You can use the @option{-frandom-seed} option to produce
-reproducibly identical object files.
-
-The @var{string} can either be a number (decimal, octal or hex) or an
-arbitrary string (in which case it's converted to a number by
-computing CRC32).
-
-The @var{string} should be different for every file you compile.
-
-@item -fsched-verbose=@var{n}
-@opindex fsched-verbose
-On targets that use instruction scheduling, this option controls the
-amount of debugging output the scheduler prints to the dump files.
-
-For @var{n} greater than zero, @option{-fsched-verbose} outputs the
-same information as @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2}.
-For @var{n} greater than one, it also output basic block probabilities,
-detailed ready list information and unit/insn info. For @var{n} greater
-than two, it includes RTL at abort point, control-flow and regions info.
-And for @var{n} over four, @option{-fsched-verbose} also includes
-dependence info.
-
-@item -save-temps
-@itemx -save-temps=cwd
-@opindex save-temps
-Store the usual ``temporary'' intermediate files permanently; place them
-in the current directory and name them based on the source file. Thus,
-compiling @file{foo.c} with @option{-c -save-temps} produces files
-@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
-preprocessed @file{foo.i} output file even though the compiler now
-normally uses an integrated preprocessor.
-
-When used in combination with the @option{-x} command-line option,
-@option{-save-temps} is sensible enough to avoid over writing an
-input source file with the same extension as an intermediate file.
-The corresponding intermediate file may be obtained by renaming the
-source file before using @option{-save-temps}.
-
-If you invoke GCC in parallel, compiling several different source
-files that share a common base name in different subdirectories or the
-same source file compiled for multiple output destinations, it is
-likely that the different parallel compilers will interfere with each
-other, and overwrite the temporary files. For instance:
-
-@smallexample
-gcc -save-temps -o outdir1/foo.o indir1/foo.c&
-gcc -save-temps -o outdir2/foo.o indir2/foo.c&
-@end smallexample
-
-may result in @file{foo.i} and @file{foo.o} being written to
-simultaneously by both compilers.
-
-@item -save-temps=obj
-@opindex save-temps=obj
-Store the usual ``temporary'' intermediate files permanently. If the
-@option{-o} option is used, the temporary files are based on the
-object file. If the @option{-o} option is not used, the
-@option{-save-temps=obj} switch behaves like @option{-save-temps}.
-
-For example:
-
-@smallexample
-gcc -save-temps=obj -c foo.c
-gcc -save-temps=obj -c bar.c -o dir/xbar.o
-gcc -save-temps=obj foobar.c -o dir2/yfoobar
-@end smallexample
-
-@noindent
-creates @file{foo.i}, @file{foo.s}, @file{dir/xbar.i},
-@file{dir/xbar.s}, @file{dir2/yfoobar.i}, @file{dir2/yfoobar.s}, and
-@file{dir2/yfoobar.o}.
-
-@item -time@r{[}=@var{file}@r{]}
-@opindex time
-Report the CPU time taken by each subprocess in the compilation
-sequence. For C source files, this is the compiler proper and assembler
-(plus the linker if linking is done).
-
-Without the specification of an output file, the output looks like this:
-
-@smallexample
-# cc1 0.12 0.01
-# as 0.00 0.01
-@end smallexample
-
-The first number on each line is the ``user time'', that is time spent
-executing the program itself. The second number is ``system time'',
-time spent executing operating system routines on behalf of the program.
-Both numbers are in seconds.
-
-With the specification of an output file, the output is appended to the
-named file, and it looks like this:
-
-@smallexample
-0.12 0.01 cc1 @var{options}
-0.00 0.01 as @var{options}
-@end smallexample
-
-The ``user time'' and the ``system time'' are moved before the program
-name, and the options passed to the program are displayed, so that one
-can later tell what file was being compiled, and with which options.
-
-@item -fvar-tracking
-@opindex fvar-tracking
-Run variable tracking pass. It computes where variables are stored at each
-position in code. Better debugging information is then generated
-(if the debugging information format supports this information).
-
-It is enabled by default when compiling with optimization (@option{-Os},
-@option{-O}, @option{-O2}, @dots{}), debugging information (@option{-g}) and
-the debug info format supports it.
-
-@item -fvar-tracking-assignments
-@opindex fvar-tracking-assignments
-@opindex fno-var-tracking-assignments
-Annotate assignments to user variables early in the compilation and
-attempt to carry the annotations over throughout the compilation all the
-way to the end, in an attempt to improve debug information while
-optimizing. Use of @option{-gdwarf-4} is recommended along with it.
-
-It can be enabled even if var-tracking is disabled, in which case
-annotations are created and maintained, but discarded at the end.
-By default, this flag is enabled together with @option{-fvar-tracking},
-except when selective scheduling is enabled.
-
-@item -fvar-tracking-assignments-toggle
-@opindex fvar-tracking-assignments-toggle
-@opindex fno-var-tracking-assignments-toggle
-Toggle @option{-fvar-tracking-assignments}, in the same way that
-@option{-gtoggle} toggles @option{-g}.
-
-@item -print-file-name=@var{library}
-@opindex print-file-name
-Print the full absolute name of the library file @var{library} that
-would be used when linking---and don't do anything else. With this
-option, GCC does not compile or link anything; it just prints the
-file name.
-
-@item -print-multi-directory
-@opindex print-multi-directory
-Print the directory name corresponding to the multilib selected by any
-other switches present in the command line. This directory is supposed
-to exist in @env{GCC_EXEC_PREFIX}.
-
-@item -print-multi-lib
-@opindex print-multi-lib
-Print the mapping from multilib directory names to compiler switches
-that enable them. The directory name is separated from the switches by
-@samp{;}, and each switch starts with an @samp{@@} instead of the
-@samp{-}, without spaces between multiple switches. This is supposed to
-ease shell processing.
-
-@item -print-multi-os-directory
-@opindex print-multi-os-directory
-Print the path to OS libraries for the selected
-multilib, relative to some @file{lib} subdirectory. If OS libraries are
-present in the @file{lib} subdirectory and no multilibs are used, this is
-usually just @file{.}, if OS libraries are present in @file{lib@var{suffix}}
-sibling directories this prints e.g.@: @file{../lib64}, @file{../lib} or
-@file{../lib32}, or if OS libraries are present in @file{lib/@var{subdir}}
-subdirectories it prints e.g.@: @file{amd64}, @file{sparcv9} or @file{ev6}.
-
-@item -print-multiarch
-@opindex print-multiarch
-Print the path to OS libraries for the selected multiarch,
-relative to some @file{lib} subdirectory.
-
-@item -print-prog-name=@var{program}
-@opindex print-prog-name
-Like @option{-print-file-name}, but searches for a program such as @command{cpp}.
-
-@item -print-libgcc-file-name
-@opindex print-libgcc-file-name
-Same as @option{-print-file-name=libgcc.a}.
-
-This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
-but you do want to link with @file{libgcc.a}. You can do:
-
-@smallexample
-gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
-@end smallexample
-
-@item -print-search-dirs
-@opindex print-search-dirs
-Print the name of the configured installation directory and a list of
-program and library directories @command{gcc} searches---and don't do anything else.
-
-This is useful when @command{gcc} prints the error message
-@samp{installation problem, cannot exec cpp0: No such file or directory}.
-To resolve this you either need to put @file{cpp0} and the other compiler
-components where @command{gcc} expects to find them, or you can set the environment
-variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
-Don't forget the trailing @samp{/}.
-@xref{Environment Variables}.
-
-@item -print-sysroot
-@opindex print-sysroot
-Print the target sysroot directory that is used during
-compilation. This is the target sysroot specified either at configure
-time or using the @option{--sysroot} option, possibly with an extra
-suffix that depends on compilation options. If no target sysroot is
-specified, the option prints nothing.
-
-@item -print-sysroot-headers-suffix
-@opindex print-sysroot-headers-suffix
-Print the suffix added to the target sysroot when searching for
-headers, or give an error if the compiler is not configured with such
-a suffix---and don't do anything else.
-
-@item -dumpmachine
-@opindex dumpmachine
-Print the compiler's target machine (for example,
-@samp{i686-pc-linux-gnu})---and don't do anything else.
-
-@item -dumpversion
-@opindex dumpversion
-Print the compiler version (for example, @code{3.0})---and don't do
-anything else.
-
-@item -dumpspecs
-@opindex dumpspecs
-Print the compiler's built-in specs---and don't do anything else. (This
-is used when GCC itself is being built.) @xref{Spec Files}.
-
@item -fno-eliminate-unused-debug-types
@opindex feliminate-unused-debug-types
@opindex fno-eliminate-unused-debug-types
@@ -7988,12 +6813,6 @@ Disable sharing of stack slots allocated
pseudo-register that does not get a hard register gets a separate
stack slot, and as a result function stack frames are larger.
-@item -fira-verbose=@var{n}
-@opindex fira-verbose
-Control the verbosity of the dump file for the integrated register allocator.
-The default value is 5. If the value @var{n} is greater or equal to 10,
-the dump output is sent to stderr using the same format as @var{n} minus 10.
-
@item -flra-remat
@opindex flra-remat
Enable CFG-sensitive rematerialization in LRA. Instead of loading
@@ -9227,20 +8046,6 @@ values are 0 (no compression) to 9 (maxi
outside this range are clamped to either 0 or 9. If the option is not
given, a default balanced compression setting is used.
-@item -flto-report
-@opindex flto-report
-Prints a report with internal details on the workings of the link-time
-optimizer. The contents of this report vary from version to version.
-It is meant to be useful to GCC developers when processing object
-files in LTO mode (via @option{-flto}).
-
-Disabled by default.
-
-@item -flto-report-wpa
-@opindex flto-report-wpa
-Like @option{-flto-report}, but only print for the WPA phase of Link
-Time Optimization.
-
@item -fuse-linker-plugin
@opindex fuse-linker-plugin
Enables the use of a linker plugin during link-time optimization. This
@@ -12610,6 +11415,1234 @@ the implementation of the @file{libatomi
@end table
+@node Developer Options
+@section GCC Developer Options
+@cindex developer options
+@cindex debugging GCC
+@cindex debug dump options
+@cindex dump options
+@cindex compilation statistics
+
+This section describes command-line options that are primarily of
+interest to GCC developers, including options to support compiler
+testing and investigation of compiler bugs and compile-time
+performance problems. This includes options that produce debug dumps
+at various points in the compilation; that print statistics such as
+memory use and execution time; and that print information about GCC's
+configuration, such as where it searches for libraries. You should
+rarely need to use any of these options for ordinary compilation and
+linking tasks.
+
+@table @gcctabopt
+
+@item -d@var{letters}
+@itemx -fdump-rtl-@var{pass}
+@itemx -fdump-rtl-@var{pass}=@var{filename}
+@opindex d
+@opindex fdump-rtl-@var{pass}
+Says to make debugging dumps during compilation at times specified by
+@var{letters}. This is used for debugging the RTL-based passes of the
+compiler. The file names for most of the dumps are made by appending
+a pass number and a word to the @var{dumpname}, and the files are
+created in the directory of the output file. In case of
+@option{=@var{filename}} option, the dump is output on the given file
+instead of the pass numbered dump files. Note that the pass number is
+assigned as passes are registered into the pass manager. Most passes
+are registered in the order that they will execute and for these passes
+the number corresponds to the pass execution order. However, passes
+registered by plugins, passes specific to compilation targets, or
+passes that are otherwise registered after all the other passes are
+numbered higher than a pass named "final", even if they are executed
+earlier. @var{dumpname} is generated from the name of the output
+file if explicitly specified and not an executable, otherwise it is
+the basename of the source file. These switches may have different
+effects when @option{-E} is used for preprocessing.
+
+Debug dumps can be enabled with a @option{-fdump-rtl} switch or some
+@option{-d} option @var{letters}. Here are the possible
+letters for use in @var{pass} and @var{letters}, and their meanings:
+
+@table @gcctabopt
+
+@item -fdump-rtl-alignments
+@opindex fdump-rtl-alignments
+Dump after branch alignments have been computed.
+
+@item -fdump-rtl-asmcons
+@opindex fdump-rtl-asmcons
+Dump after fixing rtl statements that have unsatisfied in/out constraints.
+
+@item -fdump-rtl-auto_inc_dec
+@opindex fdump-rtl-auto_inc_dec
+Dump after auto-inc-dec discovery. This pass is only run on
+architectures that have auto inc or auto dec instructions.
+
+@item -fdump-rtl-barriers
+@opindex fdump-rtl-barriers
+Dump after cleaning up the barrier instructions.
+
+@item -fdump-rtl-bbpart
+@opindex fdump-rtl-bbpart
+Dump after partitioning hot and cold basic blocks.
+
+@item -fdump-rtl-bbro
+@opindex fdump-rtl-bbro
+Dump after block reordering.
+
+@item -fdump-rtl-btl1
+@itemx -fdump-rtl-btl2
+@opindex fdump-rtl-btl2
+@opindex fdump-rtl-btl2
+@option{-fdump-rtl-btl1} and @option{-fdump-rtl-btl2} enable dumping
+after the two branch
+target load optimization passes.
+
+@item -fdump-rtl-bypass
+@opindex fdump-rtl-bypass
+Dump after jump bypassing and control flow optimizations.
+
+@item -fdump-rtl-combine
+@opindex fdump-rtl-combine
+Dump after the RTL instruction combination pass.
+
+@item -fdump-rtl-compgotos
+@opindex fdump-rtl-compgotos
+Dump after duplicating the computed gotos.
+
+@item -fdump-rtl-ce1
+@itemx -fdump-rtl-ce2
+@itemx -fdump-rtl-ce3
+@opindex fdump-rtl-ce1
+@opindex fdump-rtl-ce2
+@opindex fdump-rtl-ce3
+@option{-fdump-rtl-ce1}, @option{-fdump-rtl-ce2}, and
+@option{-fdump-rtl-ce3} enable dumping after the three
+if conversion passes.
+
+@item -fdump-rtl-cprop_hardreg
+@opindex fdump-rtl-cprop_hardreg
+Dump after hard register copy propagation.
+
+@item -fdump-rtl-csa
+@opindex fdump-rtl-csa
+Dump after combining stack adjustments.
+
+@item -fdump-rtl-cse1
+@itemx -fdump-rtl-cse2
+@opindex fdump-rtl-cse1
+@opindex fdump-rtl-cse2
+@option{-fdump-rtl-cse1} and @option{-fdump-rtl-cse2} enable dumping after
+the two common subexpression elimination passes.
+
+@item -fdump-rtl-dce
+@opindex fdump-rtl-dce
+Dump after the standalone dead code elimination passes.
+
+@item -fdump-rtl-dbr
+@opindex fdump-rtl-dbr
+Dump after delayed branch scheduling.
+
+@item -fdump-rtl-dce1
+@itemx -fdump-rtl-dce2
+@opindex fdump-rtl-dce1
+@opindex fdump-rtl-dce2
+@option{-fdump-rtl-dce1} and @option{-fdump-rtl-dce2} enable dumping after
+the two dead store elimination passes.
+
+@item -fdump-rtl-eh
+@opindex fdump-rtl-eh
+Dump after finalization of EH handling code.
+
+@item -fdump-rtl-eh_ranges
+@opindex fdump-rtl-eh_ranges
+Dump after conversion of EH handling range regions.
+
+@item -fdump-rtl-expand
+@opindex fdump-rtl-expand
+Dump after RTL generation.
+
+@item -fdump-rtl-fwprop1
+@itemx -fdump-rtl-fwprop2
+@opindex fdump-rtl-fwprop1
+@opindex fdump-rtl-fwprop2
+@option{-fdump-rtl-fwprop1} and @option{-fdump-rtl-fwprop2} enable
+dumping after the two forward propagation passes.
+
+@item -fdump-rtl-gcse1
+@itemx -fdump-rtl-gcse2
+@opindex fdump-rtl-gcse1
+@opindex fdump-rtl-gcse2
+@option{-fdump-rtl-gcse1} and @option{-fdump-rtl-gcse2} enable dumping
+after global common subexpression elimination.
+
+@item -fdump-rtl-init-regs
+@opindex fdump-rtl-init-regs
+Dump after the initialization of the registers.
+
+@item -fdump-rtl-initvals
+@opindex fdump-rtl-initvals
+Dump after the computation of the initial value sets.
+
+@item -fdump-rtl-into_cfglayout
+@opindex fdump-rtl-into_cfglayout
+Dump after converting to cfglayout mode.
+
+@item -fdump-rtl-ira
+@opindex fdump-rtl-ira
+Dump after iterated register allocation.
+
+@item -fdump-rtl-jump
+@opindex fdump-rtl-jump
+Dump after the second jump optimization.
+
+@item -fdump-rtl-loop2
+@opindex fdump-rtl-loop2
+@option{-fdump-rtl-loop2} enables dumping after the rtl
+loop optimization passes.
+
+@item -fdump-rtl-mach
+@opindex fdump-rtl-mach
+Dump after performing the machine dependent reorganization pass, if that
+pass exists.
+
+@item -fdump-rtl-mode_sw
+@opindex fdump-rtl-mode_sw
+Dump after removing redundant mode switches.
+
+@item -fdump-rtl-rnreg
+@opindex fdump-rtl-rnreg
+Dump after register renumbering.
+
+@item -fdump-rtl-outof_cfglayout
+@opindex fdump-rtl-outof_cfglayout
+Dump after converting from cfglayout mode.
+
+@item -fdump-rtl-peephole2
+@opindex fdump-rtl-peephole2
+Dump after the peephole pass.
+
+@item -fdump-rtl-postreload
+@opindex fdump-rtl-postreload
+Dump after post-reload optimizations.
+
+@item -fdump-rtl-pro_and_epilogue
+@opindex fdump-rtl-pro_and_epilogue
+Dump after generating the function prologues and epilogues.
+
+@item -fdump-rtl-sched1
+@itemx -fdump-rtl-sched2
+@opindex fdump-rtl-sched1
+@opindex fdump-rtl-sched2
+@option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2} enable dumping
+after the basic block scheduling passes.
+
+@item -fdump-rtl-ree
+@opindex fdump-rtl-ree
+Dump after sign/zero extension elimination.
+
+@item -fdump-rtl-seqabstr
+@opindex fdump-rtl-seqabstr
+Dump after common sequence discovery.
+
+@item -fdump-rtl-shorten
+@opindex fdump-rtl-shorten
+Dump after shortening branches.
+
+@item -fdump-rtl-sibling
+@opindex fdump-rtl-sibling
+Dump after sibling call optimizations.
+
+@item -fdump-rtl-split1
+@itemx -fdump-rtl-split2
+@itemx -fdump-rtl-split3
+@itemx -fdump-rtl-split4
+@itemx -fdump-rtl-split5
+@opindex fdump-rtl-split1
+@opindex fdump-rtl-split2
+@opindex fdump-rtl-split3
+@opindex fdump-rtl-split4
+@opindex fdump-rtl-split5
+These options enable dumping after five rounds of
+instruction splitting.
+
+@item -fdump-rtl-sms
+@opindex fdump-rtl-sms
+Dump after modulo scheduling. This pass is only run on some
+architectures.
+
+@item -fdump-rtl-stack
+@opindex fdump-rtl-stack
+Dump after conversion from GCC's ``flat register file'' registers to the
+x87's stack-like registers. This pass is only run on x86 variants.
+
+@item -fdump-rtl-subreg1
+@itemx -fdump-rtl-subreg2
+@opindex fdump-rtl-subreg1
+@opindex fdump-rtl-subreg2
+@option{-fdump-rtl-subreg1} and @option{-fdump-rtl-subreg2} enable dumping after
+the two subreg expansion passes.
+
+@item -fdump-rtl-unshare
+@opindex fdump-rtl-unshare
+Dump after all rtl has been unshared.
+
+@item -fdump-rtl-vartrack
+@opindex fdump-rtl-vartrack
+Dump after variable tracking.
+
+@item -fdump-rtl-vregs
+@opindex fdump-rtl-vregs
+Dump after converting virtual registers to hard registers.
+
+@item -fdump-rtl-web
+@opindex fdump-rtl-web
+Dump after live range splitting.
+
+@item -fdump-rtl-regclass
+@itemx -fdump-rtl-subregs_of_mode_init
+@itemx -fdump-rtl-subregs_of_mode_finish
+@itemx -fdump-rtl-dfinit
+@itemx -fdump-rtl-dfinish
+@opindex fdump-rtl-regclass
+@opindex fdump-rtl-subregs_of_mode_init
+@opindex fdump-rtl-subregs_of_mode_finish
+@opindex fdump-rtl-dfinit
+@opindex fdump-rtl-dfinish
+These dumps are defined but always produce empty files.
+
+@item -da
+@itemx -fdump-rtl-all
+@opindex da
+@opindex fdump-rtl-all
+Produce all the dumps listed above.
+
+@item -dA
+@opindex dA
+Annotate the assembler output with miscellaneous debugging information.
+
+@item -dD
+@opindex dD
+Dump all macro definitions, at the end of preprocessing, in addition to
+normal output.
+
+@item -dH
+@opindex dH
+Produce a core dump whenever an error occurs.
+
+@item -dp
+@opindex dp
+Annotate the assembler output with a comment indicating which
+pattern and alternative is used. The length of each instruction is
+also printed.
+
+@item -dP
+@opindex dP
+Dump the RTL in the assembler output as a comment before each instruction.
+Also turns on @option{-dp} annotation.
+
+@item -dx
+@opindex dx
+Just generate RTL for a function instead of compiling it. Usually used
+with @option{-fdump-rtl-expand}.
+@end table
+
+@item -fdump-noaddr
+@opindex fdump-noaddr
+When doing debugging dumps, suppress address output. This makes it more
+feasible to use diff on debugging dumps for compiler invocations with
+different compiler binaries and/or different
+text / bss / data / heap / stack / dso start locations.
+
+@item -freport-bug
+@opindex freport-bug
+Collect and dump debug information into temporary file if ICE in C/C++
+compiler occured.
+
+@item -fdump-unnumbered
+@opindex fdump-unnumbered
+When doing debugging dumps, suppress instruction numbers and address output.
+This makes it more feasible to use diff on debugging dumps for compiler
+invocations with different options, in particular with and without
+@option{-g}.
+
+@item -fdump-unnumbered-links
+@opindex fdump-unnumbered-links
+When doing debugging dumps (see @option{-d} option above), suppress
+instruction numbers for the links to the previous and next instructions
+in a sequence.
+
+@item -fdump-translation-unit @r{(C++ only)}
+@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
+@opindex fdump-translation-unit
+Dump a representation of the tree structure for the entire translation
+unit to a file. The file name is made by appending @file{.tu} to the
+source file name, and the file is created in the same directory as the
+output file. If the @samp{-@var{options}} form is used, @var{options}
+controls the details of the dump as described for the
+@option{-fdump-tree} options.
+
+@item -fdump-class-hierarchy @r{(C++ only)}
+@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
+@opindex fdump-class-hierarchy
+Dump a representation of each class's hierarchy and virtual function
+table layout to a file. The file name is made by appending
+@file{.class} to the source file name, and the file is created in the
+same directory as the output file. If the @samp{-@var{options}} form
+is used, @var{options} controls the details of the dump as described
+for the @option{-fdump-tree} options.
+
+@item -fdump-ipa-@var{switch}
+@opindex fdump-ipa
+Control the dumping at various stages of inter-procedural analysis
+language tree to a file. The file name is generated by appending a
+switch specific suffix to the source file name, and the file is created
+in the same directory as the output file. The following dumps are
+possible:
+
+@table @samp
+@item all
+Enables all inter-procedural analysis dumps.
+
+@item cgraph
+Dumps information about call-graph optimization, unused function removal,
+and inlining decisions.
+
+@item inline
+Dump after function inlining.
+
+@end table
+
+@item -fdump-passes
+@opindex fdump-passes
+Dump the list of optimization passes that are turned on and off by
+the current command-line options.
+
+@item -fdump-statistics-@var{option}
+@opindex fdump-statistics
+Enable and control dumping of pass statistics in a separate file. The
+file name is generated by appending a suffix ending in
+@samp{.statistics} to the source file name, and the file is created in
+the same directory as the output file. If the @samp{-@var{option}}
+form is used, @samp{-stats} causes counters to be summed over the
+whole compilation unit while @samp{-details} dumps every event as
+the passes generate them. The default with no option is to sum
+counters for each function compiled.
+
+@item -fdump-tree-@var{switch}
+@itemx -fdump-tree-@var{switch}-@var{options}
+@itemx -fdump-tree-@var{switch}-@var{options}=@var{filename}
+@opindex fdump-tree
+Control the dumping at various stages of processing the intermediate
+language tree to a file. The file name is generated by appending a
+switch-specific suffix to the source file name, and the file is
+created in the same directory as the output file. In case of
+@option{=@var{filename}} option, the dump is output on the given file
+instead of the auto named dump files. If the @samp{-@var{options}}
+form is used, @var{options} is a list of @samp{-} separated options
+which control the details of the dump. Not all options are applicable
+to all dumps; those that are not meaningful are ignored. The
+following options are available
+
+@table @samp
+@item address
+Print the address of each node. Usually this is not meaningful as it
+changes according to the environment and source file. Its primary use
+is for tying up a dump file with a debug environment.
+@item asmname
+If @code{DECL_ASSEMBLER_NAME} has been set for a given decl, use that
+in the dump instead of @code{DECL_NAME}. Its primary use is ease of
+use working backward from mangled names in the assembly file.
+@item slim
+When dumping front-end intermediate representations, inhibit dumping
+of members of a scope or body of a function merely because that scope
+has been reached. Only dump such items when they are directly reachable
+by some other path.
+
+When dumping pretty-printed trees, this option inhibits dumping the
+bodies of control structures.
+
+When dumping RTL, print the RTL in slim (condensed) form instead of
+the default LISP-like representation.
+@item raw
+Print a raw representation of the tree. By default, trees are
+pretty-printed into a C-like representation.
+@item details
+Enable more detailed dumps (not honored by every dump option). Also
+include information from the optimization passes.
+@item stats
+Enable dumping various statistics about the pass (not honored by every dump
+option).
+@item blocks
+Enable showing basic block boundaries (disabled in raw dumps).
+@item graph
+For each of the other indicated dump files (@option{-fdump-rtl-@var{pass}}),
+dump a representation of the control flow graph suitable for viewing with
+GraphViz to @file{@var{file}.@var{passid}.@var{pass}.dot}. Each function in
+the file is pretty-printed as a subgraph, so that GraphViz can render them
+all in a single plot.
+
+This option currently only works for RTL dumps, and the RTL is always
+dumped in slim form.
+@item vops
+Enable showing virtual operands for every statement.
+@item lineno
+Enable showing line numbers for statements.
+@item uid
+Enable showing the unique ID (@code{DECL_UID}) for each variable.
+@item verbose
+Enable showing the tree dump for each statement.
+@item eh
+Enable showing the EH region number holding each statement.
+@item scev
+Enable showing scalar evolution analysis details.
+@item optimized
+Enable showing optimization information (only available in certain
+passes).
+@item missed
+Enable showing missed optimization information (only available in certain
+passes).
+@item note
+Enable other detailed optimization information (only available in
+certain passes).
+@item =@var{filename}
+Instead of an auto named dump file, output into the given file
+name. The file names @file{stdout} and @file{stderr} are treated
+specially and are considered already open standard streams. For
+example,
+
+@smallexample
+gcc -O2 -ftree-vectorize -fdump-tree-vect-blocks=foo.dump
+ -fdump-tree-pre=stderr file.c
+@end smallexample
+
+outputs vectorizer dump into @file{foo.dump}, while the PRE dump is
+output on to @file{stderr}. If two conflicting dump filenames are
+given for the same pass, then the latter option overrides the earlier
+one.
+
+@item split-paths
+@opindex fdump-tree-split-paths
+Dump each function after splitting paths to loop backedges. The file
+name is made by appending @file{.split-paths} to the source file name.
+
+@item all
+Turn on all options, except @option{raw}, @option{slim}, @option{verbose}
+and @option{lineno}.
+
+@item optall
+Turn on all optimization options, i.e., @option{optimized},
+@option{missed}, and @option{note}.
+@end table
+
+The following tree dumps are possible:
+@table @samp
+
+@item original
+@opindex fdump-tree-original
+Dump before any tree based optimization, to @file{@var{file}.original}.
+
+@item optimized
+@opindex fdump-tree-optimized
+Dump after all tree based optimization, to @file{@var{file}.optimized}.
+
+@item gimple
+@opindex fdump-tree-gimple
+Dump each function before and after the gimplification pass to a file. The
+file name is made by appending @file{.gimple} to the source file name.
+
+@item cfg
+@opindex fdump-tree-cfg
+Dump the control flow graph of each function to a file. The file name is
+made by appending @file{.cfg} to the source file name.
+
+@item ch
+@opindex fdump-tree-ch
+Dump each function after copying loop headers. The file name is made by
+appending @file{.ch} to the source file name.
+
+@item ssa
+@opindex fdump-tree-ssa
+Dump SSA related information to a file. The file name is made by appending
+@file{.ssa} to the source file name.
+
+@item alias
+@opindex fdump-tree-alias
+Dump aliasing information for each function. The file name is made by
+appending @file{.alias} to the source file name.
+
+@item ccp
+@opindex fdump-tree-ccp
+Dump each function after CCP@. The file name is made by appending
+@file{.ccp} to the source file name.
+
+@item storeccp
+@opindex fdump-tree-storeccp
+Dump each function after STORE-CCP@. The file name is made by appending
+@file{.storeccp} to the source file name.
+
+@item pre
+@opindex fdump-tree-pre
+Dump trees after partial redundancy elimination. The file name is made
+by appending @file{.pre} to the source file name.
+
+@item fre
+@opindex fdump-tree-fre
+Dump trees after full redundancy elimination. The file name is made
+by appending @file{.fre} to the source file name.
+
+@item copyprop
+@opindex fdump-tree-copyprop
+Dump trees after copy propagation. The file name is made
+by appending @file{.copyprop} to the source file name.
+
+@item store_copyprop
+@opindex fdump-tree-store_copyprop
+Dump trees after store copy-propagation. The file name is made
+by appending @file{.store_copyprop} to the source file name.
+
+@item dce
+@opindex fdump-tree-dce
+Dump each function after dead code elimination. The file name is made by
+appending @file{.dce} to the source file name.
+
+@item sra
+@opindex fdump-tree-sra
+Dump each function after performing scalar replacement of aggregates. The
+file name is made by appending @file{.sra} to the source file name.
+
+@item sink
+@opindex fdump-tree-sink
+Dump each function after performing code sinking. The file name is made
+by appending @file{.sink} to the source file name.
+
+@item dom
+@opindex fdump-tree-dom
+Dump each function after applying dominator tree optimizations. The file
+name is made by appending @file{.dom} to the source file name.
+
+@item dse
+@opindex fdump-tree-dse
+Dump each function after applying dead store elimination. The file
+name is made by appending @file{.dse} to the source file name.
+
+@item phiopt
+@opindex fdump-tree-phiopt
+Dump each function after optimizing PHI nodes into straightline code. The file
+name is made by appending @file{.phiopt} to the source file name.
+
+@item backprop
+@opindex fdump-tree-backprop
+Dump each function after back-propagating use information up the definition
+chain. The file name is made by appending @file{.backprop} to the
+source file name.
+
+@item forwprop
+@opindex fdump-tree-forwprop
+Dump each function after forward propagating single use variables. The file
+name is made by appending @file{.forwprop} to the source file name.
+
+@item nrv
+@opindex fdump-tree-nrv
+Dump each function after applying the named return value optimization on
+generic trees. The file name is made by appending @file{.nrv} to the source
+file name.
+
+@item vect
+@opindex fdump-tree-vect
+Dump each function after applying vectorization of loops. The file name is
+made by appending @file{.vect} to the source file name.
+
+@item slp
+@opindex fdump-tree-slp
+Dump each function after applying vectorization of basic blocks. The file name
+is made by appending @file{.slp} to the source file name.
+
+@item vrp
+@opindex fdump-tree-vrp
+Dump each function after Value Range Propagation (VRP). The file name
+is made by appending @file{.vrp} to the source file name.
+
+@item oaccdevlow
+@opindex fdump-tree-oaccdevlow
+Dump each function after applying device-specific OpenACC transformations.
+The file name is made by appending @file{.oaccdevlow} to the source file name.
+
+@item all
+@opindex fdump-tree-all
+Enable all the available tree dumps with the flags provided in this option.
+@end table
+
+@item -fopt-info
+@itemx -fopt-info-@var{options}
+@itemx -fopt-info-@var{options}=@var{filename}
+@opindex fopt-info
+Controls optimization dumps from various optimization passes. If the
+@samp{-@var{options}} form is used, @var{options} is a list of
+@samp{-} separated option keywords to select the dump details and
+optimizations.
+
+The @var{options} can be divided into two groups: options describing the
+verbosity of the dump, and options describing which optimizations
+should be included. The options from both the groups can be freely
+mixed as they are non-overlapping. However, in case of any conflicts,
+the later options override the earlier options on the command
+line.
+
+The following options control the dump verbosity:
+
+@table @samp
+@item optimized
+Print information when an optimization is successfully applied. It is
+up to a pass to decide which information is relevant. For example, the
+vectorizer passes print the source location of loops which are
+successfully vectorized.
+@item missed
+Print information about missed optimizations. Individual passes
+control which information to include in the output.
+@item note
+Print verbose information about optimizations, such as certain
+transformations, more detailed messages about decisions etc.
+@item all
+Print detailed optimization information. This includes
+@samp{optimized}, @samp{missed}, and @samp{note}.
+@end table
+
+One or more of the following option keywords can be used to describe a
+group of optimizations:
+
+@table @samp
+@item ipa
+Enable dumps from all interprocedural optimizations.
+@item loop
+Enable dumps from all loop optimizations.
+@item inline
+Enable dumps from all inlining optimizations.
+@item vec
+Enable dumps from all vectorization optimizations.
+@item optall
+Enable dumps from all optimizations. This is a superset of
+the optimization groups listed above.
+@end table
+
+If @var{options} is
+omitted, it defaults to @samp{optimized-optall}, which means to dump all
+info about successful optimizations from all the passes.
+
+If the @var{filename} is provided, then the dumps from all the
+applicable optimizations are concatenated into the @var{filename}.
+Otherwise the dump is output onto @file{stderr}. Though multiple
+@option{-fopt-info} options are accepted, only one of them can include
+a @var{filename}. If other filenames are provided then all but the
+first such option are ignored.
+
+Note that the output @var{filename} is overwritten
+in case of multiple translation units. If a combined output from
+multiple translation units is desired, @file{stderr} should be used
+instead.
+
+In the following example, the optimization info is output to
+@file{stderr}:
+
+@smallexample
+gcc -O3 -fopt-info
+@end smallexample
+
+This example:
+@smallexample
+gcc -O3 -fopt-info-missed=missed.all
+@end smallexample
+
+@noindent
+outputs missed optimization report from all the passes into
+@file{missed.all}, and this one:
+
+@smallexample
+gcc -O2 -ftree-vectorize -fopt-info-vec-missed
+@end smallexample
+
+@noindent
+prints information about missed optimization opportunities from
+vectorization passes on @file{stderr}.
+Note that @option{-fopt-info-vec-missed} is equivalent to
+@option{-fopt-info-missed-vec}.
+
+As another example,
+@smallexample
+gcc -O3 -fopt-info-inline-optimized-missed=inline.txt
+@end smallexample
+
+@noindent
+outputs information about missed optimizations as well as
+optimized locations from all the inlining passes into
+@file{inline.txt}.
+
+Finally, consider:
+
+@smallexample
+gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt
+@end smallexample
+
+@noindent
+Here the two output filenames @file{vec.miss} and @file{loop.opt} are
+in conflict since only one output file is allowed. In this case, only
+the first option takes effect and the subsequent options are
+ignored. Thus only @file{vec.miss} is produced which contains
+dumps from the vectorizer about missed opportunities.
+
+@item -fsched-verbose=@var{n}
+@opindex fsched-verbose
+On targets that use instruction scheduling, this option controls the
+amount of debugging output the scheduler prints to the dump files.
+
+For @var{n} greater than zero, @option{-fsched-verbose} outputs the
+same information as @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2}.
+For @var{n} greater than one, it also output basic block probabilities,
+detailed ready list information and unit/insn info. For @var{n} greater
+than two, it includes RTL at abort point, control-flow and regions info.
+And for @var{n} over four, @option{-fsched-verbose} also includes
+dependence info.
+
+
+
+@item -fenable-@var{kind}-@var{pass}
+@itemx -fdisable-@var{kind}-@var{pass}=@var{range-list}
+@opindex fdisable-
+@opindex fenable-
+
+This is a set of options that are used to explicitly disable/enable
+optimization passes. These options are intended for use for debugging GCC.
+Compiler users should use regular options for enabling/disabling
+passes instead.
+
+@table @gcctabopt
+
+@item -fdisable-ipa-@var{pass}
+Disable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is
+statically invoked in the compiler multiple times, the pass name should be
+appended with a sequential number starting from 1.
+
+@item -fdisable-rtl-@var{pass}
+@itemx -fdisable-rtl-@var{pass}=@var{range-list}
+Disable RTL pass @var{pass}. @var{pass} is the pass name. If the same pass is
+statically invoked in the compiler multiple times, the pass name should be
+appended with a sequential number starting from 1. @var{range-list} is a
+comma-separated list of function ranges or assembler names. Each range is a number
+pair separated by a colon. The range is inclusive in both ends. If the range
+is trivial, the number pair can be simplified as a single number. If the
+function's call graph node's @var{uid} falls within one of the specified ranges,
+the @var{pass} is disabled for that function. The @var{uid} is shown in the
+function header of a dump file, and the pass names can be dumped by using
+option @option{-fdump-passes}.
+
+@item -fdisable-tree-@var{pass}
+@itemx -fdisable-tree-@var{pass}=@var{range-list}
+Disable tree pass @var{pass}. See @option{-fdisable-rtl} for the description of
+option arguments.
+
+@item -fenable-ipa-@var{pass}
+Enable IPA pass @var{pass}. @var{pass} is the pass name. If the same pass is
+statically invoked in the compiler multiple times, the pass name should be
+appended with a sequential number starting from 1.
+
+@item -fenable-rtl-@var{pass}
+@itemx -fenable-rtl-@var{pass}=@var{range-list}
+Enable RTL pass @var{pass}. See @option{-fdisable-rtl} for option argument
+description and examples.
+
+@item -fenable-tree-@var{pass}
+@itemx -fenable-tree-@var{pass}=@var{range-list}
+Enable tree pass @var{pass}. See @option{-fdisable-rtl} for the description
+of option arguments.
+
+@end table
+
+Here are some examples showing uses of these options.
+
+@smallexample
+
+# disable ccp1 for all functions
+ -fdisable-tree-ccp1
+# disable complete unroll for function whose cgraph node uid is 1
+ -fenable-tree-cunroll=1
+# disable gcse2 for functions at the following ranges [1,1],
+# [300,400], and [400,1000]
+# disable gcse2 for functions foo and foo2
+ -fdisable-rtl-gcse2=foo,foo2
+# disable early inlining
+ -fdisable-tree-einline
+# disable ipa inlining
+ -fdisable-ipa-inline
+# enable tree full unroll
+ -fenable-tree-unroll
+
+@end smallexample
+
+@item -fchecking
+@opindex fchecking
+@opindex fno-checking
+Enable internal consistency checking. The default depends on
+the compiler configuration.
+
+@item -frandom-seed=@var{string}
+@opindex frandom-seed
+This option provides a seed that GCC uses in place of
+random numbers in generating certain symbol names
+that have to be different in every compiled file. It is also used to
+place unique stamps in coverage data files and the object files that
+produce them. You can use the @option{-frandom-seed} option to produce
+reproducibly identical object files.
+
+The @var{string} can either be a number (decimal, octal or hex) or an
+arbitrary string (in which case it's converted to a number by
+computing CRC32).
+
+The @var{string} should be different for every file you compile.
+
+@item -save-temps
+@itemx -save-temps=cwd
+@opindex save-temps
+Store the usual ``temporary'' intermediate files permanently; place them
+in the current directory and name them based on the source file. Thus,
+compiling @file{foo.c} with @option{-c -save-temps} produces files
+@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
+preprocessed @file{foo.i} output file even though the compiler now
+normally uses an integrated preprocessor.
+
+When used in combination with the @option{-x} command-line option,
+@option{-save-temps} is sensible enough to avoid over writing an
+input source file with the same extension as an intermediate file.
+The corresponding intermediate file may be obtained by renaming the
+source file before using @option{-save-temps}.
+
+If you invoke GCC in parallel, compiling several different source
+files that share a common base name in different subdirectories or the
+same source file compiled for multiple output destinations, it is
+likely that the different parallel compilers will interfere with each
+other, and overwrite the temporary files. For instance:
+
+@smallexample
+gcc -save-temps -o outdir1/foo.o indir1/foo.c&
+gcc -save-temps -o outdir2/foo.o indir2/foo.c&
+@end smallexample
+
+may result in @file{foo.i} and @file{foo.o} being written to
+simultaneously by both compilers.
+
+@item -save-temps=obj
+@opindex save-temps=obj
+Store the usual ``temporary'' intermediate files permanently. If the
+@option{-o} option is used, the temporary files are based on the
+object file. If the @option{-o} option is not used, the
+@option{-save-temps=obj} switch behaves like @option{-save-temps}.
+
+For example:
+
+@smallexample
+gcc -save-temps=obj -c foo.c
+gcc -save-temps=obj -c bar.c -o dir/xbar.o
+gcc -save-temps=obj foobar.c -o dir2/yfoobar
+@end smallexample
+
+@noindent
+creates @file{foo.i}, @file{foo.s}, @file{dir/xbar.i},
+@file{dir/xbar.s}, @file{dir2/yfoobar.i}, @file{dir2/yfoobar.s}, and
+@file{dir2/yfoobar.o}.
+
+@item -time@r{[}=@var{file}@r{]}
+@opindex time
+Report the CPU time taken by each subprocess in the compilation
+sequence. For C source files, this is the compiler proper and assembler
+(plus the linker if linking is done).
+
+Without the specification of an output file, the output looks like this:
+
+@smallexample
+# cc1 0.12 0.01
+# as 0.00 0.01
+@end smallexample
+
+The first number on each line is the ``user time'', that is time spent
+executing the program itself. The second number is ``system time'',
+time spent executing operating system routines on behalf of the program.
+Both numbers are in seconds.
+
+With the specification of an output file, the output is appended to the
+named file, and it looks like this:
+
+@smallexample
+0.12 0.01 cc1 @var{options}
+0.00 0.01 as @var{options}
+@end smallexample
+
+The ``user time'' and the ``system time'' are moved before the program
+name, and the options passed to the program are displayed, so that one
+can later tell what file was being compiled, and with which options.
+
+@item -fdump-final-insns@r{[}=@var{file}@r{]}
+@opindex fdump-final-insns
+Dump the final internal representation (RTL) to @var{file}. If the
+optional argument is omitted (or if @var{file} is @code{.}), the name
+of the dump file is determined by appending @code{.gkd} to the
+compilation output file name.
+
+@item -fcompare-debug@r{[}=@var{opts}@r{]}
+@opindex fcompare-debug
+@opindex fno-compare-debug
+If no error occurs during compilation, run the compiler a second time,
+adding @var{opts} and @option{-fcompare-debug-second} to the arguments
+passed to the second compilation. Dump the final internal
+representation in both compilations, and print an error if they differ.
+
+If the equal sign is omitted, the default @option{-gtoggle} is used.
+
+The environment variable @env{GCC_COMPARE_DEBUG}, if defined, non-empty
+and nonzero, implicitly enables @option{-fcompare-debug}. If
+@env{GCC_COMPARE_DEBUG} is defined to a string starting with a dash,
+then it is used for @var{opts}, otherwise the default @option{-gtoggle}
+is used.
+
+@option{-fcompare-debug=}, with the equal sign but without @var{opts},
+is equivalent to @option{-fno-compare-debug}, which disables the dumping
+of the final representation and the second compilation, preventing even
+@env{GCC_COMPARE_DEBUG} from taking effect.
+
+To verify full coverage during @option{-fcompare-debug} testing, set
+@env{GCC_COMPARE_DEBUG} to say @option{-fcompare-debug-not-overridden},
+which GCC rejects as an invalid option in any actual compilation
+(rather than preprocessing, assembly or linking). To get just a
+warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug
+not overridden} will do.
+
+@item -fcompare-debug-second
+@opindex fcompare-debug-second
+This option is implicitly passed to the compiler for the second
+compilation requested by @option{-fcompare-debug}, along with options to
+silence warnings, and omitting other options that would cause
+side-effect compiler outputs to files or to the standard output. Dump
+files and preserved temporary files are renamed so as to contain the
+@code{.gk} additional extension during the second compilation, to avoid
+overwriting those generated by the first.
+
+When this option is passed to the compiler driver, it causes the
+@emph{first} compilation to be skipped, which makes it useful for little
+other than debugging the compiler proper.
+
+@item -gtoggle
+@opindex gtoggle
+Turn off generation of debug info, if leaving out this option
+generates it, or turn it on at level 2 otherwise. The position of this
+argument in the command line does not matter; it takes effect after all
+other options are processed, and it does so only once, no matter how
+many times it is given. This is mainly intended to be used with
+@option{-fcompare-debug}.
+
+@item -fvar-tracking-assignments-toggle
+@opindex fvar-tracking-assignments-toggle
+@opindex fno-var-tracking-assignments-toggle
+Toggle @option{-fvar-tracking-assignments}, in the same way that
+@option{-gtoggle} toggles @option{-g}.
+
+@item -Q
+@opindex Q
+Makes the compiler print out each function name as it is compiled, and
+print some statistics about each pass when it finishes.
+
+@item -ftime-report
+@opindex ftime-report
+Makes the compiler print some statistics about the time consumed by each
+pass when it finishes.
+
+@item -fira-verbose=@var{n}
+@opindex fira-verbose
+Control the verbosity of the dump file for the integrated register allocator.
+The default value is 5. If the value @var{n} is greater or equal to 10,
+the dump output is sent to stderr using the same format as @var{n} minus 10.
+
+@item -flto-report
+@opindex flto-report
+Prints a report with internal details on the workings of the link-time
+optimizer. The contents of this report vary from version to version.
+It is meant to be useful to GCC developers when processing object
+files in LTO mode (via @option{-flto}).
+
+Disabled by default.
+
+@item -flto-report-wpa
+@opindex flto-report-wpa
+Like @option{-flto-report}, but only print for the WPA phase of Link
+Time Optimization.
+
+@item -fmem-report
+@opindex fmem-report
+Makes the compiler print some statistics about permanent memory
+allocation when it finishes.
+
+@item -fmem-report-wpa
+@opindex fmem-report-wpa
+Makes the compiler print some statistics about permanent memory
+allocation for the WPA phase only.
+
+@item -fpre-ipa-mem-report
+@opindex fpre-ipa-mem-report
+@item -fpost-ipa-mem-report
+@opindex fpost-ipa-mem-report
+Makes the compiler print some statistics about permanent memory
+allocation before or after interprocedural optimization.
+
+@item -fprofile-report
+@opindex fprofile-report
+Makes the compiler print some statistics about consistency of the
+(estimated) profile and effect of individual passes.
+
+@item -fstack-usage
+@opindex fstack-usage
+Makes the compiler output stack usage information for the program, on a
+per-function basis. The filename for the dump is made by appending
+@file{.su} to the @var{auxname}. @var{auxname} is generated from the name of
+the output file, if explicitly specified and it is not an executable,
+otherwise it is the basename of the source file. An entry is made up
+of three fields:
+
+@itemize
+@item
+The name of the function.
+@item
+A number of bytes.
+@item
+One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}.
+@end itemize
+
+The qualifier @code{static} means that the function manipulates the stack
+statically: a fixed number of bytes are allocated for the frame on function
+entry and released on function exit; no stack adjustments are otherwise made
+in the function. The second field is this fixed number of bytes.
+
+The qualifier @code{dynamic} means that the function manipulates the stack
+dynamically: in addition to the static allocation described above, stack
+adjustments are made in the body of the function, for example to push/pop
+arguments around function calls. If the qualifier @code{bounded} is also
+present, the amount of these adjustments is bounded at compile time and
+the second field is an upper bound of the total amount of stack used by
+the function. If it is not present, the amount of these adjustments is
+not bounded at compile time and the second field only represents the
+bounded part.
+
+@item -fstats
+@opindex fstats
+Emit statistics about front-end processing at the end of the compilation.
+This option is supported only by the C++ front end, and
+the information is generally only useful to the G++ development team.
+
+@item -fdbg-cnt-list
+@opindex fdbg-cnt-list
+Print the name and the counter upper bound for all debug counters.
+
+
+@item -fdbg-cnt=@var{counter-value-list}
+@opindex fdbg-cnt
+Set the internal debug counter upper bound. @var{counter-value-list}
+is a comma-separated list of @var{name}:@var{value} pairs
+which sets the upper bound of each debug counter @var{name} to @var{value}.
+All debug counters have the initial upper bound of @code{UINT_MAX};
+thus @code{dbg_cnt} returns true always unless the upper bound
+is set by this option.
+For example, with @option{-fdbg-cnt=dce:10,tail_call:0},
+@code{dbg_cnt(dce)} returns true only for first 10 invocations.
+
+@item -print-file-name=@var{library}
+@opindex print-file-name
+Print the full absolute name of the library file @var{library} that
+would be used when linking---and don't do anything else. With this
+option, GCC does not compile or link anything; it just prints the
+file name.
+
+@item -print-multi-directory
+@opindex print-multi-directory
+Print the directory name corresponding to the multilib selected by any
+other switches present in the command line. This directory is supposed
+to exist in @env{GCC_EXEC_PREFIX}.
+
+@item -print-multi-lib
+@opindex print-multi-lib
+Print the mapping from multilib directory names to compiler switches
+that enable them. The directory name is separated from the switches by
+@samp{;}, and each switch starts with an @samp{@@} instead of the
+@samp{-}, without spaces between multiple switches. This is supposed to
+ease shell processing.
+
+@item -print-multi-os-directory
+@opindex print-multi-os-directory
+Print the path to OS libraries for the selected
+multilib, relative to some @file{lib} subdirectory. If OS libraries are
+present in the @file{lib} subdirectory and no multilibs are used, this is
+usually just @file{.}, if OS libraries are present in @file{lib@var{suffix}}
+sibling directories this prints e.g.@: @file{../lib64}, @file{../lib} or
+@file{../lib32}, or if OS libraries are present in @file{lib/@var{subdir}}
+subdirectories it prints e.g.@: @file{amd64}, @file{sparcv9} or @file{ev6}.
+
+@item -print-multiarch
+@opindex print-multiarch
+Print the path to OS libraries for the selected multiarch,
+relative to some @file{lib} subdirectory.
+
+@item -print-prog-name=@var{program}
+@opindex print-prog-name
+Like @option{-print-file-name}, but searches for a program such as @command{cpp}.
+
+@item -print-libgcc-file-name
+@opindex print-libgcc-file-name
+Same as @option{-print-file-name=libgcc.a}.
+
+This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
+but you do want to link with @file{libgcc.a}. You can do:
+
+@smallexample
+gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
+@end smallexample
+
+@item -print-search-dirs
+@opindex print-search-dirs
+Print the name of the configured installation directory and a list of
+program and library directories @command{gcc} searches---and don't do anything else.
+
+This is useful when @command{gcc} prints the error message
+@samp{installation problem, cannot exec cpp0: No such file or directory}.
+To resolve this you either need to put @file{cpp0} and the other compiler
+components where @command{gcc} expects to find them, or you can set the environment
+variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
+Don't forget the trailing @samp{/}.
+@xref{Environment Variables}.
+
+@item -print-sysroot
+@opindex print-sysroot
+Print the target sysroot directory that is used during
+compilation. This is the target sysroot specified either at configure
+time or using the @option{--sysroot} option, possibly with an extra
+suffix that depends on compilation options. If no target sysroot is
+specified, the option prints nothing.
+
+@item -print-sysroot-headers-suffix
+@opindex print-sysroot-headers-suffix
+Print the suffix added to the target sysroot when searching for
+headers, or give an error if the compiler is not configured with such
+a suffix---and don't do anything else.
+
+@item -dumpmachine
+@opindex dumpmachine
+Print the compiler's target machine (for example,
+@samp{i686-pc-linux-gnu})---and don't do anything else.
+
+@item -dumpversion
+@opindex dumpversion
+Print the compiler version (for example, @code{3.0})---and don't do
+anything else.
+
+@item -dumpspecs
+@opindex dumpspecs
+Print the compiler's built-in specs---and don't do anything else. (This
+is used when GCC itself is being built.) @xref{Spec Files}.
+@end table
+
@node Submodel Options
@section Machine-Dependent Options
@cindex submodel options
Index: gcc/doc/cppopts.texi
===================================================================
--- gcc/doc/cppopts.texi (revision 232474)
+++ gcc/doc/cppopts.texi (working copy)
@@ -710,7 +710,7 @@ will show all the predefined macros.
If you use @option{-dM} without the @option{-E} option, @option{-dM} is
interpreted as a synonym for @option{-fdump-rtl-mach}.
-@xref{Debugging Options, , ,gcc}.
+@xref{Developer Options, , ,gcc}.
@item D
@opindex dD
^ permalink raw reply [flat|nested] 12+ messages in thread