You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1438 lines
104 KiB
HTML
1438 lines
104 KiB
HTML
<html lang="en">
|
|
<head>
|
|
<title>Debugging Options - Using the GNU Compiler Collection (GCC)</title>
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
<meta name="description" content="Using the GNU Compiler Collection (GCC)">
|
|
<meta name="generator" content="makeinfo 4.13">
|
|
<link title="Top" rel="start" href="index.html#Top">
|
|
<link rel="up" href="Invoking-GCC.html#Invoking-GCC" title="Invoking GCC">
|
|
<link rel="prev" href="Warning-Options.html#Warning-Options" title="Warning Options">
|
|
<link rel="next" href="Optimize-Options.html#Optimize-Options" title="Optimize Options">
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
|
<!--
|
|
Copyright (C) 1988-2015 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with the
|
|
Invariant Sections being ``Funding Free Software'', the Front-Cover
|
|
Texts being (a) (see below), and with the Back-Cover Texts being (b)
|
|
(see below). A copy of the license is included in the section entitled
|
|
``GNU Free Documentation License''.
|
|
|
|
(a) The FSF's Front-Cover Text is:
|
|
|
|
A GNU Manual
|
|
|
|
(b) The FSF's Back-Cover Text is:
|
|
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
|
software. Copies published by the Free Software Foundation raise
|
|
funds for GNU development.-->
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
|
<style type="text/css"><!--
|
|
pre.display { font-family:inherit }
|
|
pre.format { font-family:inherit }
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
|
pre.smallexample { font-size:smaller }
|
|
pre.smalllisp { font-size:smaller }
|
|
span.sc { font-variant:small-caps }
|
|
span.roman { font-family:serif; font-weight:normal; }
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
<div class="node">
|
|
<a name="Debugging-Options"></a>
|
|
<p>
|
|
Next: <a rel="next" accesskey="n" href="Optimize-Options.html#Optimize-Options">Optimize Options</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="Warning-Options.html#Warning-Options">Warning Options</a>,
|
|
Up: <a rel="up" accesskey="u" href="Invoking-GCC.html#Invoking-GCC">Invoking GCC</a>
|
|
<hr>
|
|
</div>
|
|
|
|
<h3 class="section">3.9 Options for Debugging Your Program or GCC</h3>
|
|
|
|
<p><a name="index-options_002c-debugging-624"></a><a name="index-debugging-information-options-625"></a>
|
|
GCC has various special options that are used for debugging
|
|
either your program or GCC:
|
|
|
|
<dl>
|
|
<dt><code>-g</code><dd><a name="index-g-626"></a>Produce debugging information in the operating system's native format
|
|
(stabs, COFF, XCOFF, or DWARF 2). GDB can work with this debugging
|
|
information.
|
|
|
|
<p>On most systems that use stabs format, <samp><span class="option">-g</span></samp> enables use of extra
|
|
debugging information that only GDB can use; this extra information
|
|
makes debugging work better in GDB but probably makes other debuggers
|
|
crash or
|
|
refuse to read the program. If you want to control for certain whether
|
|
to generate the extra information, use <samp><span class="option">-gstabs+</span></samp>, <samp><span class="option">-gstabs</span></samp>,
|
|
<samp><span class="option">-gxcoff+</span></samp>, <samp><span class="option">-gxcoff</span></samp>, or <samp><span class="option">-gvms</span></samp> (see below).
|
|
|
|
<p>GCC allows you to use <samp><span class="option">-g</span></samp> with
|
|
<samp><span class="option">-O</span></samp>. 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.
|
|
|
|
<p>Nevertheless it proves possible to debug optimized output. This makes
|
|
it reasonable to use the optimizer for programs that might have bugs.
|
|
|
|
<p>The following options are useful when GCC is generated with the
|
|
capability for more than one debugging format.
|
|
|
|
<br><dt><code>-gsplit-dwarf</code><dd><a name="index-gsplit_002ddwarf-627"></a>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.
|
|
|
|
<br><dt><code>-ggdb</code><dd><a name="index-ggdb-628"></a>Produce debugging information for use by GDB. This means to use the
|
|
most expressive format available (DWARF 2, stabs, or the native format
|
|
if neither of those are supported), including GDB extensions if at all
|
|
possible.
|
|
|
|
<br><dt><code>-gpubnames</code><dd><a name="index-gpubnames-629"></a>Generate dwarf .debug_pubnames and .debug_pubtypes sections.
|
|
|
|
<br><dt><code>-ggnu-pubnames</code><dd><a name="index-ggnu_002dpubnames-630"></a>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.
|
|
|
|
<br><dt><code>-gstabs</code><dd><a name="index-gstabs-631"></a>Produce debugging information in stabs format (if that is supported),
|
|
without GDB extensions. This is the format used by DBX on most BSD
|
|
systems. On MIPS, Alpha and System V Release 4 systems this option
|
|
produces stabs debugging output that is not understood by DBX or SDB.
|
|
On System V Release 4 systems this option requires the GNU assembler.
|
|
|
|
<br><dt><code>-feliminate-unused-debug-symbols</code><dd><a name="index-feliminate_002dunused_002ddebug_002dsymbols-632"></a>Produce debugging information in stabs format (if that is supported),
|
|
for only symbols that are actually used.
|
|
|
|
<br><dt><code>-femit-class-debug-always</code><dd><a name="index-femit_002dclass_002ddebug_002dalways-633"></a>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.
|
|
|
|
<br><dt><code>-fdebug-types-section</code><dd><a name="index-fdebug_002dtypes_002dsection-634"></a><a name="index-fno_002ddebug_002dtypes_002dsection-635"></a>When using DWARF Version 4 or higher, type DIEs can be put into
|
|
their own <code>.debug_types</code> section instead of making them part of the
|
|
<code>.debug_info</code> 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</code> sections yet
|
|
and on some objects <code>.debug_types</code> produces larger instead of smaller
|
|
debugging information.
|
|
|
|
<br><dt><code>-gstabs+</code><dd><a name="index-gstabs_002b-636"></a>Produce debugging information in stabs format (if that is supported),
|
|
using GNU extensions understood only by the GNU debugger (GDB). The
|
|
use of these extensions is likely to make other debuggers crash or
|
|
refuse to read the program.
|
|
|
|
<br><dt><code>-gcoff</code><dd><a name="index-gcoff-637"></a>Produce debugging information in COFF format (if that is supported).
|
|
This is the format used by SDB on most System V systems prior to
|
|
System V Release 4.
|
|
|
|
<br><dt><code>-gxcoff</code><dd><a name="index-gxcoff-638"></a>Produce debugging information in XCOFF format (if that is supported).
|
|
This is the format used by the DBX debugger on IBM RS/6000 systems.
|
|
|
|
<br><dt><code>-gxcoff+</code><dd><a name="index-gxcoff_002b-639"></a>Produce debugging information in XCOFF format (if that is supported),
|
|
using GNU extensions understood only by the GNU debugger (GDB). The
|
|
use of these extensions is likely to make other debuggers crash or
|
|
refuse to read the program, and may cause assemblers other than the GNU
|
|
assembler (GAS) to fail with an error.
|
|
|
|
<br><dt><code>-gdwarf-</code><var>version</var><dd><a name="index-gdwarf_002d_0040var_007bversion_007d-640"></a>Produce debugging information in DWARF format (if that is supported).
|
|
The value of <var>version</var> may be either 2, 3, 4 or 5; the default version
|
|
for most targets is 4. DWARF Version 5 is only experimental.
|
|
|
|
<p>Note that with DWARF Version 2, some ports require and always
|
|
use some non-conflicting DWARF 3 extensions in the unwind tables.
|
|
|
|
<p>Version 4 may require GDB 7.0 and <samp><span class="option">-fvar-tracking-assignments</span></samp>
|
|
for maximum benefit.
|
|
|
|
<br><dt><code>-grecord-gcc-switches</code><dd><a name="index-grecord_002dgcc_002dswitches-641"></a>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 <samp><span class="option">-frecord-gcc-switches</span></samp> for another
|
|
way of storing compiler options into the object file. This is the default.
|
|
|
|
<br><dt><code>-gno-record-gcc-switches</code><dd><a name="index-gno_002drecord_002dgcc_002dswitches-642"></a>Disallow appending command-line options to the DW_AT_producer attribute
|
|
in DWARF debugging information.
|
|
|
|
<br><dt><code>-gstrict-dwarf</code><dd><a name="index-gstrict_002ddwarf-643"></a>Disallow using extensions of later DWARF standard version than selected
|
|
with <samp><span class="option">-gdwarf-</span><var>version</var></samp>. On most targets using non-conflicting
|
|
DWARF extensions from later standard versions is allowed.
|
|
|
|
<br><dt><code>-gno-strict-dwarf</code><dd><a name="index-gno_002dstrict_002ddwarf-644"></a>Allow using extensions of later DWARF standard version than selected with
|
|
<samp><span class="option">-gdwarf-</span><var>version</var></samp>.
|
|
|
|
<br><dt><code>-gz</code><span class="roman">[</span><code>=</code><var>type</var><span class="roman">]</span><dd><a name="index-gz-645"></a>Produce compressed debug sections in DWARF format, if that is supported.
|
|
If <var>type</var> is not given, the default type depends on the capabilities
|
|
of the assembler and linker used. <var>type</var> may be one of
|
|
‘<samp><span class="samp">none</span></samp>’ (don't compress debug sections), ‘<samp><span class="samp">zlib</span></samp>’ (use zlib
|
|
compression in ELF gABI format), or ‘<samp><span class="samp">zlib-gnu</span></samp>’ (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, <samp><span class="option">-gz</span></samp> is silently ignored
|
|
when producing object files.
|
|
|
|
<br><dt><code>-gvms</code><dd><a name="index-gvms-646"></a>Produce debugging information in Alpha/VMS debug format (if that is
|
|
supported). This is the format used by DEBUG on Alpha/VMS systems.
|
|
|
|
<br><dt><code>-g</code><var>level</var><dt><code>-ggdb</code><var>level</var><dt><code>-gstabs</code><var>level</var><dt><code>-gcoff</code><var>level</var><dt><code>-gxcoff</code><var>level</var><dt><code>-gvms</code><var>level</var><dd>Request debugging information and also use <var>level</var> to specify how
|
|
much information. The default level is 2.
|
|
|
|
<p>Level 0 produces no debug information at all. Thus, <samp><span class="option">-g0</span></samp> negates
|
|
<samp><span class="option">-g</span></samp>.
|
|
|
|
<p>Level 1 produces minimal information, enough for making backtraces in
|
|
parts of the program that you don't plan to debug. This includes
|
|
descriptions of functions and external variables, and line number
|
|
tables, but no information about local variables.
|
|
|
|
<p>Level 3 includes extra information, such as all the macro definitions
|
|
present in the program. Some debuggers support macro expansion when
|
|
you use <samp><span class="option">-g3</span></samp>.
|
|
|
|
<p><samp><span class="option">-gdwarf-2</span></samp> does not accept a concatenated debug level, because
|
|
GCC used to support an option <samp><span class="option">-gdwarf</span></samp> that meant to generate
|
|
debug information in version 1 of the DWARF format (which is very
|
|
different from version 2), and it would have been too confusing. That
|
|
debug format is long obsolete, but the option cannot be changed now.
|
|
Instead use an additional <samp><span class="option">-g</span><var>level</var></samp> option to change the
|
|
debug level for DWARF.
|
|
|
|
<br><dt><code>-gtoggle</code><dd><a name="index-gtoggle-647"></a>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
|
|
<samp><span class="option">-fcompare-debug</span></samp>.
|
|
|
|
<br><dt><code>-fsanitize=address</code><dd><a name="index-fsanitize_003daddress-648"></a>Enable AddressSanitizer, a fast memory error detector.
|
|
Memory access instructions are instrumented to detect
|
|
out-of-bounds and use-after-free bugs.
|
|
See <a href="https://github.com/google/sanitizers/wiki/AddressSanitizer">https://github.com/google/sanitizers/wiki/AddressSanitizer</a> for
|
|
more details. The run-time behavior can be influenced using the
|
|
<samp><span class="env">ASAN_OPTIONS</span></samp> environment variable. When set to <code>help=1</code>,
|
|
the available options are shown at startup of the instrumended program. See
|
|
<a href="https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags">https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags</a>
|
|
for a list of supported options.
|
|
|
|
<br><dt><code>-fsanitize=kernel-address</code><dd><a name="index-fsanitize_003dkernel_002daddress-649"></a>Enable AddressSanitizer for Linux kernel.
|
|
See <a href="https://github.com/google/kasan/wiki">https://github.com/google/kasan/wiki</a> for more details.
|
|
|
|
<br><dt><code>-fsanitize=thread</code><dd><a name="index-fsanitize_003dthread-650"></a>Enable ThreadSanitizer, a fast data race detector.
|
|
Memory access instructions are instrumented to detect
|
|
data race bugs. See <a href="https://github.com/google/sanitizers/wiki#threadsanitizer">https://github.com/google/sanitizers/wiki#threadsanitizer</a> for more
|
|
details. The run-time behavior can be influenced using the <samp><span class="env">TSAN_OPTIONS</span></samp>
|
|
environment variable; see
|
|
<a href="https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags">https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags</a> for a list of
|
|
supported options.
|
|
|
|
<br><dt><code>-fsanitize=leak</code><dd><a name="index-fsanitize_003dleak-651"></a>Enable LeakSanitizer, a memory leak detector.
|
|
This option only matters for linking of executables and if neither
|
|
<samp><span class="option">-fsanitize=address</span></samp> nor <samp><span class="option">-fsanitize=thread</span></samp> is used. In that
|
|
case the executable is linked against a library that overrides <code>malloc</code>
|
|
and other allocator functions. See
|
|
<a href="https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer">https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer</a> for more
|
|
details. The run-time behavior can be influenced using the
|
|
<samp><span class="env">LSAN_OPTIONS</span></samp> environment variable.
|
|
|
|
<br><dt><code>-fsanitize=undefined</code><dd><a name="index-fsanitize_003dundefined-652"></a>Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector.
|
|
Various computations are instrumented to detect undefined behavior
|
|
at runtime. Current suboptions are:
|
|
|
|
<dl>
|
|
<dt><code>-fsanitize=shift</code><dd><a name="index-fsanitize_003dshift-653"></a>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.
|
|
|
|
<br><dt><code>-fsanitize=integer-divide-by-zero</code><dd><a name="index-fsanitize_003dinteger_002ddivide_002dby_002dzero-654"></a>Detect integer division by zero as well as <code>INT_MIN / -1</code> division.
|
|
|
|
<br><dt><code>-fsanitize=unreachable</code><dd><a name="index-fsanitize_003dunreachable-655"></a>With this option, the compiler turns the <code>__builtin_unreachable</code>
|
|
call into a diagnostics message call instead. When reaching the
|
|
<code>__builtin_unreachable</code> call, the behavior is undefined.
|
|
|
|
<br><dt><code>-fsanitize=vla-bound</code><dd><a name="index-fsanitize_003dvla_002dbound-656"></a>This option instructs the compiler to check that the size of a variable
|
|
length array is positive.
|
|
|
|
<br><dt><code>-fsanitize=null</code><dd><a name="index-fsanitize_003dnull-657"></a>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.
|
|
|
|
<br><dt><code>-fsanitize=return</code><dd><a name="index-fsanitize_003dreturn-658"></a>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.
|
|
|
|
<br><dt><code>-fsanitize=signed-integer-overflow</code><dd><a name="index-fsanitize_003dsigned_002dinteger_002doverflow-659"></a>This option enables signed integer overflow checking. We check that
|
|
the result of <code>+</code>, <code>*</code>, and both unary and binary <code>-</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:
|
|
<pre class="smallexample"> signed char a = SCHAR_MAX;
|
|
a++;
|
|
</pre>
|
|
<br><dt><code>-fsanitize=bounds</code><dd><a name="index-fsanitize_003dbounds-660"></a>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.
|
|
|
|
<br><dt><code>-fsanitize=alignment</code><dd><a name="index-fsanitize_003dalignment-661"></a>
|
|
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.
|
|
|
|
<br><dt><code>-fsanitize=object-size</code><dd><a name="index-fsanitize_003dobject_002dsize-662"></a>This option enables instrumentation of memory references using the
|
|
<code>__builtin_object_size</code> function. Various out of bounds pointer
|
|
accesses are detected.
|
|
|
|
<br><dt><code>-fsanitize=float-divide-by-zero</code><dd><a name="index-fsanitize_003dfloat_002ddivide_002dby_002dzero-663"></a>Detect floating-point division by zero. Unlike other similar options,
|
|
<samp><span class="option">-fsanitize=float-divide-by-zero</span></samp> is not enabled by
|
|
<samp><span class="option">-fsanitize=undefined</span></samp>, since floating-point division by zero can
|
|
be a legitimate way of obtaining infinities and NaNs.
|
|
|
|
<br><dt><code>-fsanitize=float-cast-overflow</code><dd><a name="index-fsanitize_003dfloat_002dcast_002doverflow-664"></a>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, <samp><span class="option">-fsanitize=float-cast-overflow</span></samp> is
|
|
not enabled by <samp><span class="option">-fsanitize=undefined</span></samp>.
|
|
This option does not work well with <code>FE_INVALID</code> exceptions enabled.
|
|
|
|
<br><dt><code>-fsanitize=nonnull-attribute</code><dd><a name="index-fsanitize_003dnonnull_002dattribute-665"></a>
|
|
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</code> function attribute.
|
|
|
|
<br><dt><code>-fsanitize=returns-nonnull-attribute</code><dd><a name="index-fsanitize_003dreturns_002dnonnull_002dattribute-666"></a>
|
|
This option enables instrumentation of return statements in functions
|
|
marked with <code>returns_nonnull</code> function attribute, to detect returning
|
|
of null values from such functions.
|
|
|
|
<br><dt><code>-fsanitize=bool</code><dd><a name="index-fsanitize_003dbool-667"></a>
|
|
This option enables instrumentation of loads from bool. If a value other
|
|
than 0/1 is loaded, a run-time error is issued.
|
|
|
|
<br><dt><code>-fsanitize=enum</code><dd><a name="index-fsanitize_003denum-668"></a>
|
|
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.
|
|
|
|
<br><dt><code>-fsanitize=vptr</code><dd><a name="index-fsanitize_003dvptr-669"></a>
|
|
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.
|
|
|
|
</dl>
|
|
|
|
<p>While <samp><span class="option">-ftrapv</span></samp> causes traps for signed overflows to be emitted,
|
|
<samp><span class="option">-fsanitize=undefined</span></samp> gives a diagnostic message.
|
|
This currently works only for the C family of languages.
|
|
|
|
<br><dt><code>-fno-sanitize=all</code><dd><a name="index-fno_002dsanitize_003dall-670"></a>
|
|
This option disables all previously enabled sanitizers.
|
|
<samp><span class="option">-fsanitize=all</span></samp> is not allowed, as some sanitizers cannot be used
|
|
together.
|
|
|
|
<br><dt><code>-fasan-shadow-offset=</code><var>number</var><dd><a name="index-fasan_002dshadow_002doffset-671"></a>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.
|
|
|
|
<br><dt><code>-fsanitize-recover</code><span class="roman">[</span><code>=</code><var>opts</var><span class="roman">]</span><dd><a name="index-fsanitize_002drecover-672"></a><a name="index-fno_002dsanitize_002drecover-673"></a><samp><span class="option">-fsanitize-recover=</span></samp> controls error recovery mode for sanitizers
|
|
mentioned in comma-separated list of <var>opts</var>. 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 <samp><span class="option">-fno-sanitize-recover=</span></samp> 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.
|
|
|
|
<p>Currently this feature only works for <samp><span class="option">-fsanitize=undefined</span></samp> (and its suboptions
|
|
except for <samp><span class="option">-fsanitize=unreachable</span></samp> and <samp><span class="option">-fsanitize=return</span></samp>),
|
|
<samp><span class="option">-fsanitize=float-cast-overflow</span></samp>, <samp><span class="option">-fsanitize=float-divide-by-zero</span></samp> and
|
|
<samp><span class="option">-fsanitize=kernel-address</span></samp>. For these sanitizers error recovery is turned on by default.
|
|
<samp><span class="option">-fsanitize-recover=all</span></samp> and <samp><span class="option">-fno-sanitize-recover=all</span></samp> is also
|
|
accepted, the former enables recovery for all sanitizers that support it,
|
|
the latter disables recovery for all sanitizers that support it.
|
|
|
|
<p>Syntax without explicit <var>opts</var> parameter is deprecated. It is equivalent to
|
|
<pre class="smallexample"> -fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero
|
|
</pre>
|
|
<p class="noindent">Similarly <samp><span class="option">-fno-sanitize-recover</span></samp> is equivalent to
|
|
<pre class="smallexample"> -fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero
|
|
</pre>
|
|
<br><dt><code>-fsanitize-undefined-trap-on-error</code><dd><a name="index-fsanitize_002dundefined_002dtrap_002don_002derror-674"></a>The <samp><span class="option">-fsanitize-undefined-trap-on-error</span></samp> option instructs the compiler to
|
|
report undefined behavior using <code>__builtin_trap</code> rather than
|
|
a <code>libubsan</code> library routine. The advantage of this is that the
|
|
<code>libubsan</code> library is not needed and is not linked in, so this
|
|
is usable even in freestanding environments.
|
|
|
|
<br><dt><code>-fcheck-pointer-bounds</code><dd><a name="index-fcheck_002dpointer_002dbounds-675"></a><a name="index-fno_002dcheck_002dpointer_002dbounds-676"></a><a name="index-Pointer-Bounds-Checker-options-677"></a>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.
|
|
|
|
<p>Currently there
|
|
is only an implementation for Intel MPX available, thus x86 target
|
|
and <samp><span class="option">-mmpx</span></samp> 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 <samp><span class="option">-fcheck-pointer-bounds</span></samp>
|
|
and <samp><span class="option">-mmpx</span></samp> options are used to link a program, the GCC driver
|
|
links against the <samp><span class="file">libmpx</span></samp> runtime library and <samp><span class="file">libmpxwrappers</span></samp>
|
|
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 <samp><span class="option">-static-libmpxwrappers</span></samp>
|
|
for better protection level or use <samp><span class="option">-static</span></samp> 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 <samp><span class="option">-lpthread</span></samp>. See
|
|
also <samp><span class="option">-static-libmpx</span></samp>. The runtime library behavior can be
|
|
influenced using various <samp><span class="env">CHKP_RT_*</span></samp> environment variables. See
|
|
<a href="https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler">https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler</a>
|
|
for more details.
|
|
|
|
<p>Generated instrumentation may be controlled by various
|
|
<samp><span class="option">-fchkp-*</span></samp> options and by the <code>bnd_variable_size</code>
|
|
structure field attribute (see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>) and
|
|
<code>bnd_legacy</code>, and <code>bnd_instrument</code> function attributes
|
|
(see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>). GCC also provides a number of built-in
|
|
functions for controlling the Pointer Bounds Checker. See <a href="Pointer-Bounds-Checker-builtins.html#Pointer-Bounds-Checker-builtins">Pointer Bounds Checker builtins</a>, for more information.
|
|
|
|
<br><dt><code>-fchkp-check-incomplete-type</code><dd><a name="index-fchkp_002dcheck_002dincomplete_002dtype-678"></a><a name="index-fno_002dchkp_002dcheck_002dincomplete_002dtype-679"></a>Generate pointer bounds checks for variables with incomplete type.
|
|
Enabled by default.
|
|
|
|
<br><dt><code>-fchkp-narrow-bounds</code><dd><a name="index-fchkp_002dnarrow_002dbounds-680"></a><a name="index-fno_002dchkp_002dnarrow_002dbounds-681"></a>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 <samp><span class="option">-fchkp-narrow-to-innermost-array</span></samp>
|
|
and <samp><span class="option">-fchkp-first-field-has-own-bounds</span></samp>. Enabled by default.
|
|
|
|
<br><dt><code>-fchkp-first-field-has-own-bounds</code><dd><a name="index-fchkp_002dfirst_002dfield_002dhas_002down_002dbounds-682"></a><a name="index-fno_002dchkp_002dfirst_002dfield_002dhas_002down_002dbounds-683"></a>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.
|
|
|
|
<br><dt><code>-fchkp-narrow-to-innermost-array</code><dd><a name="index-fchkp_002dnarrow_002dto_002dinnermost_002darray-684"></a><a name="index-fno_002dchkp_002dnarrow_002dto_002dinnermost_002darray-685"></a>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.
|
|
|
|
<br><dt><code>-fchkp-optimize</code><dd><a name="index-fchkp_002doptimize-686"></a><a name="index-fno_002dchkp_002doptimize-687"></a>Enables Pointer Bounds Checker optimizations. Enabled by default at
|
|
optimization levels <samp><span class="option">-O</span></samp>, <samp><span class="option">-O2</span></samp>, <samp><span class="option">-O3</span></samp>.
|
|
|
|
<br><dt><code>-fchkp-use-fast-string-functions</code><dd><a name="index-fchkp_002duse_002dfast_002dstring_002dfunctions-688"></a><a name="index-fno_002dchkp_002duse_002dfast_002dstring_002dfunctions-689"></a>Enables use of <code>*_nobnd</code> versions of string functions (not copying bounds)
|
|
by Pointer Bounds Checker. Disabled by default.
|
|
|
|
<br><dt><code>-fchkp-use-nochk-string-functions</code><dd><a name="index-fchkp_002duse_002dnochk_002dstring_002dfunctions-690"></a><a name="index-fno_002dchkp_002duse_002dnochk_002dstring_002dfunctions-691"></a>Enables use of <code>*_nochk</code> versions of string functions (not checking bounds)
|
|
by Pointer Bounds Checker. Disabled by default.
|
|
|
|
<br><dt><code>-fchkp-use-static-bounds</code><dd><a name="index-fchkp_002duse_002dstatic_002dbounds-692"></a><a name="index-fno_002dchkp_002duse_002dstatic_002dbounds-693"></a>Allow Pointer Bounds Checker to generate static bounds holding
|
|
bounds of static variables. Enabled by default.
|
|
|
|
<br><dt><code>-fchkp-use-static-const-bounds</code><dd><a name="index-fchkp_002duse_002dstatic_002dconst_002dbounds-694"></a><a name="index-fno_002dchkp_002duse_002dstatic_002dconst_002dbounds-695"></a>Use statically-initialized bounds for constant bounds instead of
|
|
generating them each time they are required. By default enabled when
|
|
<samp><span class="option">-fchkp-use-static-bounds</span></samp> is enabled.
|
|
|
|
<br><dt><code>-fchkp-treat-zero-dynamic-size-as-infinite</code><dd><a name="index-fchkp_002dtreat_002dzero_002ddynamic_002dsize_002das_002dinfinite-696"></a><a name="index-fno_002dchkp_002dtreat_002dzero_002ddynamic_002dsize_002das_002dinfinite-697"></a>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.
|
|
|
|
<br><dt><code>-fchkp-check-read</code><dd><a name="index-fchkp_002dcheck_002dread-698"></a><a name="index-fno_002dchkp_002dcheck_002dread-699"></a>Instructs Pointer Bounds Checker to generate checks for all read
|
|
accesses to memory. Enabled by default.
|
|
|
|
<br><dt><code>-fchkp-check-write</code><dd><a name="index-fchkp_002dcheck_002dwrite-700"></a><a name="index-fno_002dchkp_002dcheck_002dwrite-701"></a>Instructs Pointer Bounds Checker to generate checks for all write
|
|
accesses to memory. Enabled by default.
|
|
|
|
<br><dt><code>-fchkp-store-bounds</code><dd><a name="index-fchkp_002dstore_002dbounds-702"></a><a name="index-fno_002dchkp_002dstore_002dbounds-703"></a>Instructs Pointer Bounds Checker to generate bounds stores for
|
|
pointer writes. Enabled by default.
|
|
|
|
<br><dt><code>-fchkp-instrument-calls</code><dd><a name="index-fchkp_002dinstrument_002dcalls-704"></a><a name="index-fno_002dchkp_002dinstrument_002dcalls-705"></a>Instructs Pointer Bounds Checker to pass pointer bounds to calls.
|
|
Enabled by default.
|
|
|
|
<br><dt><code>-fchkp-instrument-marked-only</code><dd><a name="index-fchkp_002dinstrument_002dmarked_002donly-706"></a><a name="index-fno_002dchkp_002dinstrument_002dmarked_002donly-707"></a>Instructs Pointer Bounds Checker to instrument only functions
|
|
marked with the <code>bnd_instrument</code> attribute
|
|
(see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>). Disabled by default.
|
|
|
|
<br><dt><code>-fchkp-use-wrappers</code><dd><a name="index-fchkp_002duse_002dwrappers-708"></a><a name="index-fno_002dchkp_002duse_002dwrappers-709"></a>Allows Pointer Bounds Checker to replace calls to built-in functions
|
|
with calls to wrapper functions. When <samp><span class="option">-fchkp-use-wrappers</span></samp>
|
|
is used to link a program, the GCC driver automatically links
|
|
against <samp><span class="file">libmpxwrappers</span></samp>. See also <samp><span class="option">-static-libmpxwrappers</span></samp>.
|
|
Enabled by default.
|
|
|
|
<br><dt><code>-fdump-final-insns</code><span class="roman">[</span><code>=</code><var>file</var><span class="roman">]</span><dd><a name="index-fdump_002dfinal_002dinsns-710"></a>Dump the final internal representation (RTL) to <var>file</var>. If the
|
|
optional argument is omitted (or if <var>file</var> is <code>.</code>), the name
|
|
of the dump file is determined by appending <code>.gkd</code> to the
|
|
compilation output file name.
|
|
|
|
<br><dt><code>-fcompare-debug</code><span class="roman">[</span><code>=</code><var>opts</var><span class="roman">]</span><dd><a name="index-fcompare_002ddebug-711"></a><a name="index-fno_002dcompare_002ddebug-712"></a>If no error occurs during compilation, run the compiler a second time,
|
|
adding <var>opts</var> and <samp><span class="option">-fcompare-debug-second</span></samp> to the arguments
|
|
passed to the second compilation. Dump the final internal
|
|
representation in both compilations, and print an error if they differ.
|
|
|
|
<p>If the equal sign is omitted, the default <samp><span class="option">-gtoggle</span></samp> is used.
|
|
|
|
<p>The environment variable <samp><span class="env">GCC_COMPARE_DEBUG</span></samp>, if defined, non-empty
|
|
and nonzero, implicitly enables <samp><span class="option">-fcompare-debug</span></samp>. If
|
|
<samp><span class="env">GCC_COMPARE_DEBUG</span></samp> is defined to a string starting with a dash,
|
|
then it is used for <var>opts</var>, otherwise the default <samp><span class="option">-gtoggle</span></samp>
|
|
is used.
|
|
|
|
<p><samp><span class="option">-fcompare-debug=</span></samp>, with the equal sign but without <var>opts</var>,
|
|
is equivalent to <samp><span class="option">-fno-compare-debug</span></samp>, which disables the dumping
|
|
of the final representation and the second compilation, preventing even
|
|
<samp><span class="env">GCC_COMPARE_DEBUG</span></samp> from taking effect.
|
|
|
|
<p>To verify full coverage during <samp><span class="option">-fcompare-debug</span></samp> testing, set
|
|
<samp><span class="env">GCC_COMPARE_DEBUG</span></samp> to say <samp><span class="option">-fcompare-debug-not-overridden</span></samp>,
|
|
which GCC rejects as an invalid option in any actual compilation
|
|
(rather than preprocessing, assembly or linking). To get just a
|
|
warning, setting <samp><span class="env">GCC_COMPARE_DEBUG</span></samp> to ‘<samp><span class="samp">-w%n-fcompare-debug
|
|
not overridden</span></samp>’ will do.
|
|
|
|
<br><dt><code>-fcompare-debug-second</code><dd><a name="index-fcompare_002ddebug_002dsecond-713"></a>This option is implicitly passed to the compiler for the second
|
|
compilation requested by <samp><span class="option">-fcompare-debug</span></samp>, 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</code> additional extension during the second compilation, to avoid
|
|
overwriting those generated by the first.
|
|
|
|
<p>When this option is passed to the compiler driver, it causes the
|
|
<em>first</em> compilation to be skipped, which makes it useful for little
|
|
other than debugging the compiler proper.
|
|
|
|
<br><dt><code>-feliminate-dwarf2-dups</code><dd><a name="index-feliminate_002ddwarf2_002ddups-714"></a>Compress DWARF 2 debugging information by eliminating duplicated
|
|
information about each symbol. This option only makes sense when
|
|
generating DWARF 2 debugging information with <samp><span class="option">-gdwarf-2</span></samp>.
|
|
|
|
<br><dt><code>-femit-struct-debug-baseonly</code><dd><a name="index-femit_002dstruct_002ddebug_002dbaseonly-715"></a>Emit debug information for struct-like types
|
|
only when the base name of the compilation source file
|
|
matches the base name of file in which the struct is defined.
|
|
|
|
<p>This option substantially reduces the size of debugging information,
|
|
but at significant potential loss in type information to the debugger.
|
|
See <samp><span class="option">-femit-struct-debug-reduced</span></samp> for a less aggressive option.
|
|
See <samp><span class="option">-femit-struct-debug-detailed</span></samp> for more detailed control.
|
|
|
|
<p>This option works only with DWARF 2.
|
|
|
|
<br><dt><code>-femit-struct-debug-reduced</code><dd><a name="index-femit_002dstruct_002ddebug_002dreduced-716"></a>Emit debug information for struct-like types
|
|
only when the base name of the compilation source file
|
|
matches the base name of file in which the type is defined,
|
|
unless the struct is a template or defined in a system header.
|
|
|
|
<p>This option significantly reduces the size of debugging information,
|
|
with some potential loss in type information to the debugger.
|
|
See <samp><span class="option">-femit-struct-debug-baseonly</span></samp> for a more aggressive option.
|
|
See <samp><span class="option">-femit-struct-debug-detailed</span></samp> for more detailed control.
|
|
|
|
<p>This option works only with DWARF 2.
|
|
|
|
<br><dt><code>-femit-struct-debug-detailed</code><span class="roman">[</span><code>=</code><var>spec-list</var><span class="roman">]</span><dd><a name="index-femit_002dstruct_002ddebug_002ddetailed-717"></a>Specify the struct-like types
|
|
for which the compiler generates debug information.
|
|
The intent is to reduce duplicate struct debug information
|
|
between different object files within the same program.
|
|
|
|
<p>This option is a detailed version of
|
|
<samp><span class="option">-femit-struct-debug-reduced</span></samp> and <samp><span class="option">-femit-struct-debug-baseonly</span></samp>,
|
|
which serves for most needs.
|
|
|
|
<p>A specification has the syntax<br>
|
|
[‘<samp><span class="samp">dir:</span></samp>’|‘<samp><span class="samp">ind:</span></samp>’][‘<samp><span class="samp">ord:</span></samp>’|‘<samp><span class="samp">gen:</span></samp>’](‘<samp><span class="samp">any</span></samp>’|‘<samp><span class="samp">sys</span></samp>’|‘<samp><span class="samp">base</span></samp>’|‘<samp><span class="samp">none</span></samp>’)
|
|
|
|
<p>The optional first word limits the specification to
|
|
structs that are used directly (‘<samp><span class="samp">dir:</span></samp>’) or used indirectly (‘<samp><span class="samp">ind:</span></samp>’).
|
|
A struct type is used directly when it is the type of a variable, member.
|
|
Indirect uses arise through pointers to structs.
|
|
That is, when use of an incomplete struct is valid, the use is indirect.
|
|
An example is
|
|
‘<samp><span class="samp">struct one direct; struct two * indirect;</span></samp>’.
|
|
|
|
<p>The optional second word limits the specification to
|
|
ordinary structs (‘<samp><span class="samp">ord:</span></samp>’) or generic structs (‘<samp><span class="samp">gen:</span></samp>’).
|
|
Generic structs are a bit complicated to explain.
|
|
For C++, these are non-explicit specializations of template classes,
|
|
or non-template classes within the above.
|
|
Other programming languages have generics,
|
|
but <samp><span class="option">-femit-struct-debug-detailed</span></samp> does not yet implement them.
|
|
|
|
<p>The third word specifies the source files for those
|
|
structs for which the compiler should emit debug information.
|
|
The values ‘<samp><span class="samp">none</span></samp>’ and ‘<samp><span class="samp">any</span></samp>’ have the normal meaning.
|
|
The value ‘<samp><span class="samp">base</span></samp>’ means that
|
|
the base of name of the file in which the type declaration appears
|
|
must match the base of the name of the main compilation file.
|
|
In practice, this means that when compiling <samp><span class="file">foo.c</span></samp>, debug information
|
|
is generated for types declared in that file and <samp><span class="file">foo.h</span></samp>,
|
|
but not other header files.
|
|
The value ‘<samp><span class="samp">sys</span></samp>’ means those types satisfying ‘<samp><span class="samp">base</span></samp>’
|
|
or declared in system or compiler headers.
|
|
|
|
<p>You may need to experiment to determine the best settings for your application.
|
|
|
|
<p>The default is <samp><span class="option">-femit-struct-debug-detailed=all</span></samp>.
|
|
|
|
<p>This option works only with DWARF 2.
|
|
|
|
<br><dt><code>-fno-merge-debug-strings</code><dd><a name="index-fmerge_002ddebug_002dstrings-718"></a><a name="index-fno_002dmerge_002ddebug_002dstrings-719"></a>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.
|
|
|
|
<br><dt><code>-fdebug-prefix-map=</code><var>old</var><code>=</code><var>new</var><dd><a name="index-fdebug_002dprefix_002dmap-720"></a>When compiling files in directory <samp><var>old</var></samp>, record debugging
|
|
information describing them as in <samp><var>new</var></samp> instead.
|
|
|
|
<br><dt><code>-fno-dwarf2-cfi-asm</code><dd><a name="index-fdwarf2_002dcfi_002dasm-721"></a><a name="index-fno_002ddwarf2_002dcfi_002dasm-722"></a>Emit DWARF 2 unwind info as compiler generated <code>.eh_frame</code> section
|
|
instead of using GAS <code>.cfi_*</code> directives.
|
|
|
|
<p><a name="index-g_t_0040command_007bprof_007d-723"></a><br><dt><code>-p</code><dd><a name="index-p-724"></a>Generate extra code to write profile information suitable for the
|
|
analysis program <samp><span class="command">prof</span></samp>. You must use this option when compiling
|
|
the source files you want data about, and you must also use it when
|
|
linking.
|
|
|
|
<p><a name="index-g_t_0040command_007bgprof_007d-725"></a><br><dt><code>-pg</code><dd><a name="index-pg-726"></a>Generate extra code to write profile information suitable for the
|
|
analysis program <samp><span class="command">gprof</span></samp>. You must use this option when compiling
|
|
the source files you want data about, and you must also use it when
|
|
linking.
|
|
|
|
<br><dt><code>-Q</code><dd><a name="index-Q-727"></a>Makes the compiler print out each function name as it is compiled, and
|
|
print some statistics about each pass when it finishes.
|
|
|
|
<br><dt><code>-ftime-report</code><dd><a name="index-ftime_002dreport-728"></a>Makes the compiler print some statistics about the time consumed by each
|
|
pass when it finishes.
|
|
|
|
<br><dt><code>-fmem-report</code><dd><a name="index-fmem_002dreport-729"></a>Makes the compiler print some statistics about permanent memory
|
|
allocation when it finishes.
|
|
|
|
<br><dt><code>-fmem-report-wpa</code><dd><a name="index-fmem_002dreport_002dwpa-730"></a>Makes the compiler print some statistics about permanent memory
|
|
allocation for the WPA phase only.
|
|
|
|
<br><dt><code>-fpre-ipa-mem-report</code><dd><a name="index-fpre_002dipa_002dmem_002dreport-731"></a><br><dt><code>-fpost-ipa-mem-report</code><dd><a name="index-fpost_002dipa_002dmem_002dreport-732"></a>Makes the compiler print some statistics about permanent memory
|
|
allocation before or after interprocedural optimization.
|
|
|
|
<br><dt><code>-fprofile-report</code><dd><a name="index-fprofile_002dreport-733"></a>Makes the compiler print some statistics about consistency of the
|
|
(estimated) profile and effect of individual passes.
|
|
|
|
<br><dt><code>-fstack-usage</code><dd><a name="index-fstack_002dusage-734"></a>Makes the compiler output stack usage information for the program, on a
|
|
per-function basis. The filename for the dump is made by appending
|
|
<samp><span class="file">.su</span></samp> to the <var>auxname</var>. <var>auxname</var> 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:
|
|
|
|
<ul>
|
|
<li>The name of the function.
|
|
<li>A number of bytes.
|
|
<li>One or more qualifiers: <code>static</code>, <code>dynamic</code>, <code>bounded</code>.
|
|
</ul>
|
|
|
|
<p>The qualifier <code>static</code> 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.
|
|
|
|
<p>The qualifier <code>dynamic</code> 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</code> 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.
|
|
|
|
<br><dt><code>-fprofile-arcs</code><dd><a name="index-fprofile_002darcs-735"></a>Add code so that program flow <dfn>arcs</dfn> 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
|
|
<samp><var>auxname</var><span class="file">.gcda</span></samp> for each source file. The data may be used for
|
|
profile-directed optimizations (<samp><span class="option">-fbranch-probabilities</span></samp>), or for
|
|
test coverage analysis (<samp><span class="option">-ftest-coverage</span></samp>). Each object file's
|
|
<var>auxname</var> 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. <samp><span class="file">foo.gcda</span></samp> for input file <samp><span class="file">dir/foo.c</span></samp>, or
|
|
<samp><span class="file">dir/foo.gcda</span></samp> for output file specified as <samp><span class="option">-o dir/foo.o</span></samp>).
|
|
See <a href="Cross_002dprofiling.html#Cross_002dprofiling">Cross-profiling</a>.
|
|
|
|
<p><a name="index-g_t_0040command_007bgcov_007d-736"></a><br><dt><code>--coverage</code><dd><a name="index-coverage-737"></a>
|
|
This option is used to compile and link code instrumented for coverage
|
|
analysis. The option is a synonym for <samp><span class="option">-fprofile-arcs</span></samp>
|
|
<samp><span class="option">-ftest-coverage</span></samp> (when compiling) and <samp><span class="option">-lgcov</span></samp> (when
|
|
linking). See the documentation for those options for more details.
|
|
|
|
<ul>
|
|
<li>Compile the source files with <samp><span class="option">-fprofile-arcs</span></samp> plus optimization
|
|
and code generation options. For test coverage analysis, use the
|
|
additional <samp><span class="option">-ftest-coverage</span></samp> option. You do not need to profile
|
|
every source file in a program.
|
|
|
|
<li>Link your object files with <samp><span class="option">-lgcov</span></samp> or <samp><span class="option">-fprofile-arcs</span></samp>
|
|
(the latter implies the former).
|
|
|
|
<li>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</code> calls are detected and correctly handled (double counting
|
|
will not happen).
|
|
|
|
<li>For profile-directed optimizations, compile the source files again with
|
|
the same optimization and code generation options plus
|
|
<samp><span class="option">-fbranch-probabilities</span></samp> (see <a href="Optimize-Options.html#Optimize-Options">Options that Control Optimization</a>).
|
|
|
|
<li>For test coverage analysis, use <samp><span class="command">gcov</span></samp> to produce human readable
|
|
information from the <samp><span class="file">.gcno</span></samp> and <samp><span class="file">.gcda</span></samp> files. Refer to the
|
|
<samp><span class="command">gcov</span></samp> documentation for further information.
|
|
|
|
</ul>
|
|
|
|
<p>With <samp><span class="option">-fprofile-arcs</span></samp>, 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.
|
|
|
|
<br><dt><code>-ftest-coverage</code><dd><a name="index-ftest_002dcoverage-738"></a>Produce a notes file that the <samp><span class="command">gcov</span></samp> code-coverage utility
|
|
(see <a href="Gcov.html#Gcov"><samp><span class="command">gcov</span></samp>—a Test Coverage Program</a>) can use to
|
|
show program coverage. Each source file's note file is called
|
|
<samp><var>auxname</var><span class="file">.gcno</span></samp>. Refer to the <samp><span class="option">-fprofile-arcs</span></samp> option
|
|
above for a description of <var>auxname</var> and instructions on how to
|
|
generate test coverage data. Coverage data matches the source files
|
|
more closely if you do not optimize.
|
|
|
|
<br><dt><code>-fdbg-cnt-list</code><dd><a name="index-fdbg_002dcnt_002dlist-739"></a>Print the name and the counter upper bound for all debug counters.
|
|
|
|
<br><dt><code>-fdbg-cnt=</code><var>counter-value-list</var><dd><a name="index-fdbg_002dcnt-740"></a>Set the internal debug counter upper bound. <var>counter-value-list</var>
|
|
is a comma-separated list of <var>name</var>:<var>value</var> pairs
|
|
which sets the upper bound of each debug counter <var>name</var> to <var>value</var>.
|
|
All debug counters have the initial upper bound of <code>UINT_MAX</code>;
|
|
thus <code>dbg_cnt</code> returns true always unless the upper bound
|
|
is set by this option.
|
|
For example, with <samp><span class="option">-fdbg-cnt=dce:10,tail_call:0</span></samp>,
|
|
<code>dbg_cnt(dce)</code> returns true only for first 10 invocations.
|
|
|
|
<br><dt><code>-fenable-</code><var>kind</var><code>-</code><var>pass</var><dt><code>-fdisable-</code><var>kind</var><code>-</code><var>pass</var><code>=</code><var>range-list</var><dd><a name="index-fdisable_002d-741"></a><a name="index-fenable_002d-742"></a>
|
|
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.
|
|
|
|
<dl>
|
|
<dt><code>-fdisable-ipa-</code><var>pass</var><dd>Disable IPA pass <var>pass</var>. <var>pass</var> 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.
|
|
|
|
<br><dt><code>-fdisable-rtl-</code><var>pass</var><dt><code>-fdisable-rtl-</code><var>pass</var><code>=</code><var>range-list</var><dd>Disable RTL pass <var>pass</var>. <var>pass</var> 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</var> 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</var> falls within one of the specified ranges,
|
|
the <var>pass</var> is disabled for that function. The <var>uid</var> is shown in the
|
|
function header of a dump file, and the pass names can be dumped by using
|
|
option <samp><span class="option">-fdump-passes</span></samp>.
|
|
|
|
<br><dt><code>-fdisable-tree-</code><var>pass</var><dt><code>-fdisable-tree-</code><var>pass</var><code>=</code><var>range-list</var><dd>Disable tree pass <var>pass</var>. See <samp><span class="option">-fdisable-rtl</span></samp> for the description of
|
|
option arguments.
|
|
|
|
<br><dt><code>-fenable-ipa-</code><var>pass</var><dd>Enable IPA pass <var>pass</var>. <var>pass</var> 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.
|
|
|
|
<br><dt><code>-fenable-rtl-</code><var>pass</var><dt><code>-fenable-rtl-</code><var>pass</var><code>=</code><var>range-list</var><dd>Enable RTL pass <var>pass</var>. See <samp><span class="option">-fdisable-rtl</span></samp> for option argument
|
|
description and examples.
|
|
|
|
<br><dt><code>-fenable-tree-</code><var>pass</var><dt><code>-fenable-tree-</code><var>pass</var><code>=</code><var>range-list</var><dd>Enable tree pass <var>pass</var>. See <samp><span class="option">-fdisable-rtl</span></samp> for the description
|
|
of option arguments.
|
|
|
|
</dl>
|
|
|
|
<p>Here are some examples showing uses of these options.
|
|
|
|
<pre class="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
|
|
|
|
</pre>
|
|
<br><dt><code>-d</code><var>letters</var><dt><code>-fdump-rtl-</code><var>pass</var><dt><code>-fdump-rtl-</code><var>pass</var><code>=</code><var>filename</var><dd><a name="index-d-743"></a><a name="index-fdump_002drtl_002d_0040var_007bpass_007d-744"></a>Says to make debugging dumps during compilation at times specified by
|
|
<var>letters</var>. 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</var>, and the files are
|
|
created in the directory of the output file. In case of
|
|
<samp><span class="option">=</span><var>filename</var></samp> option, the dump is output on the given file
|
|
instead of the pass numbered dump files. Note that the pass number is
|
|
computed statically as passes get registered into the pass manager.
|
|
Thus the numbering is not related to the dynamic order of execution of
|
|
passes. In particular, a pass installed by a plugin could have a
|
|
number over 200 even if it executed quite early. <var>dumpname</var> 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. These switches may have different effects when
|
|
<samp><span class="option">-E</span></samp> is used for preprocessing.
|
|
|
|
<p>Debug dumps can be enabled with a <samp><span class="option">-fdump-rtl</span></samp> switch or some
|
|
<samp><span class="option">-d</span></samp> option <var>letters</var>. Here are the possible
|
|
letters for use in <var>pass</var> and <var>letters</var>, and their meanings:
|
|
|
|
<dl>
|
|
<dt><code>-fdump-rtl-alignments</code><dd><a name="index-fdump_002drtl_002dalignments-745"></a>Dump after branch alignments have been computed.
|
|
|
|
<br><dt><code>-fdump-rtl-asmcons</code><dd><a name="index-fdump_002drtl_002dasmcons-746"></a>Dump after fixing rtl statements that have unsatisfied in/out constraints.
|
|
|
|
<br><dt><code>-fdump-rtl-auto_inc_dec</code><dd><a name="index-fdump_002drtl_002dauto_005finc_005fdec-747"></a>Dump after auto-inc-dec discovery. This pass is only run on
|
|
architectures that have auto inc or auto dec instructions.
|
|
|
|
<br><dt><code>-fdump-rtl-barriers</code><dd><a name="index-fdump_002drtl_002dbarriers-748"></a>Dump after cleaning up the barrier instructions.
|
|
|
|
<br><dt><code>-fdump-rtl-bbpart</code><dd><a name="index-fdump_002drtl_002dbbpart-749"></a>Dump after partitioning hot and cold basic blocks.
|
|
|
|
<br><dt><code>-fdump-rtl-bbro</code><dd><a name="index-fdump_002drtl_002dbbro-750"></a>Dump after block reordering.
|
|
|
|
<br><dt><code>-fdump-rtl-btl1</code><dt><code>-fdump-rtl-btl2</code><dd><a name="index-fdump_002drtl_002dbtl2-751"></a><a name="index-fdump_002drtl_002dbtl2-752"></a><samp><span class="option">-fdump-rtl-btl1</span></samp> and <samp><span class="option">-fdump-rtl-btl2</span></samp> enable dumping
|
|
after the two branch
|
|
target load optimization passes.
|
|
|
|
<br><dt><code>-fdump-rtl-bypass</code><dd><a name="index-fdump_002drtl_002dbypass-753"></a>Dump after jump bypassing and control flow optimizations.
|
|
|
|
<br><dt><code>-fdump-rtl-combine</code><dd><a name="index-fdump_002drtl_002dcombine-754"></a>Dump after the RTL instruction combination pass.
|
|
|
|
<br><dt><code>-fdump-rtl-compgotos</code><dd><a name="index-fdump_002drtl_002dcompgotos-755"></a>Dump after duplicating the computed gotos.
|
|
|
|
<br><dt><code>-fdump-rtl-ce1</code><dt><code>-fdump-rtl-ce2</code><dt><code>-fdump-rtl-ce3</code><dd><a name="index-fdump_002drtl_002dce1-756"></a><a name="index-fdump_002drtl_002dce2-757"></a><a name="index-fdump_002drtl_002dce3-758"></a><samp><span class="option">-fdump-rtl-ce1</span></samp>, <samp><span class="option">-fdump-rtl-ce2</span></samp>, and
|
|
<samp><span class="option">-fdump-rtl-ce3</span></samp> enable dumping after the three
|
|
if conversion passes.
|
|
|
|
<br><dt><code>-fdump-rtl-cprop_hardreg</code><dd><a name="index-fdump_002drtl_002dcprop_005fhardreg-759"></a>Dump after hard register copy propagation.
|
|
|
|
<br><dt><code>-fdump-rtl-csa</code><dd><a name="index-fdump_002drtl_002dcsa-760"></a>Dump after combining stack adjustments.
|
|
|
|
<br><dt><code>-fdump-rtl-cse1</code><dt><code>-fdump-rtl-cse2</code><dd><a name="index-fdump_002drtl_002dcse1-761"></a><a name="index-fdump_002drtl_002dcse2-762"></a><samp><span class="option">-fdump-rtl-cse1</span></samp> and <samp><span class="option">-fdump-rtl-cse2</span></samp> enable dumping after
|
|
the two common subexpression elimination passes.
|
|
|
|
<br><dt><code>-fdump-rtl-dce</code><dd><a name="index-fdump_002drtl_002ddce-763"></a>Dump after the standalone dead code elimination passes.
|
|
|
|
<br><dt><code>-fdump-rtl-dbr</code><dd><a name="index-fdump_002drtl_002ddbr-764"></a>Dump after delayed branch scheduling.
|
|
|
|
<br><dt><code>-fdump-rtl-dce1</code><dt><code>-fdump-rtl-dce2</code><dd><a name="index-fdump_002drtl_002ddce1-765"></a><a name="index-fdump_002drtl_002ddce2-766"></a><samp><span class="option">-fdump-rtl-dce1</span></samp> and <samp><span class="option">-fdump-rtl-dce2</span></samp> enable dumping after
|
|
the two dead store elimination passes.
|
|
|
|
<br><dt><code>-fdump-rtl-eh</code><dd><a name="index-fdump_002drtl_002deh-767"></a>Dump after finalization of EH handling code.
|
|
|
|
<br><dt><code>-fdump-rtl-eh_ranges</code><dd><a name="index-fdump_002drtl_002deh_005franges-768"></a>Dump after conversion of EH handling range regions.
|
|
|
|
<br><dt><code>-fdump-rtl-expand</code><dd><a name="index-fdump_002drtl_002dexpand-769"></a>Dump after RTL generation.
|
|
|
|
<br><dt><code>-fdump-rtl-fwprop1</code><dt><code>-fdump-rtl-fwprop2</code><dd><a name="index-fdump_002drtl_002dfwprop1-770"></a><a name="index-fdump_002drtl_002dfwprop2-771"></a><samp><span class="option">-fdump-rtl-fwprop1</span></samp> and <samp><span class="option">-fdump-rtl-fwprop2</span></samp> enable
|
|
dumping after the two forward propagation passes.
|
|
|
|
<br><dt><code>-fdump-rtl-gcse1</code><dt><code>-fdump-rtl-gcse2</code><dd><a name="index-fdump_002drtl_002dgcse1-772"></a><a name="index-fdump_002drtl_002dgcse2-773"></a><samp><span class="option">-fdump-rtl-gcse1</span></samp> and <samp><span class="option">-fdump-rtl-gcse2</span></samp> enable dumping
|
|
after global common subexpression elimination.
|
|
|
|
<br><dt><code>-fdump-rtl-init-regs</code><dd><a name="index-fdump_002drtl_002dinit_002dregs-774"></a>Dump after the initialization of the registers.
|
|
|
|
<br><dt><code>-fdump-rtl-initvals</code><dd><a name="index-fdump_002drtl_002dinitvals-775"></a>Dump after the computation of the initial value sets.
|
|
|
|
<br><dt><code>-fdump-rtl-into_cfglayout</code><dd><a name="index-fdump_002drtl_002dinto_005fcfglayout-776"></a>Dump after converting to cfglayout mode.
|
|
|
|
<br><dt><code>-fdump-rtl-ira</code><dd><a name="index-fdump_002drtl_002dira-777"></a>Dump after iterated register allocation.
|
|
|
|
<br><dt><code>-fdump-rtl-jump</code><dd><a name="index-fdump_002drtl_002djump-778"></a>Dump after the second jump optimization.
|
|
|
|
<br><dt><code>-fdump-rtl-loop2</code><dd><a name="index-fdump_002drtl_002dloop2-779"></a><samp><span class="option">-fdump-rtl-loop2</span></samp> enables dumping after the rtl
|
|
loop optimization passes.
|
|
|
|
<br><dt><code>-fdump-rtl-mach</code><dd><a name="index-fdump_002drtl_002dmach-780"></a>Dump after performing the machine dependent reorganization pass, if that
|
|
pass exists.
|
|
|
|
<br><dt><code>-fdump-rtl-mode_sw</code><dd><a name="index-fdump_002drtl_002dmode_005fsw-781"></a>Dump after removing redundant mode switches.
|
|
|
|
<br><dt><code>-fdump-rtl-rnreg</code><dd><a name="index-fdump_002drtl_002drnreg-782"></a>Dump after register renumbering.
|
|
|
|
<br><dt><code>-fdump-rtl-outof_cfglayout</code><dd><a name="index-fdump_002drtl_002doutof_005fcfglayout-783"></a>Dump after converting from cfglayout mode.
|
|
|
|
<br><dt><code>-fdump-rtl-peephole2</code><dd><a name="index-fdump_002drtl_002dpeephole2-784"></a>Dump after the peephole pass.
|
|
|
|
<br><dt><code>-fdump-rtl-postreload</code><dd><a name="index-fdump_002drtl_002dpostreload-785"></a>Dump after post-reload optimizations.
|
|
|
|
<br><dt><code>-fdump-rtl-pro_and_epilogue</code><dd><a name="index-fdump_002drtl_002dpro_005fand_005fepilogue-786"></a>Dump after generating the function prologues and epilogues.
|
|
|
|
<br><dt><code>-fdump-rtl-sched1</code><dt><code>-fdump-rtl-sched2</code><dd><a name="index-fdump_002drtl_002dsched1-787"></a><a name="index-fdump_002drtl_002dsched2-788"></a><samp><span class="option">-fdump-rtl-sched1</span></samp> and <samp><span class="option">-fdump-rtl-sched2</span></samp> enable dumping
|
|
after the basic block scheduling passes.
|
|
|
|
<br><dt><code>-fdump-rtl-ree</code><dd><a name="index-fdump_002drtl_002dree-789"></a>Dump after sign/zero extension elimination.
|
|
|
|
<br><dt><code>-fdump-rtl-seqabstr</code><dd><a name="index-fdump_002drtl_002dseqabstr-790"></a>Dump after common sequence discovery.
|
|
|
|
<br><dt><code>-fdump-rtl-shorten</code><dd><a name="index-fdump_002drtl_002dshorten-791"></a>Dump after shortening branches.
|
|
|
|
<br><dt><code>-fdump-rtl-sibling</code><dd><a name="index-fdump_002drtl_002dsibling-792"></a>Dump after sibling call optimizations.
|
|
|
|
<br><dt><code>-fdump-rtl-split1</code><dt><code>-fdump-rtl-split2</code><dt><code>-fdump-rtl-split3</code><dt><code>-fdump-rtl-split4</code><dt><code>-fdump-rtl-split5</code><dd><a name="index-fdump_002drtl_002dsplit1-793"></a><a name="index-fdump_002drtl_002dsplit2-794"></a><a name="index-fdump_002drtl_002dsplit3-795"></a><a name="index-fdump_002drtl_002dsplit4-796"></a><a name="index-fdump_002drtl_002dsplit5-797"></a>These options enable dumping after five rounds of
|
|
instruction splitting.
|
|
|
|
<br><dt><code>-fdump-rtl-sms</code><dd><a name="index-fdump_002drtl_002dsms-798"></a>Dump after modulo scheduling. This pass is only run on some
|
|
architectures.
|
|
|
|
<br><dt><code>-fdump-rtl-stack</code><dd><a name="index-fdump_002drtl_002dstack-799"></a>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.
|
|
|
|
<br><dt><code>-fdump-rtl-subreg1</code><dt><code>-fdump-rtl-subreg2</code><dd><a name="index-fdump_002drtl_002dsubreg1-800"></a><a name="index-fdump_002drtl_002dsubreg2-801"></a><samp><span class="option">-fdump-rtl-subreg1</span></samp> and <samp><span class="option">-fdump-rtl-subreg2</span></samp> enable dumping after
|
|
the two subreg expansion passes.
|
|
|
|
<br><dt><code>-fdump-rtl-unshare</code><dd><a name="index-fdump_002drtl_002dunshare-802"></a>Dump after all rtl has been unshared.
|
|
|
|
<br><dt><code>-fdump-rtl-vartrack</code><dd><a name="index-fdump_002drtl_002dvartrack-803"></a>Dump after variable tracking.
|
|
|
|
<br><dt><code>-fdump-rtl-vregs</code><dd><a name="index-fdump_002drtl_002dvregs-804"></a>Dump after converting virtual registers to hard registers.
|
|
|
|
<br><dt><code>-fdump-rtl-web</code><dd><a name="index-fdump_002drtl_002dweb-805"></a>Dump after live range splitting.
|
|
|
|
<br><dt><code>-fdump-rtl-regclass</code><dt><code>-fdump-rtl-subregs_of_mode_init</code><dt><code>-fdump-rtl-subregs_of_mode_finish</code><dt><code>-fdump-rtl-dfinit</code><dt><code>-fdump-rtl-dfinish</code><dd><a name="index-fdump_002drtl_002dregclass-806"></a><a name="index-fdump_002drtl_002dsubregs_005fof_005fmode_005finit-807"></a><a name="index-fdump_002drtl_002dsubregs_005fof_005fmode_005ffinish-808"></a><a name="index-fdump_002drtl_002ddfinit-809"></a><a name="index-fdump_002drtl_002ddfinish-810"></a>These dumps are defined but always produce empty files.
|
|
|
|
<br><dt><code>-da</code><dt><code>-fdump-rtl-all</code><dd><a name="index-da-811"></a><a name="index-fdump_002drtl_002dall-812"></a>Produce all the dumps listed above.
|
|
|
|
<br><dt><code>-dA</code><dd><a name="index-dA-813"></a>Annotate the assembler output with miscellaneous debugging information.
|
|
|
|
<br><dt><code>-dD</code><dd><a name="index-dD-814"></a>Dump all macro definitions, at the end of preprocessing, in addition to
|
|
normal output.
|
|
|
|
<br><dt><code>-dH</code><dd><a name="index-dH-815"></a>Produce a core dump whenever an error occurs.
|
|
|
|
<br><dt><code>-dp</code><dd><a name="index-dp-816"></a>Annotate the assembler output with a comment indicating which
|
|
pattern and alternative is used. The length of each instruction is
|
|
also printed.
|
|
|
|
<br><dt><code>-dP</code><dd><a name="index-dP-817"></a>Dump the RTL in the assembler output as a comment before each instruction.
|
|
Also turns on <samp><span class="option">-dp</span></samp> annotation.
|
|
|
|
<br><dt><code>-dx</code><dd><a name="index-dx-818"></a>Just generate RTL for a function instead of compiling it. Usually used
|
|
with <samp><span class="option">-fdump-rtl-expand</span></samp>.
|
|
</dl>
|
|
|
|
<br><dt><code>-fdump-noaddr</code><dd><a name="index-fdump_002dnoaddr-819"></a>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.
|
|
|
|
<br><dt><code>-freport-bug</code><dd><a name="index-freport_002dbug-820"></a>Collect and dump debug information into temporary file if ICE in C/C++
|
|
compiler occured.
|
|
|
|
<br><dt><code>-fdump-unnumbered</code><dd><a name="index-fdump_002dunnumbered-821"></a>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
|
|
<samp><span class="option">-g</span></samp>.
|
|
|
|
<br><dt><code>-fdump-unnumbered-links</code><dd><a name="index-fdump_002dunnumbered_002dlinks-822"></a>When doing debugging dumps (see <samp><span class="option">-d</span></samp> option above), suppress
|
|
instruction numbers for the links to the previous and next instructions
|
|
in a sequence.
|
|
|
|
<br><dt><code>-fdump-translation-unit </code><span class="roman">(C++ only)</span><dt><code>-fdump-translation-unit-</code><var>options</var> <span class="roman">(C++ only)</span><dd><a name="index-fdump_002dtranslation_002dunit-823"></a>Dump a representation of the tree structure for the entire translation
|
|
unit to a file. The file name is made by appending <samp><span class="file">.tu</span></samp> to the
|
|
source file name, and the file is created in the same directory as the
|
|
output file. If the ‘<samp><span class="samp">-</span><var>options</var></samp>’ form is used, <var>options</var>
|
|
controls the details of the dump as described for the
|
|
<samp><span class="option">-fdump-tree</span></samp> options.
|
|
|
|
<br><dt><code>-fdump-class-hierarchy </code><span class="roman">(C++ only)</span><dt><code>-fdump-class-hierarchy-</code><var>options</var> <span class="roman">(C++ only)</span><dd><a name="index-fdump_002dclass_002dhierarchy-824"></a>Dump a representation of each class's hierarchy and virtual function
|
|
table layout to a file. The file name is made by appending
|
|
<samp><span class="file">.class</span></samp> to the source file name, and the file is created in the
|
|
same directory as the output file. If the ‘<samp><span class="samp">-</span><var>options</var></samp>’ form
|
|
is used, <var>options</var> controls the details of the dump as described
|
|
for the <samp><span class="option">-fdump-tree</span></samp> options.
|
|
|
|
<br><dt><code>-fdump-ipa-</code><var>switch</var><dd><a name="index-fdump_002dipa-825"></a>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:
|
|
|
|
<dl>
|
|
<dt>‘<samp><span class="samp">all</span></samp>’<dd>Enables all inter-procedural analysis dumps.
|
|
|
|
<br><dt>‘<samp><span class="samp">cgraph</span></samp>’<dd>Dumps information about call-graph optimization, unused function removal,
|
|
and inlining decisions.
|
|
|
|
<br><dt>‘<samp><span class="samp">inline</span></samp>’<dd>Dump after function inlining.
|
|
|
|
</dl>
|
|
|
|
<br><dt><code>-fdump-passes</code><dd><a name="index-fdump_002dpasses-826"></a>Dump the list of optimization passes that are turned on and off by
|
|
the current command-line options.
|
|
|
|
<br><dt><code>-fdump-statistics-</code><var>option</var><dd><a name="index-fdump_002dstatistics-827"></a>Enable and control dumping of pass statistics in a separate file. The
|
|
file name is generated by appending a suffix ending in
|
|
‘<samp><span class="samp">.statistics</span></samp>’ to the source file name, and the file is created in
|
|
the same directory as the output file. If the ‘<samp><span class="samp">-</span><var>option</var></samp>’
|
|
form is used, ‘<samp><span class="samp">-stats</span></samp>’ causes counters to be summed over the
|
|
whole compilation unit while ‘<samp><span class="samp">-details</span></samp>’ dumps every event as
|
|
the passes generate them. The default with no option is to sum
|
|
counters for each function compiled.
|
|
|
|
<br><dt><code>-fdump-tree-</code><var>switch</var><dt><code>-fdump-tree-</code><var>switch</var><code>-</code><var>options</var><dt><code>-fdump-tree-</code><var>switch</var><code>-</code><var>options</var><code>=</code><var>filename</var><dd><a name="index-fdump_002dtree-828"></a>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
|
|
<samp><span class="option">=</span><var>filename</var></samp> option, the dump is output on the given file
|
|
instead of the auto named dump files. If the ‘<samp><span class="samp">-</span><var>options</var></samp>’
|
|
form is used, <var>options</var> is a list of ‘<samp><span class="samp">-</span></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
|
|
|
|
<dl>
|
|
<dt>‘<samp><span class="samp">address</span></samp>’<dd>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.
|
|
<br><dt>‘<samp><span class="samp">asmname</span></samp>’<dd>If <code>DECL_ASSEMBLER_NAME</code> has been set for a given decl, use that
|
|
in the dump instead of <code>DECL_NAME</code>. Its primary use is ease of
|
|
use working backward from mangled names in the assembly file.
|
|
<br><dt>‘<samp><span class="samp">slim</span></samp>’<dd>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.
|
|
|
|
<p>When dumping pretty-printed trees, this option inhibits dumping the
|
|
bodies of control structures.
|
|
|
|
<p>When dumping RTL, print the RTL in slim (condensed) form instead of
|
|
the default LISP-like representation.
|
|
<br><dt>‘<samp><span class="samp">raw</span></samp>’<dd>Print a raw representation of the tree. By default, trees are
|
|
pretty-printed into a C-like representation.
|
|
<br><dt>‘<samp><span class="samp">details</span></samp>’<dd>Enable more detailed dumps (not honored by every dump option). Also
|
|
include information from the optimization passes.
|
|
<br><dt>‘<samp><span class="samp">stats</span></samp>’<dd>Enable dumping various statistics about the pass (not honored by every dump
|
|
option).
|
|
<br><dt>‘<samp><span class="samp">blocks</span></samp>’<dd>Enable showing basic block boundaries (disabled in raw dumps).
|
|
<br><dt>‘<samp><span class="samp">graph</span></samp>’<dd>For each of the other indicated dump files (<samp><span class="option">-fdump-rtl-</span><var>pass</var></samp>),
|
|
dump a representation of the control flow graph suitable for viewing with
|
|
GraphViz to <samp><var>file</var><span class="file">.</span><var>passid</var><span class="file">.</span><var>pass</var><span class="file">.dot</span></samp>. Each function in
|
|
the file is pretty-printed as a subgraph, so that GraphViz can render them
|
|
all in a single plot.
|
|
|
|
<p>This option currently only works for RTL dumps, and the RTL is always
|
|
dumped in slim form.
|
|
<br><dt>‘<samp><span class="samp">vops</span></samp>’<dd>Enable showing virtual operands for every statement.
|
|
<br><dt>‘<samp><span class="samp">lineno</span></samp>’<dd>Enable showing line numbers for statements.
|
|
<br><dt>‘<samp><span class="samp">uid</span></samp>’<dd>Enable showing the unique ID (<code>DECL_UID</code>) for each variable.
|
|
<br><dt>‘<samp><span class="samp">verbose</span></samp>’<dd>Enable showing the tree dump for each statement.
|
|
<br><dt>‘<samp><span class="samp">eh</span></samp>’<dd>Enable showing the EH region number holding each statement.
|
|
<br><dt>‘<samp><span class="samp">scev</span></samp>’<dd>Enable showing scalar evolution analysis details.
|
|
<br><dt>‘<samp><span class="samp">optimized</span></samp>’<dd>Enable showing optimization information (only available in certain
|
|
passes).
|
|
<br><dt>‘<samp><span class="samp">missed</span></samp>’<dd>Enable showing missed optimization information (only available in certain
|
|
passes).
|
|
<br><dt>‘<samp><span class="samp">note</span></samp>’<dd>Enable other detailed optimization information (only available in
|
|
certain passes).
|
|
<br><dt>‘<samp><span class="samp">=</span><var>filename</var></samp>’<dd>Instead of an auto named dump file, output into the given file
|
|
name. The file names <samp><span class="file">stdout</span></samp> and <samp><span class="file">stderr</span></samp> are treated
|
|
specially and are considered already open standard streams. For
|
|
example,
|
|
|
|
<pre class="smallexample"> gcc -O2 -ftree-vectorize -fdump-tree-vect-blocks=foo.dump
|
|
-fdump-tree-pre=stderr file.c
|
|
</pre>
|
|
<p>outputs vectorizer dump into <samp><span class="file">foo.dump</span></samp>, while the PRE dump is
|
|
output on to <samp><span class="file">stderr</span></samp>. If two conflicting dump filenames are
|
|
given for the same pass, then the latter option overrides the earlier
|
|
one.
|
|
|
|
<br><dt>‘<samp><span class="samp">all</span></samp>’<dd>Turn on all options, except <samp><span class="option">raw</span></samp>, <samp><span class="option">slim</span></samp>, <samp><span class="option">verbose</span></samp>
|
|
and <samp><span class="option">lineno</span></samp>.
|
|
|
|
<br><dt>‘<samp><span class="samp">optall</span></samp>’<dd>Turn on all optimization options, i.e., <samp><span class="option">optimized</span></samp>,
|
|
<samp><span class="option">missed</span></samp>, and <samp><span class="option">note</span></samp>.
|
|
</dl>
|
|
|
|
<p>The following tree dumps are possible:
|
|
<dl>
|
|
<dt>‘<samp><span class="samp">original</span></samp>’<dd><a name="index-fdump_002dtree_002doriginal-829"></a>Dump before any tree based optimization, to <samp><var>file</var><span class="file">.original</span></samp>.
|
|
|
|
<br><dt>‘<samp><span class="samp">optimized</span></samp>’<dd><a name="index-fdump_002dtree_002doptimized-830"></a>Dump after all tree based optimization, to <samp><var>file</var><span class="file">.optimized</span></samp>.
|
|
|
|
<br><dt>‘<samp><span class="samp">gimple</span></samp>’<dd><a name="index-fdump_002dtree_002dgimple-831"></a>Dump each function before and after the gimplification pass to a file. The
|
|
file name is made by appending <samp><span class="file">.gimple</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">cfg</span></samp>’<dd><a name="index-fdump_002dtree_002dcfg-832"></a>Dump the control flow graph of each function to a file. The file name is
|
|
made by appending <samp><span class="file">.cfg</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">ch</span></samp>’<dd><a name="index-fdump_002dtree_002dch-833"></a>Dump each function after copying loop headers. The file name is made by
|
|
appending <samp><span class="file">.ch</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">ssa</span></samp>’<dd><a name="index-fdump_002dtree_002dssa-834"></a>Dump SSA related information to a file. The file name is made by appending
|
|
<samp><span class="file">.ssa</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">alias</span></samp>’<dd><a name="index-fdump_002dtree_002dalias-835"></a>Dump aliasing information for each function. The file name is made by
|
|
appending <samp><span class="file">.alias</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">ccp</span></samp>’<dd><a name="index-fdump_002dtree_002dccp-836"></a>Dump each function after CCP. The file name is made by appending
|
|
<samp><span class="file">.ccp</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">storeccp</span></samp>’<dd><a name="index-fdump_002dtree_002dstoreccp-837"></a>Dump each function after STORE-CCP. The file name is made by appending
|
|
<samp><span class="file">.storeccp</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">pre</span></samp>’<dd><a name="index-fdump_002dtree_002dpre-838"></a>Dump trees after partial redundancy elimination. The file name is made
|
|
by appending <samp><span class="file">.pre</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">fre</span></samp>’<dd><a name="index-fdump_002dtree_002dfre-839"></a>Dump trees after full redundancy elimination. The file name is made
|
|
by appending <samp><span class="file">.fre</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">copyprop</span></samp>’<dd><a name="index-fdump_002dtree_002dcopyprop-840"></a>Dump trees after copy propagation. The file name is made
|
|
by appending <samp><span class="file">.copyprop</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">store_copyprop</span></samp>’<dd><a name="index-fdump_002dtree_002dstore_005fcopyprop-841"></a>Dump trees after store copy-propagation. The file name is made
|
|
by appending <samp><span class="file">.store_copyprop</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">dce</span></samp>’<dd><a name="index-fdump_002dtree_002ddce-842"></a>Dump each function after dead code elimination. The file name is made by
|
|
appending <samp><span class="file">.dce</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">sra</span></samp>’<dd><a name="index-fdump_002dtree_002dsra-843"></a>Dump each function after performing scalar replacement of aggregates. The
|
|
file name is made by appending <samp><span class="file">.sra</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">sink</span></samp>’<dd><a name="index-fdump_002dtree_002dsink-844"></a>Dump each function after performing code sinking. The file name is made
|
|
by appending <samp><span class="file">.sink</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">dom</span></samp>’<dd><a name="index-fdump_002dtree_002ddom-845"></a>Dump each function after applying dominator tree optimizations. The file
|
|
name is made by appending <samp><span class="file">.dom</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">dse</span></samp>’<dd><a name="index-fdump_002dtree_002ddse-846"></a>Dump each function after applying dead store elimination. The file
|
|
name is made by appending <samp><span class="file">.dse</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">phiopt</span></samp>’<dd><a name="index-fdump_002dtree_002dphiopt-847"></a>Dump each function after optimizing PHI nodes into straightline code. The file
|
|
name is made by appending <samp><span class="file">.phiopt</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">forwprop</span></samp>’<dd><a name="index-fdump_002dtree_002dforwprop-848"></a>Dump each function after forward propagating single use variables. The file
|
|
name is made by appending <samp><span class="file">.forwprop</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">copyrename</span></samp>’<dd><a name="index-fdump_002dtree_002dcopyrename-849"></a>Dump each function after applying the copy rename optimization. The file
|
|
name is made by appending <samp><span class="file">.copyrename</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">nrv</span></samp>’<dd><a name="index-fdump_002dtree_002dnrv-850"></a>Dump each function after applying the named return value optimization on
|
|
generic trees. The file name is made by appending <samp><span class="file">.nrv</span></samp> to the source
|
|
file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">vect</span></samp>’<dd><a name="index-fdump_002dtree_002dvect-851"></a>Dump each function after applying vectorization of loops. The file name is
|
|
made by appending <samp><span class="file">.vect</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">slp</span></samp>’<dd><a name="index-fdump_002dtree_002dslp-852"></a>Dump each function after applying vectorization of basic blocks. The file name
|
|
is made by appending <samp><span class="file">.slp</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">vrp</span></samp>’<dd><a name="index-fdump_002dtree_002dvrp-853"></a>Dump each function after Value Range Propagation (VRP). The file name
|
|
is made by appending <samp><span class="file">.vrp</span></samp> to the source file name.
|
|
|
|
<br><dt>‘<samp><span class="samp">all</span></samp>’<dd><a name="index-fdump_002dtree_002dall-854"></a>Enable all the available tree dumps with the flags provided in this option.
|
|
</dl>
|
|
|
|
<br><dt><code>-fopt-info</code><dt><code>-fopt-info-</code><var>options</var><dt><code>-fopt-info-</code><var>options</var><code>=</code><var>filename</var><dd><a name="index-fopt_002dinfo-855"></a>Controls optimization dumps from various optimization passes. If the
|
|
‘<samp><span class="samp">-</span><var>options</var></samp>’ form is used, <var>options</var> is a list of
|
|
‘<samp><span class="samp">-</span></samp>’ separated option keywords to select the dump details and
|
|
optimizations.
|
|
|
|
<p>The <var>options</var> 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.
|
|
|
|
<p>The following options control the dump verbosity:
|
|
|
|
<dl>
|
|
<dt>‘<samp><span class="samp">optimized</span></samp>’<dd>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.
|
|
<br><dt>‘<samp><span class="samp">missed</span></samp>’<dd>Print information about missed optimizations. Individual passes
|
|
control which information to include in the output.
|
|
<br><dt>‘<samp><span class="samp">note</span></samp>’<dd>Print verbose information about optimizations, such as certain
|
|
transformations, more detailed messages about decisions etc.
|
|
<br><dt>‘<samp><span class="samp">all</span></samp>’<dd>Print detailed optimization information. This includes
|
|
‘<samp><span class="samp">optimized</span></samp>’, ‘<samp><span class="samp">missed</span></samp>’, and ‘<samp><span class="samp">note</span></samp>’.
|
|
</dl>
|
|
|
|
<p>One or more of the following option keywords can be used to describe a
|
|
group of optimizations:
|
|
|
|
<dl>
|
|
<dt>‘<samp><span class="samp">ipa</span></samp>’<dd>Enable dumps from all interprocedural optimizations.
|
|
<br><dt>‘<samp><span class="samp">loop</span></samp>’<dd>Enable dumps from all loop optimizations.
|
|
<br><dt>‘<samp><span class="samp">inline</span></samp>’<dd>Enable dumps from all inlining optimizations.
|
|
<br><dt>‘<samp><span class="samp">vec</span></samp>’<dd>Enable dumps from all vectorization optimizations.
|
|
<br><dt>‘<samp><span class="samp">optall</span></samp>’<dd>Enable dumps from all optimizations. This is a superset of
|
|
the optimization groups listed above.
|
|
</dl>
|
|
|
|
<p>If <var>options</var> is
|
|
omitted, it defaults to ‘<samp><span class="samp">optimized-optall</span></samp>’, which means to dump all
|
|
info about successful optimizations from all the passes.
|
|
|
|
<p>If the <var>filename</var> is provided, then the dumps from all the
|
|
applicable optimizations are concatenated into the <var>filename</var>.
|
|
Otherwise the dump is output onto <samp><span class="file">stderr</span></samp>. Though multiple
|
|
<samp><span class="option">-fopt-info</span></samp> options are accepted, only one of them can include
|
|
a <var>filename</var>. If other filenames are provided then all but the
|
|
first such option are ignored.
|
|
|
|
<p>Note that the output <var>filename</var> is overwritten
|
|
in case of multiple translation units. If a combined output from
|
|
multiple translation units is desired, <samp><span class="file">stderr</span></samp> should be used
|
|
instead.
|
|
|
|
<p>In the following example, the optimization info is output to
|
|
<samp><span class="file">stderr</span></samp>:
|
|
|
|
<pre class="smallexample"> gcc -O3 -fopt-info
|
|
</pre>
|
|
<p>This example:
|
|
<pre class="smallexample"> gcc -O3 -fopt-info-missed=missed.all
|
|
</pre>
|
|
<p class="noindent">outputs missed optimization report from all the passes into
|
|
<samp><span class="file">missed.all</span></samp>, and this one:
|
|
|
|
<pre class="smallexample"> gcc -O2 -ftree-vectorize -fopt-info-vec-missed
|
|
</pre>
|
|
<p class="noindent">prints information about missed optimization opportunities from
|
|
vectorization passes on <samp><span class="file">stderr</span></samp>.
|
|
Note that <samp><span class="option">-fopt-info-vec-missed</span></samp> is equivalent to
|
|
<samp><span class="option">-fopt-info-missed-vec</span></samp>.
|
|
|
|
<p>As another example,
|
|
<pre class="smallexample"> gcc -O3 -fopt-info-inline-optimized-missed=inline.txt
|
|
</pre>
|
|
<p class="noindent">outputs information about missed optimizations as well as
|
|
optimized locations from all the inlining passes into
|
|
<samp><span class="file">inline.txt</span></samp>.
|
|
|
|
<p>Finally, consider:
|
|
|
|
<pre class="smallexample"> gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt
|
|
</pre>
|
|
<p class="noindent">Here the two output filenames <samp><span class="file">vec.miss</span></samp> and <samp><span class="file">loop.opt</span></samp> 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 <samp><span class="file">vec.miss</span></samp> is produced which contains
|
|
dumps from the vectorizer about missed opportunities.
|
|
|
|
<br><dt><code>-frandom-seed=</code><var>string</var><dd><a name="index-frandom_002dseed-856"></a>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 <samp><span class="option">-frandom-seed</span></samp> option to produce
|
|
reproducibly identical object files.
|
|
|
|
<p>The <var>string</var> 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).
|
|
|
|
<p>The <var>string</var> should be different for every file you compile.
|
|
|
|
<br><dt><code>-fsched-verbose=</code><var>n</var><dd><a name="index-fsched_002dverbose-857"></a>On targets that use instruction scheduling, this option controls the
|
|
amount of debugging output the scheduler prints. This information is
|
|
written to standard error, unless <samp><span class="option">-fdump-rtl-sched1</span></samp> or
|
|
<samp><span class="option">-fdump-rtl-sched2</span></samp> is specified, in which case it is output
|
|
to the usual dump listing file, <samp><span class="file">.sched1</span></samp> or <samp><span class="file">.sched2</span></samp>
|
|
respectively. However for <var>n</var> greater than nine, the output is
|
|
always printed to standard error.
|
|
|
|
<p>For <var>n</var> greater than zero, <samp><span class="option">-fsched-verbose</span></samp> outputs the
|
|
same information as <samp><span class="option">-fdump-rtl-sched1</span></samp> and <samp><span class="option">-fdump-rtl-sched2</span></samp>.
|
|
For <var>n</var> greater than one, it also output basic block probabilities,
|
|
detailed ready list information and unit/insn info. For <var>n</var> greater
|
|
than two, it includes RTL at abort point, control-flow and regions info.
|
|
And for <var>n</var> over four, <samp><span class="option">-fsched-verbose</span></samp> also includes
|
|
dependence info.
|
|
|
|
<br><dt><code>-save-temps</code><dt><code>-save-temps=cwd</code><dd><a name="index-save_002dtemps-858"></a>Store the usual “temporary” intermediate files permanently; place them
|
|
in the current directory and name them based on the source file. Thus,
|
|
compiling <samp><span class="file">foo.c</span></samp> with <samp><span class="option">-c -save-temps</span></samp> produces files
|
|
<samp><span class="file">foo.i</span></samp> and <samp><span class="file">foo.s</span></samp>, as well as <samp><span class="file">foo.o</span></samp>. This creates a
|
|
preprocessed <samp><span class="file">foo.i</span></samp> output file even though the compiler now
|
|
normally uses an integrated preprocessor.
|
|
|
|
<p>When used in combination with the <samp><span class="option">-x</span></samp> command-line option,
|
|
<samp><span class="option">-save-temps</span></samp> 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 <samp><span class="option">-save-temps</span></samp>.
|
|
|
|
<p>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:
|
|
|
|
<pre class="smallexample"> gcc -save-temps -o outdir1/foo.o indir1/foo.c&
|
|
gcc -save-temps -o outdir2/foo.o indir2/foo.c&
|
|
</pre>
|
|
<p>may result in <samp><span class="file">foo.i</span></samp> and <samp><span class="file">foo.o</span></samp> being written to
|
|
simultaneously by both compilers.
|
|
|
|
<br><dt><code>-save-temps=obj</code><dd><a name="index-save_002dtemps_003dobj-859"></a>Store the usual “temporary” intermediate files permanently. If the
|
|
<samp><span class="option">-o</span></samp> option is used, the temporary files are based on the
|
|
object file. If the <samp><span class="option">-o</span></samp> option is not used, the
|
|
<samp><span class="option">-save-temps=obj</span></samp> switch behaves like <samp><span class="option">-save-temps</span></samp>.
|
|
|
|
<p>For example:
|
|
|
|
<pre class="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
|
|
</pre>
|
|
<p class="noindent">creates <samp><span class="file">foo.i</span></samp>, <samp><span class="file">foo.s</span></samp>, <samp><span class="file">dir/xbar.i</span></samp>,
|
|
<samp><span class="file">dir/xbar.s</span></samp>, <samp><span class="file">dir2/yfoobar.i</span></samp>, <samp><span class="file">dir2/yfoobar.s</span></samp>, and
|
|
<samp><span class="file">dir2/yfoobar.o</span></samp>.
|
|
|
|
<br><dt><code>-time</code><span class="roman">[</span><code>=</code><var>file</var><span class="roman">]</span><dd><a name="index-time-860"></a>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).
|
|
|
|
<p>Without the specification of an output file, the output looks like this:
|
|
|
|
<pre class="smallexample"> # cc1 0.12 0.01
|
|
# as 0.00 0.01
|
|
</pre>
|
|
<p>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.
|
|
|
|
<p>With the specification of an output file, the output is appended to the
|
|
named file, and it looks like this:
|
|
|
|
<pre class="smallexample"> 0.12 0.01 cc1 <var>options</var>
|
|
0.00 0.01 as <var>options</var>
|
|
</pre>
|
|
<p>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.
|
|
|
|
<br><dt><code>-fvar-tracking</code><dd><a name="index-fvar_002dtracking-861"></a>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).
|
|
|
|
<p>It is enabled by default when compiling with optimization (<samp><span class="option">-Os</span></samp>,
|
|
<samp><span class="option">-O</span></samp>, <samp><span class="option">-O2</span></samp>, <small class="dots">...</small>), debugging information (<samp><span class="option">-g</span></samp>) and
|
|
the debug info format supports it.
|
|
|
|
<br><dt><code>-fvar-tracking-assignments</code><dd><a name="index-fvar_002dtracking_002dassignments-862"></a><a name="index-fno_002dvar_002dtracking_002dassignments-863"></a>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 <samp><span class="option">-gdwarf-4</span></samp> is recommended along with it.
|
|
|
|
<p>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 <samp><span class="option">-fvar-tracking</span></samp>,
|
|
except when selective scheduling is enabled.
|
|
|
|
<br><dt><code>-fvar-tracking-assignments-toggle</code><dd><a name="index-fvar_002dtracking_002dassignments_002dtoggle-864"></a><a name="index-fno_002dvar_002dtracking_002dassignments_002dtoggle-865"></a>Toggle <samp><span class="option">-fvar-tracking-assignments</span></samp>, in the same way that
|
|
<samp><span class="option">-gtoggle</span></samp> toggles <samp><span class="option">-g</span></samp>.
|
|
|
|
<br><dt><code>-print-file-name=</code><var>library</var><dd><a name="index-print_002dfile_002dname-866"></a>Print the full absolute name of the library file <var>library</var> 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.
|
|
|
|
<br><dt><code>-print-multi-directory</code><dd><a name="index-print_002dmulti_002ddirectory-867"></a>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 <samp><span class="env">GCC_EXEC_PREFIX</span></samp>.
|
|
|
|
<br><dt><code>-print-multi-lib</code><dd><a name="index-print_002dmulti_002dlib-868"></a>Print the mapping from multilib directory names to compiler switches
|
|
that enable them. The directory name is separated from the switches by
|
|
‘<samp><span class="samp">;</span></samp>’, and each switch starts with an ‘<samp><span class="samp">@</span></samp>’ instead of the
|
|
‘<samp><span class="samp">-</span></samp>’, without spaces between multiple switches. This is supposed to
|
|
ease shell processing.
|
|
|
|
<br><dt><code>-print-multi-os-directory</code><dd><a name="index-print_002dmulti_002dos_002ddirectory-869"></a>Print the path to OS libraries for the selected
|
|
multilib, relative to some <samp><span class="file">lib</span></samp> subdirectory. If OS libraries are
|
|
present in the <samp><span class="file">lib</span></samp> subdirectory and no multilibs are used, this is
|
|
usually just <samp><span class="file">.</span></samp>, if OS libraries are present in <samp><span class="file">lib</span><var>suffix</var></samp>
|
|
sibling directories this prints e.g. <samp><span class="file">../lib64</span></samp>, <samp><span class="file">../lib</span></samp> or
|
|
<samp><span class="file">../lib32</span></samp>, or if OS libraries are present in <samp><span class="file">lib/</span><var>subdir</var></samp>
|
|
subdirectories it prints e.g. <samp><span class="file">amd64</span></samp>, <samp><span class="file">sparcv9</span></samp> or <samp><span class="file">ev6</span></samp>.
|
|
|
|
<br><dt><code>-print-multiarch</code><dd><a name="index-print_002dmultiarch-870"></a>Print the path to OS libraries for the selected multiarch,
|
|
relative to some <samp><span class="file">lib</span></samp> subdirectory.
|
|
|
|
<br><dt><code>-print-prog-name=</code><var>program</var><dd><a name="index-print_002dprog_002dname-871"></a>Like <samp><span class="option">-print-file-name</span></samp>, but searches for a program such as <samp><span class="command">cpp</span></samp>.
|
|
|
|
<br><dt><code>-print-libgcc-file-name</code><dd><a name="index-print_002dlibgcc_002dfile_002dname-872"></a>Same as <samp><span class="option">-print-file-name=libgcc.a</span></samp>.
|
|
|
|
<p>This is useful when you use <samp><span class="option">-nostdlib</span></samp> or <samp><span class="option">-nodefaultlibs</span></samp>
|
|
but you do want to link with <samp><span class="file">libgcc.a</span></samp>. You can do:
|
|
|
|
<pre class="smallexample"> gcc -nostdlib <var>files</var>... `gcc -print-libgcc-file-name`
|
|
</pre>
|
|
<br><dt><code>-print-search-dirs</code><dd><a name="index-print_002dsearch_002ddirs-873"></a>Print the name of the configured installation directory and a list of
|
|
program and library directories <samp><span class="command">gcc</span></samp> searches—and don't do anything else.
|
|
|
|
<p>This is useful when <samp><span class="command">gcc</span></samp> prints the error message
|
|
‘<samp><span class="samp">installation problem, cannot exec cpp0: No such file or directory</span></samp>’.
|
|
To resolve this you either need to put <samp><span class="file">cpp0</span></samp> and the other compiler
|
|
components where <samp><span class="command">gcc</span></samp> expects to find them, or you can set the environment
|
|
variable <samp><span class="env">GCC_EXEC_PREFIX</span></samp> to the directory where you installed them.
|
|
Don't forget the trailing ‘<samp><span class="samp">/</span></samp>’.
|
|
See <a href="Environment-Variables.html#Environment-Variables">Environment Variables</a>.
|
|
|
|
<br><dt><code>-print-sysroot</code><dd><a name="index-print_002dsysroot-874"></a>Print the target sysroot directory that is used during
|
|
compilation. This is the target sysroot specified either at configure
|
|
time or using the <samp><span class="option">--sysroot</span></samp> option, possibly with an extra
|
|
suffix that depends on compilation options. If no target sysroot is
|
|
specified, the option prints nothing.
|
|
|
|
<br><dt><code>-print-sysroot-headers-suffix</code><dd><a name="index-print_002dsysroot_002dheaders_002dsuffix-875"></a>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.
|
|
|
|
<br><dt><code>-dumpmachine</code><dd><a name="index-dumpmachine-876"></a>Print the compiler's target machine (for example,
|
|
‘<samp><span class="samp">i686-pc-linux-gnu</span></samp>’)—and don't do anything else.
|
|
|
|
<br><dt><code>-dumpversion</code><dd><a name="index-dumpversion-877"></a>Print the compiler version (for example, <code>3.0</code>)—and don't do
|
|
anything else.
|
|
|
|
<br><dt><code>-dumpspecs</code><dd><a name="index-dumpspecs-878"></a>Print the compiler's built-in specs—and don't do anything else. (This
|
|
is used when GCC itself is being built.) See <a href="Spec-Files.html#Spec-Files">Spec Files</a>.
|
|
|
|
<br><dt><code>-fno-eliminate-unused-debug-types</code><dd><a name="index-feliminate_002dunused_002ddebug_002dtypes-879"></a><a name="index-fno_002deliminate_002dunused_002ddebug_002dtypes-880"></a>Normally, when producing DWARF 2 output, GCC avoids producing debug symbol
|
|
output for types that are nowhere used in the source file being compiled.
|
|
Sometimes it is useful to have GCC emit debugging
|
|
information for all types declared in a compilation
|
|
unit, regardless of whether or not they are actually used
|
|
in that compilation unit, for example
|
|
if, in the debugger, you want to cast a value to a type that is
|
|
not actually used in your program (but is declared). More often,
|
|
however, this results in a significant amount of wasted space.
|
|
</dl>
|
|
|
|
</body></html>
|
|
|