@samp{-W}---for example,
@option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of
these have both positive and negative forms; the negative form of
-@option{-ffoo} would be @option{-fno-foo}. This manual documents
+@option{-ffoo} is @option{-fno-foo}. This manual documents
only one of these two forms, whichever one is not the default.
@c man end
@item -pass-exit-codes
@opindex pass-exit-codes
-Normally the @command{gcc} program will exit with the code of 1 if any
+Normally the @command{gcc} program exits with the code of 1 if any
phase of the compiler returns a non-success return code. If you specify
-@option{-pass-exit-codes}, the @command{gcc} program will instead return with
-numerically highest error produced by any phase that returned an error
-indication. The C, C++, and Fortran frontends return 4, if an internal
+@option{-pass-exit-codes}, the @command{gcc} program instead returns with
+the numerically highest error produced by any phase returning an error
+indication. The C, C++, and Fortran front ends return 4 if an internal
compiler error is encountered.
@end table
@opindex help
Print (on the standard output) a description of the command-line options
understood by @command{gcc}. If the @option{-v} option is also specified
-then @option{--help} will also be passed on to the various processes
+then @option{--help} is also passed on to the various processes
invoked by @command{gcc}, so that they can display the command-line options
they accept. If the @option{-Wextra} option has also been specified
(prior to the @option{--help} option), then command-line options that
-have no documentation associated with them will also be displayed.
+have no documentation associated with them are also displayed.
@item --target-help
@opindex target-help
@table @asis
@item @samp{optimizers}
-This will display all of the optimization options supported by the
+Display all of the optimization options supported by the
compiler.
@item @samp{warnings}
-This will display all of the options controlling warning messages
+Display all of the options controlling warning messages
produced by the compiler.
@item @samp{target}
-This will display target-specific options. Unlike the
+Display target-specific options. Unlike the
@option{--target-help} option however, target-specific options of the
-linker and assembler will not be displayed. This is because those
+linker and assembler are not displayed. This is because those
tools do not currently support the extended @option{--help=} syntax.
@item @samp{params}
-This will display the values recognized by the @option{--param}
+Display the values recognized by the @option{--param}
option.
@item @var{language}
-This will display the options supported for @var{language}, where
+Display the options supported for @var{language}, where
@var{language} is the name of one of the languages supported in this
version of GCC@.
@item @samp{common}
-This will display the options that are common to all languages.
+Display the options that are common to all languages.
@end table
These are the supported qualifiers:
@end smallexample
The @option{--help=} option can be repeated on the command line. Each
-successive use will display its requested class of options, skipping
+successive use displays its requested class of options, skipping
those that have already been displayed.
If the @option{-Q} option appears on the command line before the
gcc -c t.c -wrapper gdb,--args
@end smallexample
-This will invoke all subprograms of @command{gcc} under
-@samp{gdb --args}, thus the invocation of @command{cc1} will be
+@noindent
+This invokes all subprograms of @command{gcc} under
+@samp{gdb --args}, thus the invocation of @command{cc1} is
@samp{gdb --args cc1 @dots{}}.
@item -fplugin=@var{name}.so
ISO standard doesn't call for; this is to avoid interfering with any
programs that might use these names for other things.
-Functions that would normally be built in but do not have semantics
+Functions that are normally built in but do not have semantics
defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
functions when @option{-ansi} is used. @xref{Other Builtins,,Other
built-in functions provided by GCC}, for details of the functions
The compiler can accept several base standards, such as @samp{c90} or
@samp{c++98}, and GNU dialects of those standards, such as
-@samp{gnu90} or @samp{gnu++98}. By specifying a base standard, the
-compiler will accept all programs following that standard and those
+@samp{gnu90} or @samp{gnu++98}. When a base standard is specified, the
+compiler accepts all programs following that standard plus those
using GNU extensions that do not contradict it. For example,
@option{-std=c90} turns off certain features of GCC that are
incompatible with ISO C90, such as the @code{asm} and @code{typeof}
@item -fgnu-tm
@opindex fgnu-tm
-When the option @option{-fgnu-tm} is specified, the compiler will
-generate code for the Linux variant of Intel's current Transactional
+When the option @option{-fgnu-tm} is specified, the compiler
+generates code for the Linux variant of Intel's current Transactional
Memory ABI specification document (Revision 1.1, May 6 2009). This is
an experimental feature whose interface may change in future versions
of GCC, as the official specification changes. Please note that not
Check that the pointer returned by @code{operator new} is non-null
before attempting to modify the storage allocated. This check is
normally unnecessary because the C++ standard specifies that
-@code{operator new} will only return @code{0} if it is declared
-@samp{throw()}, in which case the compiler will always check the
+@code{operator new} only returns @code{0} if it is declared
+@samp{throw()}, in which case the compiler always checks the
return value even without this option. In all other cases, when
@code{operator new} has a non-empty exception specification, memory
exhaustion is signalled by throwing @code{std::bad_alloc}. See also
cost of not diagnosing duplicate definitions. If you compile with this
flag and your program mysteriously crashes after @code{main()} has
completed, you may have an object that is being destroyed twice because
-two definitions were merged.
+two definitions are merged.
This option is no longer useful on most targets, now that support has
been added for putting variables into BSS without making them common.
for reducing code size in production builds, much like defining
@samp{NDEBUG}. This does not give user code permission to throw
exceptions in violation of the exception specifications; the compiler
-will still optimize based on the specifications, so throwing an
-unexpected exception will result in undefined behavior.
+still optimizes based on the specifications, so throwing an
+unexpected exception results in undefined behavior at run time.
@item -ffor-scope
@itemx -fno-for-scope
@opindex fno-implicit-inline-templates
Don't emit code for implicit instantiations of inline templates, either.
The default is to handle inlines differently so that compiles with and
-without optimization will need the same set of explicit instantiations.
+without optimization need the same set of explicit instantiations.
@item -fno-implement-inlines
@opindex fno-implement-inlines
To save space, do not emit out-of-line copies of inline functions
-controlled by @samp{#pragma implementation}. This will cause linker
+controlled by @samp{#pragma implementation}. This causes linker
errors if these functions are not inlined everywhere they are called.
@item -fms-extensions
@item -fnothrow-opt
@opindex fnothrow-opt
-Treat a @code{throw()} exception specification as though it were a
+Treat a @code{throw()} exception specification as if it were a
@code{noexcept} specification to reduce or eliminate the text size
overhead relative to a function with no exception specification. If
the function has local variables of types with non-trivial
-destructors, the exception specification will actually make the
+destructors, the exception specification actually makes the
function smaller because the EH cleanups for those variables can be
optimized away. The semantic effect is that an exception thrown out of
-a function with such an exception specification will result in a call
+a function with such an exception specification results in a call
to @code{terminate} rather than @code{unexpected}.
@item -fno-operator-names
@item -fpermissive
@opindex fpermissive
Downgrade some diagnostics about nonconformant code from errors to
-warnings. Thus, using @option{-fpermissive} will allow some
+warnings. Thus, using @option{-fpermissive} allows some
nonconforming code to compile.
@item -fno-pretty-templates
@opindex fno-pretty-templates
When an error message refers to a specialization of a function
-template, the compiler will normally print the signature of the
+template, the compiler normally prints the signature of the
template followed by the template arguments and any typedefs or
typenames in the signature (e.g. @code{void f(T) [with T = int]}
rather than @code{void f(int)}) so that it's clear which template is
involved. When an error message refers to a specialization of a class
-template, the compiler will omit any template arguments that match
+template, the compiler omits any template arguments that match
the default template arguments for that template. If either of these
behaviors make it harder to understand the error message rather than
-easier, using @option{-fno-pretty-templates} will disable them.
+easier, you can use @option{-fno-pretty-templates} to disable them.
@item -frepo
@opindex frepo
functions for use by the C++ run-time type identification features
(@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
of the language, you can save some space by using this flag. Note that
-exception handling uses the same information, but it will generate it as
+exception handling uses the same information, but G++ generates it as
needed. The @samp{dynamic_cast} operator can still be used for casts that
do not require run-time type information, i.e.@: casts to @code{void *} or to
unambiguous base classes.
Register destructors for objects with static storage duration with the
@code{__cxa_atexit} function rather than the @code{atexit} function.
This option is required for fully standards-compliant handling of static
-destructors, but will only work if your C library supports
+destructors, but only works if your C library supports
@code{__cxa_atexit}.
@item -fno-use-cxa-get-exception-ptr
@opindex fno-use-cxa-get-exception-ptr
Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
-will cause @code{std::uncaught_exception} to be incorrect, but is necessary
+causes @code{std::uncaught_exception} to be incorrect, but is necessary
if the runtime routine is not available.
@item -fvisibility-inlines-hidden
@opindex fvisibility-inlines-hidden
This switch declares that the user does not attempt to compare
pointers to inline functions or methods where the addresses of the two functions
-were taken in different shared objects.
+are taken in different shared objects.
The effect of this is that GCC may, effectively, mark inline methods with
@code{__attribute__ ((visibility ("hidden")))} so that they do not
effect of the switch for that method. For example, if you do want to
compare pointers to a particular inline method, you might mark it as
having default visibility. Marking the enclosing class with explicit
-visibility will have no effect.
+visibility has no effect.
Explicitly instantiated inline methods are unaffected by this option
as their linkage might otherwise cross a shared library boundary.
@item
The One Definition Rule is relaxed for types without explicit
-visibility specifications that are defined in more than one different
-shared object: those declarations are permitted if they would have
-been permitted when this option was not used.
+visibility specifications that are defined in more than one
+shared object: those declarations are permitted if they are
+permitted when this option is not used.
@end enumerate
In new code it is better to use @option{-fvisibility=hidden} and
Among the consequences of these changes are that static data members
of the same type with the same name but defined in different shared
-objects will be different, so changing one will not change the other;
+objects are different, so changing one does not change the other;
and that pointers to function members defined in different shared
objects may not compare equal. When this flag is given, it is a
violation of the ODR to define types with the same name differently.
@item -fno-weak
@opindex fno-weak
Do not use weak symbol support, even if it is provided by the linker.
-By default, G++ will use weak symbols if they are available. This
+By default, G++ uses weak symbols if they are available. This
option exists only for testing, and should not be used by end-users;
-it will result in inferior code and has no benefits. This option may
+it results in inferior code and has no benefits. This option may
be removed in a future release of G++.
@item -nostdinc++
@opindex fno-default-inline
Do not assume @samp{inline} for functions defined inside a class scope.
@xref{Optimize Options,,Options That Control Optimization}. Note that these
-functions will have linkage like inline functions; they just won't be
+functions have linkage like inline functions; they just aren't
inlined by default.
@item -Wabi @r{(C, Objective-C, C++ and Objective-C++ only)}
all such cases, there are probably some cases that are not warned about,
even though G++ is generating incompatible code. There may also be
cases where warnings are emitted even though the code that is generated
-will be compatible.
+is compatible.
You should rewrite your code to avoid these warnings if you are
concerned about the fact that code generated by G++ may not be binary
@end smallexample
@noindent
-In this case, G++ will place @code{B::f2} into the same byte
-as@code{A::f1}; other compilers will not. You can avoid this problem
+In this case, G++ places @code{B::f2} into the same byte
+as@code{A::f1}; other compilers do not. You can avoid this problem
by explicitly padding @code{A} so that its size is a multiple of the
-byte size on your platform; that will cause G++ and other compilers to
-layout @code{B} identically.
+byte size on your platform; that causes G++ and other compilers to
+lay out @code{B} identically.
@item
Incorrect handling of tail-padding for virtual bases. G++ does not use
@end smallexample
@noindent
-In this case, G++ will not place @code{B} into the tail-padding for
-@code{A}; other compilers will. You can avoid this problem by
+In this case, G++ does not place @code{B} into the tail-padding for
+@code{A}; other compilers do. You can avoid this problem by
explicitly padding @code{A} so that its size is a multiple of its
-alignment (ignoring virtual base classes); that will cause G++ and other
-compilers to layout @code{C} identically.
+alignment (ignoring virtual base classes); that causes G++ and other
+compilers to lay out @code{C} identically.
@item
Incorrect handling of bit-fields with declared widths greater than that
@end smallexample
@noindent
-Assuming that an @code{int} does not have 4096 bits, G++ will make the
+Assuming that an @code{int} does not have 4096 bits, G++ makes the
union too small by the number of bits in an @code{int}.
@item
@end smallexample
@noindent
-G++ will place the @code{A} base class of @code{C} at a nonzero offset;
+G++ places the @code{A} base class of @code{C} at a nonzero offset;
it should be placed at offset zero. G++ mistakenly believes that the
@code{A} data member of @code{B} is already at offset zero.
@item -Wnon-virtual-dtor @r{(C++ and Objective-C++ only)}
@opindex Wnon-virtual-dtor
@opindex Wno-non-virtual-dtor
-Warn when a class has virtual functions and accessible non-virtual
-destructor, in which case it would be possible but unsafe to delete
+Warn when a class has virtual functions and an accessible non-virtual
+destructor, in which case it is possible but unsafe to delete
an instance of a derived class through a pointer to the base class.
This warning is also enabled if @option{-Weffc++} is specified.
@};
@end smallexample
-The compiler will rearrange the member initializers for @samp{i}
+@noindent
+The compiler rearranges the member initializers for @samp{i}
and @samp{j} to match the declaration order of the members, emitting
a warning to that effect. This warning is enabled by @option{-Wall}.
@end table
b->f();
@end smallexample
-will fail to compile.
+@noindent
+fails to compile.
@item -Wno-pmf-conversions @r{(C++ and Objective-C++ only)}
@opindex Wno-pmf-conversions
@opindex Wno-sign-promo
Warn when overload resolution chooses a promotion from unsigned or
enumerated type to a signed type, over a conversion to an unsigned type of
-the same size. Previous versions of G++ would try to preserve
+the same size. Previous versions of G++ tried to preserve
unsignedness, but the standard mandates the current behavior.
@smallexample
@}
@end smallexample
-In this example, G++ will synthesize a default @samp{A& operator =
-(const A&);}, while cfront will use the user-defined @samp{operator =}.
+@noindent
+In this example, G++ synthesizes a default @samp{A& operator =
+(const A&);}, while cfront uses the user-defined @samp{operator =}.
@end table
@node Objective-C and Objective-C++ Dialect Options
literal string specified with the syntax @code{@@"@dots{}"}. The default
class name is @code{NXConstantString} if the GNU runtime is being used, and
@code{NSConstantString} if the NeXT runtime is being used (see below). The
-@option{-fconstant-cfstrings} option, if also present, will override the
+@option{-fconstant-cfstrings} option, if also present, overrides the
@option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
to be laid out as constant CoreFoundation strings.
@opindex fobjc-call-cxx-cdtors
For each Objective-C class, check if any of its instance variables is a
C++ object with a non-trivial default constructor. If so, synthesize a
-special @code{- (id) .cxx_construct} instance method which will run
+special @code{- (id) .cxx_construct} instance method which runs
non-trivial default constructors on any such instance variables, in order,
and then return @code{self}. Similarly, check if any instance variable
is a C++ object with a non-trivial destructor, and if so, synthesize a
-special @code{- (void) .cxx_destruct} method which will run
+special @code{- (void) .cxx_destruct} method which runs
all such default destructors, in reverse order.
The @code{- (id) .cxx_construct} and @code{- (void) .cxx_destruct}
-methods thusly generated will only operate on instance variables
+methods thusly generated only operate on instance variables
declared in the current Objective-C class, and not those inherited
from superclasses. It is the responsibility of the Objective-C
runtime to invoke all such methods in an object's inheritance
-hierarchy. The @code{- (id) .cxx_construct} methods will be invoked
+hierarchy. The @code{- (id) .cxx_construct} methods are invoked
by the runtime immediately after a new object instance is allocated;
-the @code{- (void) .cxx_destruct} methods will be invoked immediately
+the @code{- (void) .cxx_destruct} methods are invoked immediately
before the runtime deallocates an object instance.
As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
Warn if multiple methods with differing argument and/or return types are
found for a given selector when attempting to send a message using this
selector to a receiver of type @code{id} or @code{Class}. When this flag
-is off (which is the default behavior), the compiler will omit such warnings
+is off (which is the default behavior), the compiler omits such warnings
if any differences found are confined to types that share the same size
and alignment.
@cindex message formatting
Traditionally, diagnostic messages have been formatted irrespective of
-the output device's aspect (e.g.@: its width, @dots{}). The options described
-below can be used to control the diagnostic messages formatting
-algorithm, e.g.@: how many characters per line, how often source location
-information should be reported. Right now, only the C++ front end can
-honor these options. However it is expected, in the near future, that
-the remaining front ends would be able to digest them correctly.
+the output device's aspect (e.g.@: its width, @dots{}). You can use the
+options described below
+to control the formatting algorithm for diagnostic messages,
+e.g.@: how many characters per line, how often source location
+information should be reported. Note that some language front ends may not
+honor these options.
@table @gcctabopt
@item -fmessage-length=@var{n}
Try to format error messages so that they fit on lines of about @var{n}
characters. The default is 72 characters for @command{g++} and 0 for the rest of
the front ends supported by GCC@. If @var{n} is zero, then no
-line-wrapping will be done; each error message will appear on a single
+line-wrapping is done; each error message appears on a single
line.
@opindex fdiagnostics-show-location
@ref{Objective-C and Objective-C++ Dialect Options}.
When an unrecognized warning option is requested (e.g.,
-@option{-Wunknown-warning}), GCC will emit a diagnostic stating
+@option{-Wunknown-warning}), GCC emits a diagnostic stating
that the option is not recognized. However, if the @option{-Wno-} form
-is used, the behavior is slightly different: No diagnostic will be
+is used, the behavior is slightly different: no diagnostic is
produced for @option{-Wno-unknown-warning} unless other diagnostics
are being produced. This allows the use of new @option{-Wno-} options
-with old compilers, but if something goes wrong, the compiler will
-warn that an unrecognized option was used.
+with old compilers, but if something goes wrong, the compiler
+warns that an unrecognized option is present.
@table @gcctabopt
@item -pedantic
version of the ISO C standard specified by any @option{-std} option used.
Valid ISO C and ISO C++ programs should compile properly with or without
-this option (though a rare few will require @option{-ansi} or a
+this option (though a rare few require @option{-ansi} or a
@option{-std} option specifying the required version of ISO C)@. However,
without this option, certain GNU extensions and traditional C and C++
features are supported as well. With this option, they are rejected.
extended dialect of C, such as @samp{gnu90} or @samp{gnu99}, there is a
corresponding @dfn{base standard}, the version of ISO C on which the GNU
extended dialect is based. Warnings from @option{-pedantic} are given
-where they are required by the base standard. (It would not make sense
+where they are required by the base standard. (It does not make sense
for such warnings to be given only for features not in the specified GNU
C dialect, since by definition the GNU dialects of C include all
features the compiler supports with the given option, and there would be
@opindex Wno-coverage-mismatch
Warn if feedback profiles do not match when using the
@option{-fprofile-use} option.
-If a source file was changed between @option{-fprofile-gen} and
-@option{-fprofile-use}, the files with the profile feedback can fail
+If a source file is changed between compiling with @option{-fprofile-gen} and
+with @option{-fprofile-use}, the files with the profile feedback can fail
to match the source file and GCC cannot use the profile feedback
information. By default, this warning is enabled and is treated as an
error. @option{-Wno-coverage-mismatch} can be used to disable the
@}
@end group
@end smallexample
-the compiler will perform the entire computation with @code{double}
+the compiler performs the entire computation with @code{double}
because the floating-point literal is a @code{double}.
@item -Wformat
extensions. Other library implementations may not support all these
features; GCC does not support warning about features that go beyond a
particular library's limitations. However, if @option{-pedantic} is used
-with @option{-Wformat}, warnings will be given about format features not
+with @option{-Wformat}, warnings are given about format features not
in the selected standard version (but not for @code{strfmon} formats,
since those are not in any version of the C standard). @xref{C Dialect
Options,,Options Controlling C Dialect}.
specified with @samp{$} operand number specifications, normally
warnings are still given, since the implementation could not know what
type to pass to @code{va_arg} to skip the unused arguments. However,
-in the case of @code{scanf} formats, this option will suppress the
+in the case of @code{scanf} formats, this option suppresses the
warning if the unused arguments are all pointers, since the Single
Unix Specification says that such unused arguments are allowed.
Warn about uninitialized variables that are initialized with themselves.
Note this option can only be used with the @option{-Wuninitialized} option.
-For example, GCC will warn about @code{i} being uninitialized in the
+For example, GCC warns about @code{i} being uninitialized in the
following snippet only when @option{-Winit-self} has been specified:
@smallexample
@group
@code{if} statement, which in this example is @code{if (b)}. This is
often not what the programmer expected, as illustrated in the above
example by indentation the programmer chose. When there is the
-potential for this confusion, GCC will issue a warning when this flag
+potential for this confusion, GCC issues a warning when this flag
is specified. To eliminate the warning, add explicit braces around
the innermost @code{if} statement so there is no way the @code{else}
-could belong to the enclosing @code{if}. The resulting code would
-look like this:
+can belong to the enclosing @code{if}. The resulting code
+looks like this:
@smallexample
@group
@end group
@end smallexample
-Also warn for dangerous uses of the
-?: with omitted middle operand GNU extension. When the condition
-in the ?: operator is a boolean expression the omitted value will
-be always 1. Often the user expects it to be a value computed
+Also warn for dangerous uses of the GNU extension to
+@code{?:} with omitted middle operand. When the condition
+in the @code{?}: operator is a boolean expression, the omitted value is
+always 1. Often programmers expect it to be a value computed
inside the conditional expression instead.
This warning is enabled by @option{-Wall}.
used. To suppress this warning cast the unused expression to
@samp{void}. This includes an expression-statement or the left-hand
side of a comma expression that contains no side effects. For example,
-an expression such as @samp{x[i,j]} will cause a warning, while
-@samp{x[(void)i,j]} will not.
+an expression such as @samp{x[i,j]} causes a warning, while
+@samp{x[(void)i,j]} does not.
This warning is enabled by @option{-Wall}.
variables that are uninitialized or clobbered as a whole. They do
not occur for variables or elements declared @code{volatile}. Because
these warnings depend on optimization, the exact variables or elements
-for which there are warnings will depend on the precise optimization
+for which there are warnings depends on the precise optimization
options and version of GCC used.
Note that there may be no warning about a variable that is used only
@opindex Wno-maybe-uninitialized
For an automatic variable, if there exists a path from the function
entry to a use of the variable that is initialized, but there exist
-some other paths the variable is not initialized, the compiler will
-emit a warning if it can not prove the uninitialized paths do not
-happen at run time. These warnings are made optional because GCC is
+some other paths for which the variable is not initialized, the compiler
+emits a warning if it cannot prove the uninitialized paths are not
+executed at run time. These warnings are made optional because GCC is
not smart enough to see all the reasons why the code might be correct
-despite appearing to have an error. Here is one example of how
+in spite of appearing to have an error. Here is one example of how
this can happen:
@smallexample
@noindent
If the value of @code{y} is always 1, 2 or 3, then @code{x} is
always initialized, but GCC doesn't know this. To suppress the
-warning, the user needs to provide a default case with assert(0) or
+warning, you need to provide a default case with assert(0) or
similar code.
@cindex @code{longjmp} warnings
@cindex unknown pragmas, warning
@cindex pragmas, warning of unknown
Warn when a @code{#pragma} directive is encountered that is not understood by
-GCC@. If this command-line option is used, warnings will even be issued
+GCC@. If this command-line option is used, warnings are even issued
for unknown pragmas in system header files. This is not the case if
-the warnings were only enabled by the @option{-Wall} command-line option.
+the warnings are only enabled by the @option{-Wall} command-line option.
@item -Wno-pragmas
@opindex Wno-pragmas
actually a problem. To help focus on important issues, several
warning levels are defined. No warnings are issued for the use of
undefined signed overflow when estimating how many iterations a loop
-will require, in particular when determining whether a loop will be
+requires, in particular when determining whether a loop will be
executed at all.
@table @gcctabopt
@item -Wstrict-overflow=1
Warn about cases that are both questionable and easy to avoid. For
-example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
-compiler will simplify this to @code{1}. This level of
+example, with @option{-fstrict-overflow}, the compiler simplifies
+@code{x + 1 > x} to @code{1}. This level of
@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
are not, and must be explicitly requested.
@item -Wstrict-overflow=3
Also warn about other cases where a comparison is simplified. For
-example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
+example: @code{x + 1 > 1} is simplified to @code{x > 0}.
@item -Wstrict-overflow=4
Also warn about other simplifications not covered by the above cases.
-For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
+For example: @code{(x * 10) / 5} is simplified to @code{x * 2}.
@item -Wstrict-overflow=5
Also warn about cases where the compiler reduces the magnitude of a
-constant involved in a comparison. For example: @code{x + 2 > y} will
-be simplified to @code{x + 1 >= y}. This is reported only at the
+constant involved in a comparison. For example: @code{x + 2 > y} is
+simplified to @code{x + 1 >= y}. This is reported only at the
highest warning level because this simplification applies to many
-comparisons, so this warning level will give a very large number of
+comparisons, so this warning level gives a very large number of
false positives.
@end table
compiler output harder to read. Using this command-line option tells
GCC to emit warnings from system headers as if they occurred in user
code. However, note that using @option{-Wall} in conjunction with this
-option will @emph{not} warn about unknown pragmas in system
+option does @emph{not} warn about unknown pragmas in system
headers---for that, @option{-Wunknown-pragmas} must also be used.
@item -Wtrampolines
likely maximum error that the computation introduces, and allow for it
when performing comparisons (and when producing output, but that's a
different problem). In particular, instead of testing for equality, you
-would check to see whether the two values have ranges that overlap; and
+should check to see whether the two values have ranges that overlap; and
this is done with the relational operators, so equality comparisons are
probably mistaken.
@item
In traditional C, some preprocessor directives did not exist.
-Traditional preprocessors would only consider a line to be a directive
+Traditional preprocessors only considered a line to be a directive
if the @samp{#} appeared in column 1 on the line. Therefore
@option{-Wtraditional} warns about directives that traditional C
-understands but would ignore because the @samp{#} does not appear as the
+understands but ignores because the @samp{#} does not appear as the
first character on the line. It also suggests you hide directives like
@samp{#pragma} not understood by traditional C by indenting them. Some
-traditional implementations would not recognize @samp{#elif}, so it
+traditional implementations do not recognize @samp{#elif}, so this option
suggests avoiding it altogether.
@item
@item
Conversions by prototypes between fixed/floating-point values and vice
versa. The absence of these prototypes when compiling with traditional
-C would cause serious problems. This is a subset of the possible
-conversion warnings, for the full set use @option{-Wtraditional-conversion}.
+C causes serious problems. This is a subset of the possible
+conversion warnings; for the full set use @option{-Wtraditional-conversion}.
@item
Use of ISO C style function definitions. This warning intentionally is
@emph{not} issued for prototype declarations or variadic functions
-because these ISO C features will appear in your code when using
+because these ISO C features appear in your code when using
libiberty's traditional C compatibility macros, @code{PARAMS} and
@code{VPARAMS}. This warning is also bypassed for nested functions
because that feature is already a GCC extension and thus not relevant to
@opindex Wno-shadow
Warn whenever a local variable or type declaration shadows another variable,
parameter, type, or class member (in C++), or whenever a built-in function
-is shadowed. Note that in C++, the compiler will not warn if a local variable
-shadows a struct/class/enum, but will warn if it shadows an explicit typedef.
+is shadowed. Note that in C++, the compiler warns if a local variable
+shadows an explicit typedef, but not if it shadows a struct/class/enum.
@item -Wlarger-than=@var{len}
@opindex Wlarger-than=@var{len}
@item -Wunsafe-loop-optimizations
@opindex Wunsafe-loop-optimizations
@opindex Wno-unsafe-loop-optimizations
-Warn if the loop cannot be optimized because the compiler could not
+Warn if the loop cannot be optimized because the compiler cannot
assume anything on the bounds of the loop indices. With
-@option{-funsafe-loop-optimizations} warn if the compiler made
+@option{-funsafe-loop-optimizations} warn if the compiler makes
such assumptions.
@item -Wno-pedantic-ms-format @r{(MinGW targets only)}
@opindex Wno-write-strings
When compiling C, give string constants the type @code{const
char[@var{length}]} so that copying the address of one into a
-non-@code{const} @code{char *} pointer will get a warning. These
-warnings will help you find at compile time code that can try to write
+non-@code{const} @code{char *} pointer produces a warning. These
+warnings help you find at compile time code that can try to write
into a string constant, but only if you have been very careful about
-using @code{const} in declarations and prototypes. Otherwise, it will
-just be a nuisance. This is why we did not make @option{-Wall} request
+using @code{const} in declarations and prototypes. Otherwise, it is
+just a nuisance. This is why we did not make @option{-Wall} request
these warnings.
When compiling C++, warn about the deprecated conversion from string
using @option{-Wno-sign-conversion}.
For C++, also warn for confusing overload resolution for user-defined
-conversions; and conversions that will never use a type conversion
+conversions; and conversions that never use a type conversion
operator: conversions to @code{void}, the same type, a base class or a
reference to them. Warnings about conversions between signed and
unsigned integers are disabled by default in C++ unless
@opindex Wattributes
Do not warn if an unexpected @code{__attribute__} is used, such as
unrecognized attributes, function attributes applied to variables,
-etc. This will not stop errors for incorrect use of supported
+etc. This does not stop errors for incorrect use of supported
attributes.
@item -Wno-builtin-macro-redefined
@opindex Wextra
@opindex Wno-extra
Warn if a structure's initializer has some fields missing. For
-example, the following code would cause such a warning, because
+example, the following code causes such a warning, because
@code{x.h} is implicitly zero:
@smallexample
@end smallexample
This option does not warn about designated initializers, so the following
-modification would not trigger a warning:
+modification does not trigger a warning:
@smallexample
struct s @{ int f, g, h; @};
@opindex Wno-format
Warn about function pointers that might be candidates for @code{format}
attributes. Note these are only possible candidates, not absolute ones.
-GCC will guess that function pointers with @code{format} attributes that
+GCC guesses that function pointers with @code{format} attributes that
are used in assignment, initialization, parameter passing or return
statements should have a corresponding @code{format} attribute in the
resulting type. I.e.@: the left-hand side of the assignment or
of the containing function respectively should also have a @code{format}
attribute to avoid the warning.
-GCC will also warn about function definitions that might be
+GCC also warns about function definitions that might be
candidates for @code{format} attributes. Again, these are only
-possible candidates. GCC will guess that @code{format} attributes
+possible candidates. GCC guesses that @code{format} attributes
might be appropriate for any function that calls a function like
@code{vprintf} or @code{vscanf}, but this might not always be the
case, and some functions for which @code{format} attributes are
this, which is why this option is not the default.
You can switch the warning off for all characters by writing
-@option{-Wnormalized=none}. You would only want to do this if you
-were using some other normalization scheme (like ``D''), because
+@option{-Wnormalized=none}. You should only do this if you
+are using some other normalization scheme (like ``D''), because
otherwise you can easily create bugs that are literally impossible to see.
Some characters in ISO 10646 have distinct meanings but look identical
in some fonts or display methodologies, especially once formatting has
been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
-LETTER N'', will display just like a regular @code{n} that has been
+LETTER N'', displays just like a regular @code{n} that has been
placed in a superscript. ISO 10646 defines the @dfn{NFKC}
normalization scheme to convert all these into a standard form as
-well, and GCC will warn if your code is not in NFKC if you use
+well, and GCC warns if your code is not in NFKC if you use
@option{-Wnormalized=nfkc}. This warning is comparable to warning
about every identifier that contains the letter O because it might be
confused with the digit 0, and so is not the default, but may be
-useful as a local coding convention if the programming environment is
-unable to be fixed to display these characters distinctly.
+useful as a local coding convention if the programming environment
+cannot be fixed to display these characters distinctly.
@item -Wno-deprecated
@opindex Wno-deprecated
attribute has no effect on the layout or size of the structure.
Such structures may be mis-aligned for little benefit. For
instance, in this code, the variable @code{f.x} in @code{struct bar}
-will be misaligned even though @code{struct bar} does not itself
+is misaligned even though @code{struct bar} does not itself
have the packed attribute:
@smallexample
@item -Winline
@opindex Winline
@opindex Wno-inline
-Warn if a function can not be inlined and it was declared as inline.
-Even with this option, the compiler will not warn about failures to
+Warn if a function that is declared as inline cannot be inlined.
+Even with this option, the compiler does not warn about failures to
inline functions declared in system headers.
The compiler uses a variety of heuristics to determine whether or not
@opindex Wvla
@opindex Wno-vla
Warn if variable length array is used in the code.
-@option{-Wno-vla} will prevent the @option{-pedantic} warning of
+@option{-Wno-vla} prevents the @option{-pedantic} warning of
the variable length array.
@item -Wvolatile-register-var
@opindex Wno-disabled-optimization
Warn if a requested optimization pass is disabled. This warning does
not generally indicate that there is anything wrong with your code; it
-merely indicates that GCC's optimizers were unable to handle the code
+merely indicates that GCC's optimizers are unable to handle the code
effectively. Often, the problem is that your code is too big or too
-complex; GCC will refuse to optimize programs when the optimization
+complex; GCC refuses to optimize programs when the optimization
itself is likely to take inordinate amounts of time.
@item -Wpointer-sign @r{(C and Objective-C only)}
@opindex Wstack-protector
@opindex Wno-stack-protector
This option is only active when @option{-fstack-protector} is active. It
-warns about functions that will not be protected against stack smashing.
+warns about functions that are not protected against stack smashing.
@item -Wno-mudflap
@opindex Wno-mudflap
@item -Wunsuffixed-float-constants @r{(C and Objective-C only)}
@opindex Wunsuffixed-float-constants
-GCC will issue a warning for any floating constant that does not have
-a suffix. When used together with @option{-Wsystem-headers} it will
-warn about such constants in system header files. This can be useful
+Issue a warning for any floating constant that does not have
+a suffix. When used together with @option{-Wsystem-headers} it
+warns about such constants in system header files. This can be useful
when preparing code to use with the @code{FLOAT_CONST_DECIMAL64} pragma
from the decimal floating-point extension to C99.
@end table
On most systems that use stabs format, @option{-g} enables use of extra
debugging information that only GDB can use; this extra information
-makes debugging work better in GDB but will probably make other debuggers
+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 @option{-gstabs+}, @option{-gstabs},
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 were already at hand; some statements may
-execute in different places because they were moved out of loops.
+results or their values are already at hand; some statements may
+execute in different places because they have been moved out of loops.
Nevertheless it proves possible to debug optimized output. This makes
it reasonable to use the optimizer for programs that might have bugs.
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 will increase the size of debugging information by as much as a
+option increases the size of debugging information by as much as a
factor of two.
@item -fno-debug-types-section
@opindex fno-debug-types-section
@opindex fdebug-types-section
-By default when using DWARF Version 4 or higher type DIEs will be put into
-their own .debug_types section instead of making them part of the
-.debug_info section. It is more efficient to put them in a separate
-comdat sections since the linker will then be able to remove duplicates.
-But not all DWARF consumers support .debug_types sections yet.
+By default when using DWARF Version 4 or higher, type DIEs are put into
+their own @code{.debug_types} section instead of making them part of the
+@code{.debug_info} section. It is more efficient to put them in a separate
+comdat sections since the linker can then remove duplicates.
+But not all DWARF consumers support @code{.debug_types} sections yet.
@item -gstabs+
@opindex gstabs+
Produce debugging information in DWARF format (if that is supported).
The value of @var{version} may be either 2, 3 or 4; the default version is 2.
-Note that with DWARF Version 2 some ports require, and will always
-use, some non-conflicting DWARF 3 extensions in the unwind tables.
+Note that with DWARF Version 2, some ports require and always
+use some non-conflicting DWARF 3 extensions in the unwind tables.
Version 4 may require GDB 7.0 and @option{-fvar-tracking-assignments}
for maximum benefit.
@item -gtoggle
@opindex gtoggle
-Turn off generation of debug info, if leaving out this option would have
-generated 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
+Turn off generation of debug info, if leaving out this option
+generates it, or turn it on at level 2 otherwise. The position of this
+argument in the command line does not matter; it takes effect after all
other options are processed, and it does so only once, no matter how
many times it is given. This is mainly intended to be used with
@option{-fcompare-debug}.
@opindex fdump-final-insns
Dump the final internal representation (RTL) to @var{file}. If the
optional argument is omitted (or if @var{file} is @code{.}), the name
-of the dump file will be determined by appending @code{.gkd} to the
+of the dump file is determined by appending @code{.gkd} to the
compilation output file name.
@item -fcompare-debug@r{[}=@var{opts}@r{]}
To verify full coverage during @option{-fcompare-debug} testing, set
@env{GCC_COMPARE_DEBUG} to say @samp{-fcompare-debug-not-overridden},
-which GCC will reject as an invalid option in any actual compilation
+which GCC rejects as an invalid option in any actual compilation
(rather than preprocessing, assembly or linking). To get just a
warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug
not overridden} will do.
@item -femit-struct-debug-baseonly
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 was defined.
+matches the base name of file in which the struct is defined.
This option substantially reduces the size of debugging information,
but at significant potential loss in type information to the debugger.
@item -femit-struct-debug-reduced
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 was defined,
+matches the base name of file in which the type is defined,
unless the struct is a template or defined in a system header.
This option significantly reduces the size of debugging information,
@item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
Specify the struct-like types
-for which the compiler will generate debug information.
+for which the compiler generates debug information.
The intent is to reduce duplicate struct debug information
between different object files within the same program.
This option is a detailed version of
@option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
-which will serve for most needs.
+which serves for most needs.
A specification has the syntax@*
[@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
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 would be legal, the use is indirect.
+That is, when use of an incomplete struct is valid, the use is indirect.
An example is
@samp{struct one direct; struct two * indirect;}.
but @option{-femit-struct-debug-detailed} does not yet implement them.
The third word specifies the source files for those
-structs for which the compiler will emit debug information.
+structs for which the compiler should emit debug information.
The values @samp{none} and @samp{any} have the normal meaning.
The value @samp{base} 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
-types declared in @file{foo.c} and @file{foo.h} will have debug information,
-but types declared in other header will not.
+In practice, this means that when compiling @file{foo.c}, debug information
+is generated for types declared in that file and @file{foo.h},
+but not other header files.
The value @samp{sys} means those types satisfying @samp{base}
or declared in system or compiler headers.
show program coverage. Each source file's note file is called
@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
above for a description of @var{auxname} and instructions on how to
-generate test coverage data. Coverage data will match the source files
-more closely, if you do not optimize.
+generate test coverage data. Coverage data matches the source files
+more closely if you do not optimize.
@item -fdbg-cnt-list
@opindex fdbg-cnt-list
@item -dp
@opindex dp
Annotate the assembler output with a comment indicating which
-pattern and alternative was used. The length of each instruction is
+pattern and alternative is used. The length of each instruction is
also printed.
@item -dP
file name is generated by appending a suffix ending in
@samp{.statistics} to the source file name, and the file is created in
the same directory as the output file. If the @samp{-@var{option}}
-form is used, @samp{-stats} will cause counters to be summed over the
-whole compilation unit while @samp{-details} will dump every event as
+form is used, @samp{-stats} causes counters to be summed over the
+whole compilation unit while @samp{-details} dumps every event as
the passes generate them. The default with no option is to sum
counters for each function compiled.
@samp{-@var{options}} form is used, @var{options} is a list of
@samp{-} separated options which control the details of the dump. Not
all options are applicable to all dumps; those that are not
-meaningful will be ignored. The following options are available
+meaningful are ignored. The following options are available
@table @samp
@item address
Dump the control flow graph of each function to a file in VCG format. The
file name is made by appending @file{.vcg} to the source file name. Note
that if the file contains more than one function, the generated file cannot
-be used directly by VCG@. You will need to cut and paste each function's
+be used directly by VCG@. You must cut and paste each function's
graph into its own separate file first.
@item ch
@item -frandom-seed=@var{string}
@opindex frandom-seed
-This option provides a seed that GCC uses when it would otherwise use
-random numbers. It is used to generate certain symbol names
+This option provides a seed that GCC uses in place of
+random numbers in generating certain symbol names
that have to be different in every compiled file. It is also used to
place unique stamps in coverage data files and the object files that
produce them. You can use the @option{-frandom-seed} option to produce
@opindex save-temps
Store the usual ``temporary'' intermediate files permanently; place them
in the current directory and name them based on the source file. Thus,
-compiling @file{foo.c} with @option{-c -save-temps} would produce files
+compiling @file{foo.c} with @option{-c -save-temps} produces files
@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
preprocessed @file{foo.i} output file even though the compiler now
normally uses an integrated preprocessor.
gcc -save-temps=obj foobar.c -o dir2/yfoobar
@end smallexample
-would create @file{foo.i}, @file{foo.s}, @file{dir/xbar.i},
+@noindent
+creates @file{foo.i}, @file{foo.s}, @file{dir/xbar.i},
@file{dir/xbar.s}, @file{dir2/yfoobar.i}, @file{dir2/yfoobar.s}, and
@file{dir2/yfoobar.o}.
optimizing. Use of @option{-gdwarf-4} is recommended along with it.
It can be enabled even if var-tracking is disabled, in which case
-annotations will be created and maintained, but discarded at the end.
+annotations are created and maintained, but discarded at the end.
@item -fvar-tracking-assignments-toggle
@opindex fvar-tracking-assignments-toggle
@item -print-search-dirs
@opindex print-search-dirs
Print the name of the configured installation directory and a list of
-program and library directories @command{gcc} will search---and don't do anything else.
+program and library directories @command{gcc} searches---and don't do anything else.
This is useful when @command{gcc} prints the error message
@samp{installation problem, cannot exec cpp0: No such file or directory}.
@item -print-sysroot
@opindex print-sysroot
-Print the target sysroot directory that will be used during
+Print the target sysroot directory that is used during
compilation. This is the target sysroot specified either at configure
time or using the @option{--sysroot} option, possibly with an extra
suffix that depends on compilation options. If no target sysroot is
@item -feliminate-unused-debug-types
@opindex feliminate-unused-debug-types
-Normally, when producing DWARF 2 output, GCC will emit debugging
+Normally, when producing DWARF 2 output, GCC emits debugging
information for all types declared in a compilation
unit, regardless of whether or not they are actually used
in that compilation unit. Sometimes this is useful, such as
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.
-With this option, GCC will avoid producing debug symbol output
+With this option, GCC avoids producing debug symbol output
for types that are nowhere used in the source file being compiled.
@end table
results. Statements are independent: if you stop the program with a
breakpoint between statements, you can then assign a new value to any
variable or change the program counter to any other statement in the
-function and get exactly the results you would expect from the source
+function and get exactly the results you expect from the source
code.
Turning on optimization flags makes the compiler attempt to improve
Options of the form @option{-f@var{flag}} specify machine-independent
flags. Most flags have both positive and negative forms; the negative
-form of @option{-ffoo} would be @option{-fno-foo}. In the table
-below, only one of the forms is listed---the one you typically will
+form of @option{-ffoo} is @option{-fno-foo}. In the table
+below, only one of the forms is listed---the one you typically
use. You can figure out the other form by either removing @samp{no-}
or adding it.
on, even if the variables aren't referenced.
GCC enables this option by default. If you want to force the compiler to
-check if the variable was referenced, regardless of whether or not
+check if a variable is referenced, regardless of whether or not
optimization is turned on, use the @option{-fno-keep-static-consts} option.
@item -fmerge-constants
arrays or initialized constant variables with integral or floating-point
types. Languages like C or C++ require each variable, including multiple
instances of the same variable in recursive calls, to have distinct locations,
-so using this option will result in non-conforming
+so using this option results in non-conforming
behavior.
@item -fmodulo-sched
@item -fmodulo-sched-allow-regmoves
@opindex fmodulo-sched-allow-regmoves
-Perform more aggressive SMS based modulo scheduling with register moves
-allowed. By setting this flag certain anti-dependences edges will be
-deleted which will trigger the generation of reg-moves based on the
+Perform more aggressive SMS-based modulo scheduling with register moves
+allowed. By setting this flag certain anti-dependences edges are
+deleted, which triggers the generation of reg-moves based on the
life-range analysis. This option is effective only with
@option{-fmodulo-sched} enabled.
range/validity tests. Modules so instrumented should be immune to
buffer overflows, invalid heap use, and some other classes of C/C++
programming errors. The instrumentation relies on a separate runtime
-library (@file{libmudflap}), which will be linked into a program if
+library (@file{libmudflap}), which is linked into a program if
@option{-fmudflap} is given at link time. Run-time behavior of the
instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
In common subexpression elimination (CSE), scan through jump instructions
when the target of the jump is not reached by any other path. For
example, when CSE encounters an @code{if} statement with an
-@code{else} clause, CSE will follow the jump when the condition
+@code{else} clause, CSE follows the jump when the condition
tested is false.
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
@item -frerun-cse-after-loop
@opindex frerun-cse-after-loop
-Re-run common subexpression elimination after loop optimizations has been
+Re-run common subexpression elimination after loop optimizations are
performed.
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
@item -fgcse-lm
@opindex fgcse-lm
-When @option{-fgcse-lm} is enabled, global common subexpression elimination will
-attempt to move loads that are only killed by stores into themselves. This
+When @option{-fgcse-lm} is enabled, global common subexpression elimination
+attempts to move loads that are only killed by stores into themselves. This
allows a loop containing a load/store sequence to be changed to a load outside
the loop, and a copy/store within the loop.
-Enabled by default when gcse is enabled.
+Enabled by default when @option{-fgcse} is enabled.
@item -fgcse-sm
@opindex fgcse-sm
When @option{-fgcse-sm} is enabled, a store motion pass is run after
-global common subexpression elimination. This pass will attempt to move
+global common subexpression elimination. This pass attempts to move
stores out of loops. When used in conjunction with @option{-fgcse-lm},
loops containing a load/store sequence can be changed to a load before
the loop and a store after the loop.
@item -funsafe-loop-optimizations
@opindex funsafe-loop-optimizations
-If given, the loop optimizer will assume that loop indices do not
+If given, the loop optimizer assumes that loop indices do not
overflow, and that the loops with nontrivial exit condition are not
infinite. This enables a wider range of loop optimizations even if
the loop optimizer itself cannot prove that these assumptions are valid.
-Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
+If you use @option{-Wunsafe-loop-optimizations}, the compiler warns you
if it finds this kind of loop.
@item -fcrossjumping
@itemx -fsched-stalled-insns=@var{n}
@opindex fsched-stalled-insns
Define how many insns (if any) can be moved prematurely from the queue
-of stalled insns into the ready list, during the second scheduling pass.
-@option{-fno-sched-stalled-insns} means that no insns will be moved
+of stalled insns into the ready list during the second scheduling pass.
+@option{-fno-sched-stalled-insns} means that no insns are moved
prematurely, @option{-fsched-stalled-insns=0} means there is no limit
on how many queued insns can be moved prematurely.
@option{-fsched-stalled-insns} without a value is equivalent to
@item -fsched-stalled-insns-dep
@itemx -fsched-stalled-insns-dep=@var{n}
@opindex fsched-stalled-insns-dep
-Define how many insn groups (cycles) will be examined for a dependency
-on a stalled insn that is candidate for premature removal from the queue
+Define how many insn groups (cycles) are examined for a dependency
+on a stalled insn that is a candidate for premature removal from the queue
of stalled insns. This has an effect only during the second scheduling pass,
and only if @option{-fsched-stalled-insns} is used.
@option{-fno-sched-stalled-insns-dep} is equivalent to
@item -freschedule-modulo-scheduled-loops
@opindex freschedule-modulo-scheduled-loops
-The modulo scheduling comes before the traditional scheduling, if a loop
-was modulo scheduled we may want to prevent the later scheduling passes
-from changing its schedule, we use this option to control that.
+The modulo scheduling comes before the traditional scheduling. If a loop
+is modulo scheduled you may want to prevent the later scheduling passes
+from changing its schedule; use this option to control that.
@item -fselective-scheduling
@opindex fselective-scheduling
@item -fcaller-saves
@opindex fcaller-saves
-Enable values to be allocated in registers that will be clobbered by
+Enable allocation of values to registers that are clobbered by
function calls, by emitting extra instructions to save and restore the
registers around such calls. Such allocation is done only when it
-seems to result in better code than would otherwise be produced.
+seems to result in better code.
This option is always enabled by default on certain machines, usually
those which have no call-preserved registers to use instead.
@item -fconserve-stack
@opindex fconserve-stack
-Attempt to minimize stack usage. The compiler will attempt to use less
+Attempt to minimize stack usage. The compiler attempts to use less
stack space, even if that makes the program slower. This option
implies setting the @option{large-stack-frame} parameter to 100
and the @option{large-stack-frame-growth} parameter to 400.
@item -fipa-cp-clone
@opindex fipa-cp-clone
Perform function cloning to make interprocedural constant propagation stronger.
-When enabled, interprocedural constant propagation will perform function cloning
+When enabled, interprocedural constant propagation performs function cloning
when externally visible function can be called with constant arguments.
Because this optimization can create multiple copies of functions,
it may significantly increase code size
ENDDO
ENDDO
@end smallexample
-loop interchange will transform the loop as if the user had written:
+loop interchange transforms the loop as if it were written:
@smallexample
DO I = 1, N
DO J = 1, M
A(I) = A(I) + C
ENDDO
@end smallexample
-loop strip mining will transform the loop as if the user had written:
+loop strip mining transforms the loop as if it were written:
@smallexample
DO II = 1, N, 51
DO I = II, min (II + 50, N)
ENDDO
ENDDO
@end smallexample
-loop blocking will transform the loop as if the user had written:
+loop blocking transforms the loop as if it were written:
@smallexample
DO II = 1, N, 51
DO JJ = 1, M, 51
ENDDO
@end smallexample
which can be beneficial when @code{M} is larger than the caches,
-because the innermost loop will iterate over a smaller amount of data
+because the innermost loop iterates over a smaller amount of data
which can be kept in the caches. This optimization applies to all the
languages supported by GCC and is not limited to Fortran. To use this
code transformation, GCC has to be configured with @option{--with-ppl}
if (cond)
A[i] = expr;
@end smallexample
-would be transformed to
+is transformed to
@smallexample
for (i = 0; i < N; i++)
A[i] = cond ? expr : A[i];
@item -ftree-loop-im
@opindex ftree-loop-im
Perform loop invariant motion on trees. This pass moves only invariants that
-would be hard to handle at RTL level (function calls, operations that expand to
+are hard to handle at RTL level (function calls, operations that expand to
nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
operands of conditions that are invariant out of the loop, so that we can use
just trivial invariantness analysis in loop unswitching. The pass also includes
@item -fvariable-expansion-in-unroller
@opindex fvariable-expansion-in-unroller
-With this option, the compiler will create multiple copies of some
-local variables when unrolling a loop which can result in superior code.
+With this option, the compiler creates multiple copies of some
+local variables when unrolling a loop, which can result in superior code.
@item -fpartial-inlining
@opindex fpartial-inlining
@opindex fno-guess-branch-probability
Do not guess branch probabilities using heuristics.
-GCC will use heuristics to guess branch probabilities if they are
+GCC uses heuristics to guess branch probabilities if they are
not provided by profiling feedback (@option{-fprofile-arcs}). These
heuristics are based on the control flow graph. If some branch probabilities
-are specified by @samp{__builtin_expect}, then the heuristics will be
+are specified by @samp{__builtin_expect}, then the heuristics are
used to guess branch probabilities for the rest of the control flow graph,
taking the @samp{__builtin_expect} info into account. The interactions
between the heuristics and @samp{__builtin_expect} can be complex, and in
The practice of reading from a different union member than the one most
recently written to (called ``type-punning'') is common. Even with
@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
-is accessed through the union type. So, the code above will work as
+is accessed through the union type. So, the code above works as
expected. @xref{Structures unions enumerations and bit-fields
implementation}. However, this code might not:
@smallexample
Allow the compiler to assume strict signed overflow rules, depending
on the language being compiled. For C (and C++) this means that
overflow when doing arithmetic with signed numbers is undefined, which
-means that the compiler may assume that it will not happen. This
-permits various optimizations. For example, the compiler will assume
-that an expression like @code{i + 10 > i} will always be true for
+means that the compiler may assume that it does not happen. This
+permits various optimizations. For example, the compiler assumes
+that an expression like @code{i + 10 > i} is always true for
signed @code{i}. This assumption is only valid if signed overflow is
undefined, as the expression is false if @code{i + 10} overflows when
using twos complement arithmetic. When this option is in effect any
-attempt to determine whether an operation on signed numbers will
-overflow must be written carefully to not actually involve overflow.
+attempt to determine whether an operation on signed numbers
+overflows must be written carefully to not actually involve overflow.
This option also allows the compiler to assume strict pointer
semantics: given a pointer to an object, if adding an offset to that
Align the start of functions to the next power-of-two greater than
@var{n}, skipping up to @var{n} bytes. For instance,
@option{-falign-functions=32} aligns functions to the next 32-byte
-boundary, but @option{-falign-functions=24} would align to the next
+boundary, but @option{-falign-functions=24} aligns to the next
32-byte boundary only if this can be done by skipping 23 bytes or less.
@option{-fno-align-functions} and @option{-falign-functions=1} are
-equivalent and mean that functions will not be aligned.
+equivalent and mean that functions are not aligned.
Some assemblers only support this flag when @var{n} is a power of two;
in that case, it is rounded up.
branch target is reached in the usual flow of the code.
@option{-fno-align-labels} and @option{-falign-labels=1} are
-equivalent and mean that labels will not be aligned.
+equivalent and mean that labels are not aligned.
If @option{-falign-loops} or @option{-falign-jumps} are applicable and
are greater than this value, then their values are used instead.
@itemx -falign-loops=@var{n}
@opindex falign-loops
Align loops to a power-of-two boundary, skipping up to @var{n} bytes
-like @option{-falign-functions}. The hope is that the loop will be
-executed many times, which will make up for any execution of the dummy
+like @option{-falign-functions}. If the loops are
+executed many times, this makes up for any execution of the dummy
operations.
@option{-fno-align-loops} and @option{-falign-loops=1} are
-equivalent and mean that loops will not be aligned.
+equivalent and mean that loops are not aligned.
If @var{n} is not specified or is zero, use a machine-dependent default.
need be executed.
@option{-fno-align-jumps} and @option{-falign-jumps=1} are
-equivalent and mean that loops will not be aligned.
+equivalent and mean that loops are not aligned.
If @var{n} is not specified or is zero, use a machine-dependent default.
Do not reorder top-level functions, variables, and @code{asm}
statements. Output them in the same order that they appear in the
input file. When this option is used, unreferenced static variables
-will not be removed. This option is intended to support existing code
+are not removed. This option is intended to support existing code
that relies on a particular ordering. For new code, it is better to
use attributes.
each web individual pseudo register. This allows the register allocation pass
to operate on pseudos directly, but also strengthens several other optimization
passes, such as CSE, loop optimizer and trivial dead code remover. It can,
-however, make debugging impossible, since variables will no longer stay in a
+however, make debugging impossible, since variables no longer stay in a
``home register''.
Enabled by default with @option{-funroll-loops}.
@opindex fprofile-correction
Profiles collected using an instrumented binary for multi-threaded programs may
be inconsistent due to missed counter updates. When this option is specified,
-GCC will use heuristics to correct or smooth out such inconsistencies. By
-default, GCC will emit an error message when an inconsistent profile is detected.
+GCC uses heuristics to correct or smooth out such inconsistencies. By
+default, GCC emits an error message when an inconsistent profile is detected.
@item -fprofile-dir=@var{path}
@opindex fprofile-dir
@option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs}
and used by @option{-fprofile-use} and @option{-fbranch-probabilities}
and its related options. Both absolute and relative paths can be used.
-By default, GCC will use the current directory as @var{path}, thus the
-profile data file will appear in the same directory as the object file.
+By default, GCC uses the current directory as @var{path}, thus the
+profile data file appears in the same directory as the object file.
@item -fprofile-generate
@itemx -fprofile-generate=@var{path}
The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
-If @var{path} is specified, GCC will look at the @var{path} to find
+If @var{path} is specified, GCC looks at the @var{path} to find
the profile feedback data files. See @option{-fprofile-dir}.
@item -fprofile-use
@option{-Wcoverage-mismatch}. Note this may result in poorly optimized
code.
-If @var{path} is specified, GCC will look at the @var{path} to find
+If @var{path} is specified, GCC looks at the @var{path} to find
the profile feedback data files. See @option{-fprofile-dir}.
@end table
it is unpredictable when rounding to the types specified in the source
code takes place. When compiling C, if
@option{-fexcess-precision=standard} is specified then excess
-precision will follow the rules specified in ISO C99; in particular,
+precision follows the rules specified in ISO C99; in particular,
both casts and assignments cause values to be rounded to their
semantic types (whereas @option{-ffloat-store} only affects
assignments). This option is enabled by default for C if a strict
@opindex frename-registers
Attempt to avoid false dependencies in scheduled code by making use
of registers left over after register allocation. This optimization
-will most benefit processors with lots of registers. Depending on the
+most benefits processors with lots of registers. Depending on the
debug information format adopted by the target, however, it can
-make debugging impossible, since variables will no longer stay in
+make debugging impossible, since variables no longer stay in
a ``home register''.
Enabled by default with @option{-funroll-loops} and @option{-fpeel-loops}.
the future.
Only use these options when there are significant benefits from doing
-so. When you specify these options, the assembler and linker will
-create larger object and executable files and will also be slower.
-You will not be able to use @code{gprof} on all systems if you
-specify this option and you may have problems with debugging if
+so. When you specify these options, the assembler and linker
+create larger object and executable files and are also slower.
+You cannot use @code{gprof} on all systems if you
+specify this option, and you may have problems with debugging if
you specify both this option and @option{-g}.
@item -fbranch-target-load-optimize
int foo (void) @{ return a + b + c; @}
@end smallexample
-would usually calculate the addresses of all three variables, but if you
-compile it with @option{-fsection-anchors}, it will access the variables
+@noindent
+usually calculates the addresses of all three variables, but if you
+compile it with @option{-fsection-anchors}, it accesses the variables
from a common anchor point instead. The effect is similar to the
following pseudocode (which isn't valid C):
@item --param @var{name}=@var{value}
@opindex param
In some places, GCC uses various constants to control the amount of
-optimization that is done. For example, GCC will not inline functions
+optimization that is done. For example, GCC does not inline functions
that contain more than a certain number of instructions. You can
control some of these constants on the command line using the
@option{--param} option.
@item min-crossjump-insns
The minimum number of instructions that must be matched at the end
-of two blocks before crossjumping will be performed on them. This
+of two blocks before crossjumping is performed on them. This
value is ignored in the case where all instructions in the block being
crossjumped from are matched. The default value is 5.
@item max-delay-slot-insn-search
The maximum number of instructions to consider when looking for an
instruction to fill a delay slot. If more than this arbitrary number of
-instructions is searched, the time savings from filling the delay slot
-will be minimal so stop searching. Increasing values mean more
+instructions are searched, the time savings from filling the delay slot
+are minimal, so stop searching. Increasing values mean more
aggressive optimization, making the compilation time increase with probably
small improvement in execution time.
control-flow graph.
@item max-gcse-memory
-The approximate maximum amount of memory that will be allocated in
+The approximate maximum amount of memory that can be allocated in
order to perform the global common subexpression elimination
optimization. If more memory than specified is required, the
-optimization will not be done.
+optimization is not done.
@item max-gcse-insertion-ratio
If the ratio of expression insertions to deletions is larger than this value
-for any expression, then RTL PRE will insert or remove the expression and thus
-leave partially redundant computations in the instruction stream. The default value is 20.
+for any expression, then RTL PRE inserts or removes the expression and thus
+leaves partially redundant computations in the instruction stream. The default value is 20.
@item max-pending-list-length
-The maximum number of pending dependencies scheduling will allow
+The maximum number of pending dependencies scheduling allows
before flushing the current state and starting over. Large functions
with few branches or calls can create excessively large lists which
needlessly consume memory and resources.
Several parameters control the tree inliner used in GCC@.
This number sets the maximum number of instructions (counted in GCC's
internal representation) in a single function that the tree inliner
-will consider for inlining. This only affects functions declared
+considers for inlining. This only affects functions declared
inline and methods implemented in a class declaration (C++).
The default value is 400.
@item max-inline-insns-auto
When you use @option{-finline-functions} (included in @option{-O3}),
a lot of functions that would otherwise not be considered for inlining
-by the compiler will be investigated. To those functions, a different
+by the compiler are investigated. To those functions, a different
(more restrictive) limit compared to functions declared inline can
be applied.
The default value is 40.
@item comdat-sharing-probability
@itemx comdat-sharing-probability
Probability (in percent) that C++ inline function with comdat visibility
-will be shared across multiple compilation units. The default value is 20.
+are shared across multiple compilation units. The default value is 20.
@item min-vect-loop-bound
-The minimum number of iterations under which a loop will not get vectorized
+The minimum number of iterations under which a loop is not vectorized
when @option{-ftree-vectorize} is used. The number of iterations after
vectorization needs to be greater than the value specified by this option
to allow vectorization. The default value is 0.
Scaling factor in calculation of maximum distance an expression
can be moved by GCSE optimizations. This is currently supported only in the
code hoisting pass. The bigger the ratio, the more aggressive code hoisting
-will be with simple expressions, i.e., the expressions that have cost
-less than @option{gcse-unrestricted-cost}. Specifying 0 will disable
+is with simple expressions, i.e., the expressions that have cost
+less than @option{gcse-unrestricted-cost}. Specifying 0 disables
hoisting of simple expressions. The default value is 10.
@item gcse-unrestricted-cost
Cost, roughly measured as the cost of a single typical machine
-instruction, at which GCSE optimizations will not constrain
+instruction, at which GCSE optimizations do not constrain
the distance an expression can travel. This is currently
supported only in the code hoisting pass. The lesser the cost,
-the more aggressive code hoisting will be. Specifying 0 will
-allow all expressions to travel unrestricted distances.
+the more aggressive code hoisting is. Specifying 0
+allows all expressions to travel unrestricted distances.
The default value is 3.
@item max-hoist-depth
The depth of search in the dominator tree for expressions to hoist.
This is used to avoid quadratic behavior in hoisting algorithm.
-The value of 0 will avoid limiting the search, but may slow down compilation
+The value of 0 does not limit on the search, but may slow down compilation
of huge functions. The default value is 30.
@item max-tail-merge-comparisons
The default value is 128.
@item omega-max-wild-cards
-The maximum number of wildcard variables that the Omega solver will
-be able to insert. The default value is 18.
+The maximum number of wildcard variables that the Omega solver is
+able to insert. The default value is 18.
@item omega-hash-table-size
The size of the hash table in the Omega solver. The default value is
@item max-predicted-iterations
The maximum number of loop iterations we predict statically. This is useful
-in cases where function contain single loop with known bound and other loop
-with unknown. We predict the known number of iterations correctly, while
+in cases where a function contains a single loop with known bound and
+another loop with unknown bound.
+The known number of iterations is predicted correctly, while
the unknown number of iterations average to roughly 10. This means that the
-loop without bounds would appear artificially cold relative to the other one.
+loop without bounds appears artificially cold relative to the other one.
@item align-threshold
-Select fraction of the maximal frequency of executions of basic block in
-function given basic block will get aligned.
+Select fraction of the maximal frequency of executions of a basic block in
+a function to align the basic block.
@item align-loop-iterations
-A loop expected to iterate at lest the selected number of iterations will get
+A loop expected to iterate at least the selected number of iterations is
aligned.
@item tracer-dynamic-coverage
@item tracer-max-code-growth
Stop tail duplication once code growth has reached given percentage. This is
-rather hokey argument, as most of the duplicates will be eliminated later in
+a rather artificial limit, as most of the duplicates are eliminated later in
cross jumping, so it may be set to much higher values than is the desired code
growth.
@item tracer-min-branch-ratio
@itemx tracer-min-branch-ratio-feedback
-Stop forward growth if the best edge do have probability lower than this
+Stop forward growth if the best edge has probability lower than this
threshold.
Similarly to @option{tracer-dynamic-coverage} two values are present, one for
@item sched-spec-prob-cutoff
The minimal probability of speculation success (in percents), so that
-speculative insn will be scheduled.
+speculative insns are scheduled.
The default value is 40.
@item sched-mem-true-dep-cost
The default value is 50.
@item selsched-max-sched-times
-The maximum number of times that an instruction will be scheduled during
+The maximum number of times that an instruction is scheduled during
selective scheduling. This is the limit on the number of iterations
through which the instruction may be pipelined. The default value is 2.
for renaming in the selective scheduler. The default value is 2.
@item sms-min-sc
-The minimum value of stage count that swing modulo scheduler will
-generate. The default value is 2.
+The minimum value of stage count that swing modulo scheduler
+generates. The default value is 2.
@item max-last-value-rtl
The maximum size measured as number of RTLs that can be recorded in an expression
ratio is 3.
@item ssp-buffer-size
-The minimum size of buffers (i.e.@: arrays) that will receive stack smashing
+The minimum size of buffers (i.e.@: arrays) that receive stack smashing
protection when @option{-fstack-protection} is used.
@item max-jump-thread-duplication-stmts
duplicated when threading jumps.
@item max-fields-for-field-sensitive
-Maximum number of fields in a structure we will treat in
+Maximum number of fields in a structure treated in
a field sensitive manner during pointer analysis. The default is zero
for @option{-O0} and @option{-O1},
and 100 for @option{-Os}, @option{-O2}, and @option{-O3}.
set this value to 0 to disable canonical types.
@item switch-conversion-max-branch-ratio
-Switch initialization conversion will refuse to create arrays that are
+Switch initialization conversion refuses to create arrays that are
bigger than @option{switch-conversion-max-branch-ratio} times the number of
branches in the switch.
consuming all of the memory available on the host machine. This
parameter sets a limit on the length of the sets that are computed,
which prevents the runaway behavior. Setting a value of 0 for
-this parameter will allow an unlimited set length.
+this parameter allows an unlimited set length.
@item sccvn-max-scc-size
Maximum size of a strongly connected component (SCC) during SCCVN
processing. If this limit is hit, SCCVN processing for the whole
-function will not be done and optimizations depending on it will
-be disabled. The default maximum SCC size is 10000.
+function is not done and optimizations depending on it are
+disabled. The default maximum SCC size is 10000.
@item ira-max-loops-num
IRA uses regional register allocation by default. If a function
@item loop-max-datarefs-for-datadeps
Building data dapendencies is expensive for very large loops. This
parameter limits the number of data references in loops that are
-considered for data dependence analysis. These large loops will not
-be handled then by the optimizations using loop data dependencies.
+considered for data dependence analysis. These large loops are no
+handled by the optimizations using loop data dependencies.
The default value is 1000.
@item max-vartrack-size
(non-overlapping) uids above it if the reserved range is exhausted.
@item ipa-sra-ptr-growth-factor
-IPA-SRA will replace a pointer to an aggregate with one or more new
+IPA-SRA replaces a pointer to an aggregate with one or more new
parameters only when their cumulative size is less or equal to
@option{ipa-sra-ptr-growth-factor} times the size of the original
pointer parameter.
@item tm-max-aggregate-size
When making copies of thread-local variables in a transaction, this
-parameter specifies the size in bytes after which variables will be
+parameter specifies the size in bytes after which variables are
saved with the logging functions as opposed to save/restore code
sequence pairs. This option only applies when using
@option{-fgnu-tm}.
@item -nodefaultlibs
@opindex nodefaultlibs
Do not use the standard system libraries when linking.
-Only the libraries you specify will be passed to the linker, options
+Only the libraries you specify are passed to the linker, and options
specifying linkage of the system libraries, such as @code{-static-libgcc}
-or @code{-shared-libgcc}, will be ignored.
+or @code{-shared-libgcc}, are ignored.
The standard startup files are used normally, unless @option{-nostartfiles}
is used. The compiler may generate calls to @code{memcmp},
@code{memset}, @code{memcpy} and @code{memmove}.
@item -nostdlib
@opindex nostdlib
Do not use the standard system startup files or libraries when linking.
-No startup files and only the libraries you specify will be passed to
-the linker, options specifying linkage of the system libraries, such as
-@code{-static-libgcc} or @code{-shared-libgcc}, will be ignored.
+No startup files and only the libraries you specify are passed to
+the linker, and options specifying linkage of the system libraries, such as
+@code{-static-libgcc} or @code{-shared-libgcc}, are ignored.
+
The compiler may generate calls to @code{memcmp}, @code{memset},
@code{memcpy} and @code{memmove}.
These entries are usually resolved by entries in
other standard libraries. In other words, when you specify @option{-nostdlib}
or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
This ensures that you have no unresolved references to internal GCC
-library subroutines. (For example, @samp{__main}, used to ensure C++
-constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
+library subroutines.
+(An example of such an internal subroutine is @samp{__main}, used to ensure C++
+constructors are called; @pxref{Collect2,,@code{collect2}, gccint,
GNU Compiler Collection (GCC) Internals}.)
@item -pie
@opindex pie
Produce a position independent executable on targets that support it.
For predictable results, you must also specify the same set of options
-that were used to generate code (@option{-fpie}, @option{-fPIE},
-or model suboptions) when you specify this option.
+used for compilation (@option{-fpie}, @option{-fPIE},
+or model suboptions) when you specify this linker option.
@item -rdynamic
@opindex rdynamic
@opindex shared
Produce a shared object which can then be linked with other objects to
form an executable. Not all systems support this option. For predictable
-results, you must also specify the same set of options that were used to
-generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
-when you specify this option.@footnote{On some systems, @samp{gcc -shared}
+results, you must also specify the same set of options used for compilation
+(@option{-fpic}, @option{-fPIC}, or model suboptions) when
+you specify this linker option.@footnote{On some systems, @samp{gcc -shared}
needs to build supplementary stub code for constructors to work. On
multi-libbed systems, @samp{gcc -shared} must select the correct support
libraries to link against. Failing to supply the correct flags may lead
this is the right thing to do.
If, instead, you use the GCC driver to create shared libraries, you may
-find that they will not always be linked with the shared @file{libgcc}.
+find that they are not always linked with the shared @file{libgcc}.
If GCC finds, at its configuration time, that you have a non-GNU linker
or a GNU linker that does not support option @option{--eh-frame-hdr},
-it will link the shared version of @file{libgcc} into shared libraries
-by default. Otherwise, it will take advantage of the linker and optimize
+it links the shared version of @file{libgcc} into shared libraries
+by default. Otherwise, it takes advantage of the linker and optimizes
away the linking with the shared version of @file{libgcc}, linking with
the static version of libgcc by default. This allows exceptions to
propagate through such shared libraries, without incurring relocation
@file{libgcc}.
@item -static-libstdc++
-When the @command{g++} program is used to link a C++ program, it will
-normally automatically link against @option{libstdc++}. If
+When the @command{g++} program is used to link a C++ program, it
+normally automatically links against @option{libstdc++}. If
@file{libstdc++} is available as a shared library, and the
-@option{-static} option is not used, then this will link against the
+@option{-static} option is not used, then this links against the
shared version of @file{libstdc++}. That is normally fine. However, it
is sometimes useful to freeze the version of @file{libstdc++} used by
the program without going all the way to a fully static link. The
If a standard system include directory, or a directory specified with
@option{-isystem}, is also specified with @option{-I}, the @option{-I}
-option will be ignored. The directory will still be searched but as a
+option is ignored. The directory is still searched but as a
system directory at its normal position in the system include chain.
This is to ensure that GCC's procedure to fix buggy system headers and
the ordering for the @code{include_next} directive are not inadvertently changed.
For each subprogram to be run, the compiler driver first tries the
@option{-B} prefix, if any. If that name is not found, or if @option{-B}
-was not specified, the driver tries two standard prefixes,
+is not specified, the driver tries two standard prefixes,
@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
those results in a file name that is found, the unmodified program
name is searched for using the directories specified in your
@env{PATH} environment variable.
-The compiler will check to see if the path provided by the @option{-B}
-refers to a directory, and if necessary it will add a directory
+The compiler checks to see if the path provided by the @option{-B}
+refers to a directory, and if necessary it adds a directory
separator character at the end of the path.
@option{-B} prefixes that effectively specify directory names also apply
As a special kludge, if the path provided by @option{-B} is
@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
-9, then it will be replaced by @file{[dir/]include}. This is to help
+9, then it is replaced by @file{[dir/]include}. This is to help
with boot-strapping the compiler.
@item -specs=@var{file}
@item --sysroot=@var{dir}
@opindex sysroot
Use @var{dir} as the logical root directory for headers and libraries.
-For example, if the compiler would normally search for headers in
-@file{/usr/include} and libraries in @file{/usr/lib}, it will instead
-search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
+For example, if the compiler normally searches for headers in
+@file{/usr/include} and libraries in @file{/usr/lib}, it instead
+searches @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
If you use both this option and the @option{-isysroot} option, then
-the @option{--sysroot} option will apply to libraries, but the
-@option{-isysroot} option will apply to header files.
+the @option{--sysroot} option applies to libraries, but the
+@option{-isysroot} option applies to header files.
The GNU linker (beginning with version 2.16) has the necessary support
for this option. If your linker does not support this option, the
-header file aspect of @option{--sysroot} will still work, but the
-library aspect will not.
+header file aspect of @option{--sysroot} still works, but the
+library aspect does not.
@item -I-
@opindex I-
directory (where the current input file came from) as the first search
directory for @samp{#include "@var{file}"}. There is no way to
override this effect of @option{-I-}. With @option{-I.} you can specify
-searching the directory that was current when the compiler was
+searching the directory that is current when the compiler is
invoked. That is not exactly the same as what the preprocessor does
by default, but it is often satisfactory.
This tells the compiler to create, override or delete the named spec
string. All lines after this directive up to the next directive or
blank line are considered to be the text for the spec string. If this
-results in an empty string then the spec will be deleted. (Or, if the
-spec did not exist, then nothing will happen.) Otherwise, if the spec
-does not currently exist a new spec will be created. If the spec does
-exist then its contents will be overridden by the text of this
+results in an empty string then the spec is deleted. (Or, if the
+spec did not exist, then nothing happens.) Otherwise, if the spec
+does not currently exist a new spec is created. If the spec does
+exist then its contents are overridden by the text of this
directive, unless the first character of that text is the @samp{+}
-character, in which case the text will be appended to the spec.
+character, in which case the text is appended to the spec.
@item [@var{suffix}]:
Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
and up to the next directive or blank line are considered to make up the
spec string for the indicated suffix. When the compiler encounters an
-input file with the named suffix, it will processes the spec string in
+input file with the named suffix, it processes the spec string in
order to work out how to compile that file. For example:
@smallexample
@end table
GCC already has an extensive list of suffixes built into it.
-This directive will add an entry to the end of the list of suffixes, but
+This directive adds an entry to the end of the list of suffixes, but
since the list is searched from the end backwards, it is effectively
possible to override earlier entries using this technique.
@item %d
Marks the argument containing or following the @samp{%d} as a
-temporary file name, so that that file will be deleted if GCC exits
+temporary file name, so that that file is deleted if GCC exits
successfully. Unlike @samp{%g}, this contributes no text to the
argument.
just like ordinary text), making such attacks more likely to succeed.
@item %u@var{suffix}
-Like @samp{%g}, but generates a new temporary file name even if
-@samp{%u@var{suffix}} was already seen.
+Like @samp{%g}, but generates a new temporary file name
+each time it appears instead of once per compilation.
@item %U@var{suffix}
Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
new one if there is no such last file name. In the absence of any
@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
-would involve the generation of two distinct file names, one
+involves the generation of two distinct file names, one
for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
simply substituted with a file name chosen for the previous @samp{%u},
without regard to any appended suffix.
@item %w
Marks the argument containing or following the @samp{%w} as the
designated output file of this compilation. This puts the argument
-into the sequence of arguments that @samp{%o} will substitute later.
+into the sequence of arguments that @samp{%o} substitutes.
@item %o
Substitutes the names of all the output files, with spaces
around the @samp{%o} as well or the results are undefined.
@samp{%o} is for use in the specs for running the linker.
Input files whose names have no recognized suffix are not compiled
-at all, but they are included among the output files, so they will
-be linked.
+at all, but they are included among the output files, so they are
+linked.
@item %O
Substitutes the suffix for object files. Note that this is
because of the need for those to form complete file names. The
handling is such that @samp{%O} is treated exactly as if it had already
been substituted, except that @samp{%g, %u, and %U} do not currently
-support additional @var{suffix} characters following @samp{%O} as they would
+support additional @var{suffix} characters following @samp{%O} as they do
following, for example, @samp{.o}.
@item %p
@item %l
Process the @code{link} spec. This is the spec for computing the
-command line passed to the linker. Typically it will make use of the
+command line passed to the linker. Typically it makes use of the
@samp{%L %G %S %D and %E} sequences.
@item %D
Dump out a @option{-L} option for each directory that GCC believes might
contain startup files. If the target supports multilibs then the
-current multilib directory will be prepended to each of these paths.
+current multilib directory is prepended to each of these paths.
@item %L
Process the @code{lib} spec. This is a spec string for deciding which
-libraries should be included on the command line to the linker.
+libraries are included on the command line to the linker.
@item %G
Process the @code{libgcc} spec. This is a spec string for deciding
-which GCC support library should be included on the command line to the linker.
+which GCC support library is included on the command line to the linker.
@item %S
Process the @code{startfile} spec. This is a spec for deciding which
-object files should be the first ones passed to the linker. Typically
+object files are the first ones passed to the linker. Typically
this might be a file named @file{crt0.o}.
@item %E
Process the @code{endfile} spec. This is a spec string that specifies
-the last object files that will be passed to the linker.
+the last object files that are passed to the linker.
@item %C
Process the @code{cpp} spec. This is used to construct the arguments
@item %<@code{S}
Remove all occurrences of @code{-S} from the command line. Note---this
command is position dependent. @samp{%} commands in the spec string
-before this one will see @code{-S}, @samp{%} commands in the spec string
-after this one will not.
+before this one see @code{-S}, @samp{%} commands in the spec string
+after this one do not.
@item %:@var{function}(@var{args})
Call the named function @var{function}, passing it @var{args}.
@end table
@item %@{@code{S}@}
-Substitutes the @code{-S} switch, if that switch was given to GCC@.
-If that switch was not specified, this substitutes nothing. Note that
+Substitutes the @code{-S} switch, if that switch is given to GCC@.
+If that switch is not specified, this substitutes nothing. Note that
the leading dash is omitted when specifying this option, and it is
automatically inserted if the substitution is performed. Thus the spec
-string @samp{%@{foo@}} would match the command-line option @option{-foo}
-and would output the command-line option @option{-foo}.
+string @samp{%@{foo@}} matches the command-line option @option{-foo}
+and outputs the command-line option @option{-foo}.
@item %W@{@code{S}@}
Like %@{@code{S}@} but mark last argument supplied within as a file to be
with @code{-S}, but which also take an argument. This is used for
switches like @option{-o}, @option{-D}, @option{-I}, etc.
GCC considers @option{-o foo} as being
-one switch whose names starts with @samp{o}. %@{o*@} would substitute this
-text, including the space. Thus two arguments would be generated.
+one switch whose name starts with @samp{o}. %@{o*@} substitutes this
+text, including the space. Thus two arguments are generated.
@item %@{@code{S}*&@code{T}*@}
Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
@item %@{@code{S}:@code{X}@}
-Substitutes @code{X}, if the @option{-S} switch was given to GCC@.
+Substitutes @code{X}, if the @option{-S} switch is given to GCC@.
@item %@{!@code{S}:@code{X}@}
-Substitutes @code{X}, if the @option{-S} switch was @emph{not} given to GCC@.
+Substitutes @code{X}, if the @option{-S} switch is @emph{not} given to GCC@.
@item %@{@code{S}*:@code{X}@}
Substitutes @code{X} if one or more switches whose names start with
@code{-S} are specified to GCC@. Normally @code{X} is substituted only
once, no matter how many such switches appeared. However, if @code{%*}
-appears somewhere in @code{X}, then @code{X} will be substituted once
+appears somewhere in @code{X}, then @code{X} is substituted once
for each matching switch, with the @code{%*} replaced by the part of
-that switch that matched the @code{*}.
+that switch matching the @code{*}.
@item %@{.@code{S}:@code{X}@}
Substitutes @code{X}, if processing a file with suffix @code{S}.
Substitutes @code{X}, if not processing a file for language @code{S}.
@item %@{@code{S}|@code{P}:@code{X}@}
-Substitutes @code{X} if either @code{-S} or @code{-P} was given to
+Substitutes @code{X} if either @code{-S} or @code{-P} is given to
GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and
@code{*} sequences as well, although they have a stronger binding than
the @samp{|}. If @code{%*} appears in @code{X}, all of the
%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
@end smallexample
-will output the following command-line options from the following input
+@noindent
+outputs the following command-line options from the following input
command-line options:
@smallexample
@item %@{S:X; T:Y; :D@}
-If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
+If @code{S} is given to GCC, substitutes @code{X}; else if @code{T} is
given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
be as many clauses as you need. This may be combined with @code{.},
@code{,}, @code{!}, @code{|}, and @code{*} as needed.
Values other than @samp{8} or @samp{16} are untested and unlikely to work.
Note also that this option changes the ABI, compiling a program with a
different stack offset than the libraries have been compiled with
-will generally not work.
+generally does not work.
This option can be useful if you want to evaluate if a different stack
offset would give you better code, but to actually use a different stack
offset to build working programs, it is recommended to configure the
The maximum alignment for SIMD vector mode types.
@var{num} may be 4 or 8. The default is 8.
Note that this is an ABI change, even though many library function
-interfaces will be unaffected, if they don't use SIMD vector modes
-in places where they affect size and/or alignment of relevant types.
+interfaces are unaffected if they don't use SIMD vector modes
+in places that affect size and/or alignment of relevant types.
@item -msplit-vecmove-early
@opindex msplit-vecmove-early
Split vector moves into single word moves before reload. In theory this
-could give better register allocation, but so far the reverse seems to be
+can give better register allocation, but so far the reverse seems to be
generally the case.
@item -m1reg-@var{reg}
Generate a stack frame that is compliant with the ARM Procedure Call
Standard for all functions, even if this is not strictly necessary for
correct execution of the code. Specifying @option{-fomit-frame-pointer}
-with this option will cause the stack frames not to be generated for
+with this option causes the stack frames not to be generated for
leaf functions. The default is @option{-mno-apcs-frame}.
@item -mapcs
Generate code to check the amount of stack space available upon entry to
every function (that actually uses some stack space). If there is
insufficient space available then either the function
-@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
+@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} is
called, depending upon the amount of stack space required. The runtime
system is required to provide these functions. The default is
@option{-mno-apcs-stack-check}, since this produces smaller code.
@opindex mno-sched-prolog
Prevent the reordering of instructions in the function prologue, or the
merging of those instruction with the instructions in the function's
-body. This means that all functions will start with a recognizable set
+body. This means that all functions start with a recognizable set
of instructions (or in fact one of a choice from a small set of
different function prologues), and this information can be used to
-locate the start if functions inside an executable piece of code. The
+locate the start of functions inside an executable piece of code. The
default is @option{-msched-prolog}.
@item -mfloat-abi=@var{name}
instead of specifying the actual target processor type, and hence
restricting which instructions can be used, it specifies that GCC should
tune the performance of the code as if the target were of the type
-specified in this option, but still choosing the instructions that it
-will generate based on the CPU specified by a @option{-mcpu=} option.
+specified in this option, but still choosing the instructions it
+generates based on the CPU specified by a @option{-mcpu=} option.
For some ARM implementations better performance can be obtained by using
this option.
If the selected floating-point hardware includes the NEON extension
(e.g. @option{-mfpu}=@samp{neon}), note that floating-point
-operations will not be used by GCC's auto-vectorization pass unless
+operations are not generated by GCC's auto-vectorization pass unless
@option{-funsafe-math-optimizations} is also specified. This is
because NEON hardware does not fully implement the IEEE 754 standard for
floating-point arithmetic (in particular denormal values are treated as
@item -mstructure-size-boundary=@var{n}
@opindex mstructure-size-boundary
-The size of all structures and unions will be rounded up to a multiple
+The sizes of all structures and unions are rounded up to a multiple
of the number of bits set by this option. Permissible values are 8, 32
and 64. The default value varies for different toolchains. For the COFF
targeted toolchain the default value is 8. A value of 64 is only allowed
@item -mabort-on-noreturn
@opindex mabort-on-noreturn
Generate a call to the function @code{abort} at the end of a
-@code{noreturn} function. It will be executed if the function tries to
+@code{noreturn} function. It is executed if the function tries to
return.
@item -mlong-calls
Tells the compiler to perform function calls by first loading the
address of the function into a register and then performing a subroutine
call on this register. This switch is needed if the target function
-will lie outside of the 64 megabyte addressing range of the offset based
+lies outside of the 64-megabyte addressing range of the offset-based
version of subroutine call instruction.
-Even if this switch is enabled, not all function calls will be turned
+Even if this switch is enabled, not all function calls are turned
into long calls. The heuristic is that static functions, functions
that have the @samp{short-call} attribute, functions that are inside
-the scope of a @samp{#pragma no_long_calls} directive and functions whose
+the scope of a @samp{#pragma no_long_calls} directive, and functions whose
definitions have already been compiled within the current compilation
-unit, will not be turned into long calls. The exception to this rule is
+unit are not turned into long calls. The exceptions to this rule are
that weak function definitions, functions with the @samp{long-call}
attribute or the @samp{section} attribute, and functions that are within
-the scope of a @samp{#pragma long_calls} directive, will always be
+the scope of a @samp{#pragma long_calls} directive are always
turned into long calls.
This feature is not enabled by default. Specifying
-@option{-mno-long-calls} will restore the default behavior, as will
+@option{-mno-long-calls} restores the default behavior, as does
placing the function calls within the scope of a @samp{#pragma
long_calls_off} directive. Note these switches have no effect on how
the compiler generates code to handle function calls via function
@item -mcall-prologues
@opindex mcall-prologues
-Functions prologues/epilogues expanded as call to appropriate
-subroutines. Code size will be smaller.
+Functions prologues/epilogues are expanded as calls to appropriate
+subroutines. Code size is smaller.
@item -mint8
@opindex mint8
@item -mno-interrupts
@opindex mno-interrupts
Generated code is not compatible with hardware interrupts.
-Code size will be smaller.
+Code size is smaller.
@item -mrelax
@opindex mrelax
Jump relaxing is performed by the linker because jump offsets are not
known before code is located. Therefore, the assembler code generated by the
-compiler will be the same, but the instructions in the executable may
+compiler is the same, but the instructions in the executable may
differ from instructions in the assembler code.
@item -mshort-calls
@item -mstrict-X
@opindex mstrict-X
Use address register @code{X} in a way proposed by the hardware. This means
-that @code{X} will only be used in indirect, post-increment or
+that @code{X} is only used in indirect, post-increment or
pre-decrement addressing.
Without this option, the @code{X} register may be used in the same way
as @code{Y} or @code{Z} which then is emulated by additional
instructions.
For example, loading a value with @code{X+const} addressing with a
-small non-negative @code{const < 64} to a register @var{Rn} will be
+small non-negative @code{const < 64} to a register @var{Rn} is
performed as
@example
prologue/epilogue.
@item
-For indirect calls to functions and computed goto, the linker will
-generate @emph{stubs}. Stubs are jump pads sometimes also called
-@emph{trampolines}. Thus, the indirect call/jump will jump to such a stub.
+For indirect calls to functions and computed goto, the linker
+generates @emph{stubs}. Stubs are jump pads sometimes also called
+@emph{trampolines}. Thus, the indirect call/jump jumps to such a stub.
The stub contains a direct jump to the desired address.
@item
The @code{__trampolines_start} symbol is defined in the linker script.
@item
-Stubs will be generated automatically by the linker if
+Stubs are generated automatically by the linker if
the following two conditions are met:
@itemize @minus
@end itemize
@item
-The compiler will emit such @code{gs} modifiers for code labels in the
+The compiler emits such @code{gs} modifiers for code labels in the
following situations:
@itemize @minus
@item Taking address of a function or code label.
@item
If a @ref{AVR Named Address Spaces,named address space} other than
-generic or @code{__flash} is used, then @code{RAMPZ} will be set
+generic or @code{__flash} is used, then @code{RAMPZ} is set
as needed before the operation.
@item
If the device supports RAM larger than 64@tie{KiB} and the compiler
needs to change @code{RAMPZ} to accomplish an operation, @code{RAMPZ}
-will be reset to zero after the operation.
+is reset to zero after the operation.
@item
If the device comes with a specific @code{RAMP} register, the ISR
-prologue/epilogue will save/restore that SFR and initialize it with
+prologue/epilogue saves/restores that SFR and initializes it with
zero in case the ISR code might (implicitly) use it.
@item
@item __AVR_@var{Device}__
Setting @code{-mmcu=@var{device}} defines this built-in macro which reflects
-the device's name. For example, @code{-mmcu=atmega8} will define the
+the device's name. For example, @code{-mmcu=atmega8} defines the
built-in macro @code{__AVR_ATmega8__}, @code{-mmcu=attiny261a} defines
@code{__AVR_ATtiny261A__}, etc.
@samp{bf561}, @samp{bf592}.
The optional @var{sirevision} specifies the silicon revision of the target
Blackfin processor. Any workarounds available for the targeted silicon revision
-will be enabled. If @var{sirevision} is @samp{none}, no workarounds are enabled.
+are enabled. If @var{sirevision} is @samp{none}, no workarounds are enabled.
If @var{sirevision} is @samp{any}, all workarounds for the targeted processor
-will be enabled. The @code{__SILICON_REVISION__} macro is defined to two
+are enabled. The @code{__SILICON_REVISION__} macro is defined to two
hexadecimal digits representing the major and minor numbers in the silicon
revision. If @var{sirevision} is @samp{none}, the @code{__SILICON_REVISION__}
is not defined. If @var{sirevision} is @samp{any}, the
@item -mspecld-anomaly
@opindex mspecld-anomaly
-When enabled, the compiler will ensure that the generated code does not
+When enabled, the compiler ensures that the generated code does not
contain speculative loads after jump instructions. If this option is used,
@code{__WORKAROUND_SPECULATIVE_LOADS} is defined.
@item -mcsync-anomaly
@opindex mcsync-anomaly
-When enabled, the compiler will ensure that the generated code does not
+When enabled, the compiler ensures that the generated code does not
contain CSYNC or SSYNC instructions too soon after conditional branches.
If this option is used, @code{__WORKAROUND_SPECULATIVE_SYNCS} is defined.
@item -mno-leaf-id-shared-library
@opindex mno-leaf-id-shared-library
Do not assume that the code being compiled won't link against any ID shared
-libraries. Slower code will be generated for jump and call insns.
+libraries. Slower code is generated for jump and call insns.
@item -mshared-library-id=n
@opindex mshared-library-id
-Specified the identification number of the ID based shared library being
-compiled. Specifying a value of 0 will generate more compact code, specifying
-other values will force the allocation of that number to the current
-library but is no more space or time efficient than omitting this option.
+Specifies the identification number of the ID-based shared library being
+compiled. Specifying a value of 0 generates more compact code; specifying
+other values forces the allocation of that number to the current
+library but is no more space- or time-efficient than omitting this option.
@item -msep-data
@opindex msep-data
version of subroutine call instruction.
This feature is not enabled by default. Specifying
-@option{-mno-long-calls} will restore the default behavior. Note these
+@option{-mno-long-calls} restores the default behavior. Note these
switches have no effect on how the compiler generates code to handle
function calls via function pointers.
@item -mmulticore
@opindex mmulticore
Build standalone application for multicore Blackfin processor. Proper
-start files and link scripts will be used to support multicore.
+start files and link scripts are used to support multicore.
This option defines @code{__BFIN_MULTICORE}. It can only be used with
@option{-mcpu=bf561@r{[}-@var{sirevision}@r{]}}. It can be used with
@option{-mcorea} or @option{-mcoreb}. If it's used without
@opindex mcorea
Build standalone application for Core A of BF561 when using
one application per core programming model. Proper start files
-and link scripts will be used to support Core A. This option
+and link scripts are used to support Core A. This option
defines @code{__BFIN_COREA}. It must be used with @option{-mmulticore}.
@item -mcoreb
@opindex mcoreb
Build standalone application for Core B of BF561 when using
one application per core programming model. Proper start files
-and link scripts will be used to support Core B. This option
+and link scripts are used to support Core B. This option
defines @code{__BFIN_COREB}. When this option is used, coreb_main
should be used instead of main. It must be used with
@option{-mmulticore}.
@item -msdram
@opindex msdram
Build standalone application for SDRAM. Proper start files and
-link scripts will be used to put the application into SDRAM.
+link scripts are used to put the application into SDRAM.
Loader should initialize SDRAM before loading the application
into SDRAM. This option defines @code{__BFIN_SDRAM}.
These options are defined for all architectures running the Darwin operating
system.
-FSF GCC on Darwin does not create ``fat'' object files; it will create
-an object file for the single architecture that it was built to
+FSF GCC on Darwin does not create ``fat'' object files; it creates
+an object file for the single architecture that GCC was built to
target. Apple's GCC on Darwin does create ``fat'' files if multiple
@option{-arch} options are used; it does so by running the compiler or
linker multiple times and joining the results together with
@option{-force_cpusubtype_ALL} option can be used to override this.
The Darwin tools vary in their behavior when presented with an ISA
-mismatch. The assembler, @file{as}, will only permit instructions to
+mismatch. The assembler, @file{as}, only permits instructions to
be used that are valid for the subtype of the file it is generating,
so you cannot put 64-bit instructions in a @samp{ppc750} object file.
-The linker for shared libraries, @file{/usr/bin/libtool}, will fail
-and print an error if asked to create a shared library with a less
+The linker for shared libraries, @file{/usr/bin/libtool}, fails
+and prints an error if asked to create a shared library with a less
restrictive subtype than its input files (for instance, trying to put
a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
-for executables, @command{ld}, will quietly give the executable the most
+for executables, @command{ld}, quietly gives the executable the most
restrictive subtype of any of its input files.
@table @gcctabopt
framework that contains the subframework, or in a sibling subframework
header. Two subframeworks are siblings if they occur in the same
framework. A subframework should not have the same name as a
-framework, a warning will be issued if this is violated. Currently a
-subframework cannot have subframeworks, in the future, the mechanism
+framework; a warning is issued if this is violated. Currently a
+subframework cannot have subframeworks; in the future, the mechanism
may be extended to support this. The standard frameworks can be found
in @file{/System/Library/Frameworks} and
@file{/Library/Frameworks}. An example include looks like
@item -bundle_loader @var{executable}
@opindex bundle_loader
-This option specifies the @var{executable} that will be loading the build
+This option specifies the @var{executable} that will load the build
output file being linked. See man ld(1) for more information.
@item -dynamiclib
@opindex dynamiclib
-When passed this option, GCC will produce a dynamic library instead of
+When passed this option, GCC produces a dynamic library instead of
an executable when linking, using the Darwin @file{libtool} command.
@item -force_cpusubtype_ALL
@opindex msoft-float
Use (do not use) the hardware floating-point instructions for
floating-point operations. When @option{-msoft-float} is specified,
-functions in @file{libgcc.a} will be used to perform floating-point
+functions in @file{libgcc.a} are used to perform floating-point
operations. Unless they are replaced by routines that emulate the
floating-point operations, or compiled in such a way as to call such
-emulations routines, these routines will issue floating-point
+emulations routines, these routines issue floating-point
operations. If you are compiling for an Alpha without floating-point
operations, you must ensure that the library is built so as not to call
them.
@opindex mbuild-constants
Normally GCC examines a 32- or 64-bit integer constant to
see if it can construct it from smaller constants in two or three
-instructions. If it cannot, it will output the constant as a literal and
-generate code to load it from the data segment at run time.
+instructions. If it cannot, it outputs the constant as a literal and
+generates code to load it from the data segment at run time.
Use this option to require GCC to construct @emph{all} integer constants
using code, even if it takes more instructions (the maximum is six).
-You would typically use this option to build a shared library dynamic
+You typically use this option to build a shared library dynamic
loader. Itself a shared library, it must relocate itself in memory
before it can find the variables and constants in its own data segment.
Indicate whether GCC should generate code to use the optional BWX,
CIX, FIX and MAX instruction sets. The default is to use the instruction
sets supported by the CPU type specified via @option{-mcpu=} option or that
-of the CPU on which GCC was built if none was specified.
+of the CPU on which GCC was built if none is specified.
@item -mfloat-vax
@itemx -mfloat-ieee
Set the instruction set and instruction scheduling parameters for
machine type @var{cpu_type}. You can specify either the @samp{EV}
style name or the corresponding chip number. GCC supports scheduling
-parameters for the EV4, EV5 and EV6 family of processors and will
-choose the default values for the instruction set from the processor
-you specify. If you do not specify a processor type, GCC will default
+parameters for the EV4, EV5 and EV6 family of processors and
+chooses the default values for the instruction set from the processor
+you specify. If you do not specify a processor type, GCC defaults
to the processor on which the compiler was built.
Supported values for @var{cpu_type} are
@item -msmall-model
@opindex msmall-model
Use the small address space model. This can produce smaller code, but
-it does assume that all symbolic values and addresses will fit into a
+it does assume that all symbolic values and addresses fit into a
20-bit range.
@item -mno-lsim
1.1, and @samp{2.0} for PA 2.0 processors. Refer to
@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
architecture option for your machine. Code compiled for lower numbered
-architectures will run on higher numbered architectures, but not the
+architectures runs on higher numbered architectures, but not the
other way around.
@item -mpa-risc-1-0
Generate code that assumes calls never cross space boundaries. This
allows GCC to emit code that performs faster indirect calls.
-This option will not work in the presence of shared libraries or nested
+This option does not work in the presence of shared libraries or nested
functions.
@item -mfixed-range=@var{register-range}
and @option{-mno-portable-runtime} options together under HP-UX with
the SOM linker.
-It is normally not desirable to use this option as it will degrade
+It is normally not desirable to use this option as it degrades
performance. However, it may be useful in large applications,
particularly when partial linking is used to build the application.
@item -memregs=@var{number}
@opindex memregs=
-Specifies the number of memory-based pseudo-registers GCC will use
-during code generation. These pseudo-registers will be used like real
+Specifies the number of memory-based pseudo-registers GCC uses
+during code generation. These pseudo-registers are used like real
registers, so there is a tradeoff between GCC's ability to fit the
code into available registers, and the performance penalty of using
memory instead of registers. Note that all modules in a program must
@item -mmodel=medium
@opindex mmodel=medium
Assume objects may be anywhere in the 32-bit address space (the compiler
-will generate @code{seth/add3} instructions to load their addresses), and
+generates @code{seth/add3} instructions to load their addresses), and
assume all subroutines are reachable with the @code{bl} instruction.
@item -mmodel=large
@opindex mmodel=large
Assume objects may be anywhere in the 32-bit address space (the compiler
-will generate @code{seth/add3} instructions to load their addresses), and
+generates @code{seth/add3} instructions to load their addresses), and
assume subroutines may not be reachable with the @code{bl} instruction
-(the compiler will generate the much slower @code{seth/add3/jl}
+(the compiler generates the much slower @code{seth/add3/jl}
instruction sequence).
@item -msdata=none
@opindex msdata=none
-Disable use of the small data area. Variables will be put into
-one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
+Disable use of the small data area. Variables are put into
+one of @samp{.data}, @samp{.bss}, or @samp{.rodata} (unless the
@code{section} attribute has been specified).
This is the default.
All modules should be compiled with the same @option{-G @var{num}} value.
Compiling with different values of @var{num} may or may not work; if it
-doesn't the linker will give an error message---incorrect code will not be
+doesn't the linker gives an error message---incorrect code is not
generated.
@item -mdebug
@item -mbranch-cost=@var{number}
@opindex mbranch-cost=@var{number}
-@var{number} can only be 1 or 2. If it is 1 then branches will be
-preferred over conditional code, if it is 2, then the opposite will
-apply.
+@var{number} can only be 1 or 2. If it is 1 then branches are
+preferred over conditional code, if it is 2, then the opposite applies.
@item -mflush-trap=@var{number}
@opindex mflush-trap=@var{number}
@opindex mflush-func=@var{name}
Specifies the name of the operating system function to call to flush
the cache. The default is @emph{_flush_cache}, but a function call
-will only be used if a trap is not available.
+is only used if a trap is not available.
@item -mno-flush-func
@opindex mno-flush-func
Also, you must provide function prototypes for all functions that
take variable numbers of arguments (including @code{printf});
-otherwise incorrect code will be generated for calls to those
+otherwise incorrect code is generated for calls to those
functions.
-In addition, seriously incorrect code will result if you call a
+In addition, seriously incorrect code results if you call a
function with too many arguments. (Normally, extra arguments are
harmlessly ignored.)
Aligning variables on 32-bit boundaries produces code that runs somewhat
faster on processors with 32-bit busses at the expense of more memory.
-@strong{Warning:} if you use the @option{-malign-int} switch, GCC will
-align structures containing the above types differently than
+@strong{Warning:} if you use the @option{-malign-int} switch, GCC
+aligns structures containing the above types differently than
most published application binary interface specifications for the m68k.
@item -mpcrel
@itemx -mstrict-align
@opindex mno-strict-align
@opindex mstrict-align
-Do not (do) assume that unaligned memory references will be handled by
+Do not (do) assume that unaligned memory references are handled by
the system.
@item -msep-data
This is the default.
@item -mshared-library-id=n
-Specified the identification number of the ID based shared library being
-compiled. Specifying a value of 0 will generate more compact code, specifying
-other values will force the allocation of that number to the current
-library but is no more space or time efficient than omitting this option.
+Specifies the identification number of the ID-based shared library being
+compiled. Specifying a value of 0 generates more compact code; specifying
+other values forces the allocation of that number to the current
+library, but is no more space- or time-efficient than omitting this option.
@item -mxgot
@itemx -mno-xgot
@item -mbased=@var{n}
@opindex mbased=
-Variables of size @var{n} bytes or smaller will be placed in the
+Variables of size @var{n} bytes or smaller are placed in the
@code{.based} section by default. Based variables use the @code{$tp}
register as a base register, and there is a 128-byte limit to the
@code{.based} section.
@item -mc=@var{name}
@opindex mc=
-Selects which section constant data will be placed in. @var{name} may
+Selects which section constant data is placed in. @var{name} may
be @code{tiny}, @code{near}, or @code{far}.
@item -mclip
@item -mtiny=@var{n}
@opindex mtiny=
-Variables that are @var{n} bytes or smaller will be allocated to the
+Variables that are @var{n} bytes or smaller are allocated to the
@code{.tiny} section. These variables use the @code{$gp} base
register. The default for this option is 4, but note that there's a
65536-byte limit to the @code{.tiny} section.
@item -march=@var{arch}
@opindex march
-Generate code that will run on @var{arch}, which can be the name of a
+Generate code that runs on @var{arch}, which can be the name of a
generic MIPS ISA, or the name of a particular processor.
The ISA names are:
@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
-For example, @option{-march=r2000} will set @samp{_MIPS_ARCH}
-to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
+For example, @option{-march=r2000} sets @samp{_MIPS_ARCH}
+to @samp{"r2000"} and defines the macro @samp{_MIPS_ARCH_R2000}.
Note that the @samp{_MIPS_ARCH} macro uses the processor names given
-above. In other words, it will have the full prefix and will not
+above. In other words, it has the full prefix and does not
abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
the macro names the resolved architecture (either @samp{"mips1"} or
@samp{"mips3"}). It names the default architecture when no
operations. The list of @var{arch} values is the same as for
@option{-march}.
-When this option is not used, GCC will optimize for the processor
+When this option is not used, GCC optimizes for the processor
specified by @option{-march}. By using @option{-march} and
-@option{-mtune} together, it is possible to generate code that will
-run on a family of processors, but optimize the code for one
+@option{-mtune} together, it is possible to generate code that
+runs on a family of processors, but optimize the code for one
particular member of that family.
@option{-mtune} defines the macros @samp{_MIPS_TUNE} and
@opindex mips16
@opindex mno-mips16
Generate (do not generate) MIPS16 code. If GCC is targetting a
-MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
+MIPS32 or MIPS64 architecture, it makes use of the MIPS16e ASE@.
MIPS16 code generation can also be controlled on a per-function basis
by means of @code{mips16} and @code{nomips16} attributes.
@option{-mno-shared} depends on binutils 2.16 or higher and generates
objects that can only be linked by the GNU linker. However, the option
does not affect the ABI of the final executable; it only affects the ABI
-of relocatable objects. Using @option{-mno-shared} will generally make
+of relocatable objects. Using @option{-mno-shared} generally makes
executables both smaller and quicker.
@option{-mshared} is the default.
offset table.
GCC normally uses a single instruction to load values from the GOT@.
-While this is relatively efficient, it will only work if the GOT
-is smaller than about 64k. Anything larger will cause the linker
+While this is relatively efficient, it only works if the GOT
+is smaller than about 64k. Anything larger causes the linker
to report an error such as:
@cindex relocation truncated to fit (MIPS)
@end smallexample
If this happens, you should recompile your code with @option{-mxgot}.
-It should then work with very large GOTs, although it will also be
-less efficient, since it will take three instructions to fetch the
+This works with very large GOTs, although the code is also
+less efficient, since it takes three instructions to fetch the
value of a global symbol.
Note that some linkers can create multiple GOTs. If you have such a
@opindex mno-llsc
Use (do not use) @samp{ll}, @samp{sc}, and @samp{sync} instructions to
implement atomic memory built-in functions. When neither option is
-specified, GCC will use the instructions if the target architecture
+specified, GCC uses the instructions if the target architecture
supports them.
@option{-mllsc} is useful if the runtime environment can emulate the
@itemx -mno-extern-sdata
@opindex mextern-sdata
@opindex mno-extern-sdata
-Assume (do not assume) that externally-defined data will be in
-a small data section if that data is within the @option{-G} limit.
+Assume (do not assume) that externally-defined data is in
+a small data section if the size of that data is within the @option{-G} limit.
@option{-mextern-sdata} is the default for all configurations.
If you compile a module @var{Mod} with @option{-mextern-sdata} @option{-G
@option{-mno-gpopt} is useful for cases where the @code{$gp} register
might not hold the value of @code{_gp}. For example, if the code is
part of a library that might be used in a boot monitor, programs that
-call boot monitor routines will pass an unknown value in @code{$gp}.
-(In such situations, the boot monitor itself would usually be compiled
+call boot monitor routines pass an unknown value in @code{$gp}.
+(In such situations, the boot monitor itself is usually compiled
with @option{-G0}.)
@option{-mno-gpopt} implies @option{-mno-local-sdata} and
@opindex mfix-vr4130
Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
workarounds are implemented by the assembler rather than by GCC,
-although GCC will avoid using @code{mflo} and @code{mfhi} if the
+although GCC avoids using @code{mflo} and @code{mfhi} if the
VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
instructions are available instead.
In common with many processors, the R10K tries to predict the outcome
of a conditional branch and speculatively executes instructions from
the ``taken'' branch. It later aborts these instructions if the
-predicted outcome was wrong. However, on the R10K, even aborted
+predicted outcome is wrong. However, on the R10K, even aborted
instructions can have side effects.
This problem only affects kernel stores and, depending on the system,
the target memory into cache and mark the cache line as dirty, even if
the store itself is later aborted. If a DMA operation writes to the
same area of memory before the ``dirty'' line is flushed, the cached
-data will overwrite the DMA-ed data. See the R10K processor manual
+data overwrites the DMA-ed data. See the R10K processor manual
for a full description, including other potential problems.
One workaround is to insert cache barrier instructions before every memory
access that might be speculatively executed and that might have side
effects even if aborted. @option{-mr10k-cache-barrier=@var{setting}}
controls GCC's implementation of this workaround. It assumes that
-aborted accesses to any byte in the following regions will not have
+aborted accesses to any byte in the following regions does not have
side effects:
@enumerate
instructions may be generated if they are supported by the selected
architecture. An exception is for the MIPS32 and MIPS64 architectures
and processors that implement those architectures; for those, Branch
-Likely instructions will not be generated by default because the MIPS32
+Likely instructions are not be generated by default because the MIPS32
and MIPS64 architectures specifically deprecate their use.
@item -mfp-exceptions
@itemx -mno-fp-exceptions
@opindex mfp-exceptions
-Specifies whether FP exceptions are enabled. This affects how we schedule
-FP instructions for some processors. The default is that FP exceptions are
+Specifies whether FP exceptions are enabled. This affects how
+FP instructions are scheduled for some processors.
+The default is that FP exceptions are
enabled.
For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
@opindex mvr4130-align
The VR4130 pipeline is two-way superscalar, but can only issue two
instructions together if the first one is 8-byte aligned. When this
-option is enabled, GCC will align pairs of instructions that it
+option is enabled, GCC aligns pairs of instructions that it
thinks should execute in parallel.
This option only has an effect when optimizing for the VR4130.
@opindex msynci
Enable (disable) generation of @code{synci} instructions on
architectures that support it. The @code{synci} instructions (if
-enabled) will be generated when @code{__builtin___clear_cache()} is
+enabled) are generated when @code{__builtin___clear_cache()} is
compiled.
This option defaults to @code{-mno-synci}, but the default can be
When compiling code for single processor systems, it is generally safe
to use @code{synci}. However, on many multi-core (SMP) systems, it
-will not invalidate the instruction caches on all cores and may lead
+does not invalidate the instruction caches on all cores and may lead
to undefined behavior.
@item -mrelax-pic-calls
@opindex mreturn-pointer-on-d0
When generating a function that returns a pointer, return the pointer
in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
-only in a0, and attempts to call such functions without a prototype
-would result in errors. Note that this option is on by default; use
+only in @code{a0}, and attempts to call such functions without a prototype
+result in errors. Note that this option is on by default; use
@option{-mno-return-pointer-on-d0} to disable it.
@item -mno-crt0
for @var{ae_type} are @samp{ANY}, @samp{MUL}, and @samp{MAC}.
@option{-mae=ANY} selects a completely generic AE type. Code
-generated with this option will run on any of the other AE types. The
-code will not be as efficient as it would be if compiled for a specific
-AE type, and some types of operation (e.g., multiplication) will not
+generated with this option runs on any of the other AE types. The
+code is not as efficient as it would be if compiled for a specific
+AE type, and some types of operation (e.g., multiplication) do not
work properly on all types of AE.
@option{-mae=MUL} selects a MUL AE type. This is the most useful AE type
@item -msymbol-as-address
Enable the compiler to directly use a symbol name as an address in a
load/store instruction, without first loading it into a
-register. Typically, the use of this option will generate larger
+register. Typically, the use of this option generates larger
programs, which run faster than when the option isn't used. However, the
results vary from program to program, so it is left as a user option,
rather than being permanently enabled.
performs byte-level memory operations on the MAC AE type. The MAC AE has
no hardware support for byte-level memory operations, so all byte
load/stores must be synthesized from word load/store operations. This is
-inefficient and a warning will be generated indicating to the programmer
-that they should rewrite the code to avoid byte operations, or to target
-an AE type that has the necessary hardware support. This option enables
-the warning to be turned off.
+inefficient and a warning is generated to indicate
+that you should rewrite the code to avoid byte operations, or to target
+an AE type that has the necessary hardware support. This option disables
+these warnings.
@end table
@option{-mno-powerpc64}.
If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
-will use only the instructions in the common subset of both
-architectures plus some special AIX common-mode calls, and will not use
+uses only the instructions in the common subset of both
+architectures plus some special AIX common-mode calls, and does not use
the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
permits GCC to use any instruction from either architecture and to
allow use of the MQ register; specify this for the Motorola MPC601.
@samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
@option{-mcpu=common} selects a completely generic processor. Code
-generated under this option will run on any POWER or PowerPC processor.
-GCC will use only the instructions in the common subset of both
-architectures, and will not use the MQ register. GCC assumes a generic
+generated under this option runs on any POWER or PowerPC processor.
+GCC uses only the instructions in the common subset of both
+architectures, and does not use the MQ register. GCC assumes a generic
processor model for scheduling purposes.
@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
scheduling purposes.
The other options specify a specific processor. Code generated under
-those options will run best on that processor, and may not run at all on
+those options runs best on that processor, and may not run at all on
others.
The @option{-mcpu} options automatically enable or disable the
-mpowerpc-gpopt -mpowerpc-gfxopt -msingle-float -mdouble-float @gol
-msimple-fpu -mstring -mmulhw -mdlmzb -mmfpgpr -mvsx}
-The particular options set for any particular CPU will vary between
+The particular options set for any particular CPU varies between
compiler versions, depending on what setting seems to produce optimal
code for that CPU; it doesn't necessarily reflect the actual hardware's
capabilities. If you wish to set an individual option to a particular
@opindex mtune
Set the instruction scheduling parameters for machine type
@var{cpu_type}, but do not set the architecture type, register usage, or
-choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
+choice of mnemonics, as @option{-mcpu=@var{cpu_type}} does. The same
values for @var{cpu_type} are used for @option{-mtune} as for
-@option{-mcpu}. If both are specified, the code generated will use the
+@option{-mcpu}. If both are specified, the code generated uses the
architecture, registers, and mnemonics set by @option{-mcpu}, but the
scheduling parameters set by @option{-mtune}.
@opindex mminimal-toc
Modify generation of the TOC (Table Of Contents), which is created for
every executable file. The @option{-mfull-toc} option is selected by
-default. In that case, GCC will allocate at least one TOC entry for
+default. In that case, GCC allocates at least one TOC entry for
each unique non-automatic variable reference in your program. GCC
-will also place floating-point constants in the TOC@. However, only
+also places floating-point constants in the TOC@. However, only
16,384 entries are available in the TOC@.
If you receive a linker error message that saying you have overflowed
If you still run out of space in the TOC even when you specify both of
these options, specify @option{-mminimal-toc} instead. This option causes
GCC to make only one TOC entry for every file. When you specify this
-option, GCC will produce code that is slower and larger but which
+option, GCC produces code that is slower and larger but which
uses extremely little TOC space. You may wish to use this option
-only on files that contain less frequently executed code.
+only on files that contain less frequently-executed code.
@item -maix64
@itemx -maix32
@opindex mno-strict-align
@opindex mstrict-align
On System V.4 and embedded PowerPC systems do not (do) assume that
-unaligned memory references will be handled by the system.
+unaligned memory references are handled by the system.
@item -mrelocatable
@itemx -mno-relocatable
@item -minsert-sched-nops=@var{scheme}
@opindex minsert-sched-nops
-This option controls which NOP insertion scheme will be used during
+This option controls which NOP insertion scheme is used during
the second scheduling pass. The argument @var{scheme} takes one of the
following values:
variable argument functions are properly prototyped. Otherwise, the
compiler must insert an instruction before every non prototyped call to
set or clear bit 6 of the condition code register (@var{CR}) to
-indicate whether floating-point values were passed in the floating-point
+indicate whether floating-point values are passed in the floating-point
registers in case the function takes variable arguments. With
@option{-mprototype}, only calls to prototyped variable argument functions
-will set or clear the bit.
+set or clear the bit.
@item -msim
@opindex msim
@code{r13} to point to two separate small data areas. Selecting
@option{-mno-eabi} means that the stack is aligned to a 16-byte boundary,
do not call an initialization function from @code{main}, and the
-@option{-msdata} option will only use @code{r13} to point to a single
+@option{-msdata} option only uses @code{r13} to point to a single
small data area. The @option{-meabi} option is on by default if you
configured GCC using one of the @samp{powerpc*-*-eabi*} options.
By default assume that all calls are far away so that a longer more
expensive calling sequence is required. This is required for calls
further than 32 megabytes (33,554,432 bytes) from the current location.
-A short call will be generated if the compiler knows
+A short call is generated if the compiler knows
the call cannot be that far away. This setting can be overridden by
the @code{shortcall} function attribute, or by @code{#pragma
longcall(0)}.
as can the GNU linker for PowerPC/64. It is planned to add this feature
to the GNU linker for 32-bit PowerPC systems as well.
-On Darwin/PPC systems, @code{#pragma longcall} will generate @code{jbsr
+On Darwin/PPC systems, @code{#pragma longcall} generates @code{jbsr
callee, L42}, plus a @dfn{branch island} (glue code). The two target
addresses represent the callee and the branch island. The
-Darwin/PPC linker will prefer the first address and generate a @code{bl
-callee} if the PPC @code{bl} instruction will reach the callee directly;
-otherwise, the linker will generate @code{bl L42} to call the branch
+Darwin/PPC linker prefers the first address and generates a @code{bl
+callee} if the PPC @code{bl} instruction reaches the callee directly;
+otherwise, the linker generates @code{bl L42} to call the branch
island. The branch island is appended to the body of the
calling function; it computes the full 32-bit address of the callee
and jumps to it.
the glue for every direct call, and the Darwin linker decides whether
to use or discard it.
-In the future, we may cause GCC to ignore all longcall specifications
+In the future, GCC may ignore all longcall specifications
when the linker is known to generate glue.
@item -mtls-markers
@item -mrecip
@itemx -mno-recip
@opindex mrecip
-This option will enable GCC to use the reciprocal estimate and
+This option enables use of the reciprocal estimate and
reciprocal square root estimate instructions with additional
Newton-Raphson steps to increase precision instead of doing a divide or
square root and divide for floating-point arguments. You should use
@code{rsqrtf}: enable the single-precision reciprocal square root approximation instructions;
@code{rsqrtd}: enable the double-precision reciprocal square root approximation instructions;
-So for example, @option{-mrecip=all,!rsqrtd} would enable the
+So, for example, @option{-mrecip=all,!rsqrtd} enables
all of the reciprocal estimate instructions, except for the
@code{FRSQRTE}, @code{XSRSQRTEDP}, and @code{XVRSQRTEDP} instructions
which handle the double-precision reciprocal square root calculations.
external library. The only type supported at present is @code{mass},
which specifies to use IBM's Mathematical Acceleration Subsystem
(MASS) libraries for vectorizing intrinsics using external libraries.
-GCC will currently emit calls to @code{acosd2}, @code{acosf4},
+GCC currently emits calls to @code{acosd2}, @code{acosf4},
@code{acoshd2}, @code{acoshf4}, @code{asind2}, @code{asinf4},
@code{asinhd2}, @code{asinhf4}, @code{atan2d2}, @code{atan2f4},
@code{atand2}, @code{atanf4}, @code{atanhd2}, @code{atanhf4},
@code{sinhf4}, @code{sqrtd2}, @code{sqrtf4}, @code{tand2},
@code{tanf4}, @code{tanhd2}, and @code{tanhf4} when generating code
for power7. Both @option{-ftree-vectorize} and
-@option{-funsafe-math-optimizations} have to be enabled. The MASS
-libraries will have to be specified at link time.
+@option{-funsafe-math-optimizations} must also be enabled. The MASS
+libraries must be specified at link time.
@item -mfriz
@itemx -mno-friz
systems where a function pointer points to a 3-word descriptor giving
the function address, TOC value to be loaded in register @var{r2}, and
static chain value to be loaded in register @var{r11}. The
-@option{-mpointers-to-nested-functions} is on by default. You will
-not be able to call through pointers to nested functions or pointers
+@option{-mpointers-to-nested-functions} is on by default. You cannot
+call through pointers to nested functions or pointers
to functions compiled in other languages that use the static chain if
you use the @option{-mno-pointers-to-nested-functions}.
floating-point hardware. The default is enabled for the @var{RX600}
series and disabled for the @var{RX200} series.
-Floating-point instructions will only be generated for 32-bit floating-point
-values however, so if the @option{-m64bit-doubles} option is in
-use then the FPU hardware will not be used for doubles.
+Floating-point instructions are only generated for 32-bit floating-point
+values, however, so the FPU hardware is not used for doubles if the
+@option{-m64bit-doubles} option is used.
@emph{Note} If the @option{-fpu} option is enabled then
@option{-funsafe-math-optimizations} is also enabled automatically.
not overflow. Also when the small data area is used one of the RX's
registers (usually @code{r13}) is reserved for use pointing to this
area, so it is no longer available for use by the compiler. This
-could result in slower and/or larger code if variables which once
-could have been held in the reserved register are now pushed onto the
-stack.
+could result in slower and/or larger code if variables are pushed onto
+the stack instead of being held in this register.
Note, common variables (variables that have not been initialized) and
constants are not placed into the small data area as they are assigned
@item -mrelax
@opindex mrelax
Enable linker relaxation. Linker relaxation is a process whereby the
-linker will attempt to reduce the size of a program by finding shorter
+linker attempts to reduce the size of a program by finding shorter
versions of various instructions. Disabled by default.
@item -mint-register=@var{N}
@opindex mint-register
Specify the number of registers to reserve for fast interrupt handler
functions. The value @var{N} can be between 0 and 4. A value of 1
-means that register @code{r13} will be reserved for the exclusive use
+means that register @code{r13} is reserved for the exclusive use
of fast interrupt handlers. A value of 2 reserves @code{r13} and
@code{r12}. A value of 3 reserves @code{r13}, @code{r12} and
@code{r11}, and a value of 4 reserves @code{r13} through @code{r10}.
@opindex mpid
@opindex mno-pid
Enables the generation of position independent data. When enabled any
-access to constant data will done via an offset from a base address
+access to constant data is done via an offset from a base address
held in a register. This allows the location of constant data to be
determined at run time without requiring the executable to be
relocated, which is a benefit to embedded applications with tight
@emph{Note:} The generic GCC command-line option @option{-ffixed-@var{reg}}
has special significance to the RX port when used with the
@code{interrupt} function attribute. This attribute indicates a
-function intended to process fast interrupts. GCC will will ensure
+function intended to process fast interrupts. GCC ensures
that it only uses the registers @code{r10}, @code{r11}, @code{r12}
and/or @code{r13} and only provided that the normal use of the
corresponding registers have been restricted via the
@opindex msoft-float
Use (do not use) the hardware floating-point instructions and registers
for floating-point operations. When @option{-msoft-float} is specified,
-functions in @file{libgcc.a} will be used to perform floating-point
+functions in @file{libgcc.a} are used to perform floating-point
operations. When @option{-mhard-float} is specified, the compiler
generates IEEE floating-point instructions. This is the default.
@opindex mno-hard-dfp
Use (do not use) the hardware decimal-floating-point instructions for
decimal-floating-point operations. When @option{-mno-hard-dfp} is
-specified, functions in @file{libgcc.a} will be used to perform
+specified, functions in @file{libgcc.a} are used to perform
decimal-floating-point operations. When @option{-mhard-dfp} is
specified, the compiler generates decimal-floating-point hardware
instructions. This is the default for @option{-march=z9-ec} or higher.
@item -march=@var{cpu-type}
@opindex march
-Generate code that will run on @var{cpu-type}, which is the name of a system
+Generate code that runs on @var{cpu-type}, which is the name of a system
representing a certain processor type. Possible values for
@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, @samp{z990},
@samp{z9-109}, @samp{z9-ec} and @samp{z10}.
@item -mdalign
@opindex mdalign
Align doubles at 64-bit boundaries. Note that this changes the calling
-conventions, and thus some functions from the standard C library will
+conventions, and thus some functions from the standard C library do
not work unless you recompile it first with @option{-mdalign}.
@item -mrelax
code generation option (e.g. @option{-m4}) does not allow the use of the @code{icbi}
instruction.
If the selected code generation option does not allow the use of the @code{icbi}
-instruction, and @option{-musermode} is not in effect, the inlined code will
-manipulate the instruction cache address array directly with an associative
-write. This not only requires privileged mode, but it will also
-fail if the cache line had been mapped via the TLB and has become unmapped.
+instruction, and @option{-musermode} is not in effect, the inlined code
+manipulates the instruction cache address array directly with an associative
+write. This not only requires privileged mode at run time, but it also
+fails if the cache line had been mapped via the TLB and has become unmapped.
@item -misize
@opindex misize
@item inv20u
@itemx inv20l
Variants of the @samp{inv:minlat} strategy. In the case
-that the inverse calculation was not separated from the multiply, they speed
+that the inverse calculation is not separated from the multiply, they speed
up division where the dividend fits into 20 bits (plus sign where applicable)
by inserting a test to skip a number of operations in this case; this test
slows down the case of larger dividends. @samp{inv20u} assumes the case of a such
@item -mbranch-cost=@var{num}
@opindex mbranch-cost=@var{num}
Assume @var{num} to be the cost for a branch instruction. Higher numbers
-will make the compiler try to generate more branch-free code if possible.
+make the compiler try to generate more branch-free code if possible.
If not specified the value is selected depending on the processor type that
is being compiled for.
@option{-mimpure-text} suppresses the ``relocations remain against
allocatable but non-writable sections'' linker error message.
-However, the necessary relocations will trigger copy-on-write, and the
+However, the necessary relocations trigger copy-on-write, and the
shared object is not actually shared across processes. Instead of
using @option{-mimpure-text}, you should compile all source code with
@option{-fpic} or @option{-fPIC}.
With @option{-mflat}, the compiler does not generate save/restore instructions
and uses a ``flat'' or single register window model. This model is compatible
with the regular register window model. The local registers and the input
-registers (0--5) are still treated as ``call-saved'' registers and will be
+registers (0--5) are still treated as ``call-saved'' registers and are
saved on the stack as needed.
With @option{-mno-flat} (the default), the compiler generates save/restore
assignment, in place of twice as many @code{ld} and @code{st} pairs.
However, the use of this changed alignment directly violates the SPARC
ABI@. Thus, it's intended only for use on targets where the developer
-acknowledges that their resulting code will not be directly in line with
+acknowledges that their resulting code is not directly in line with
the rules of the ABI@.
@item -mcpu=@var{cpu_type}
@opindex mtune
Set the instruction scheduling parameters for machine type
@var{cpu_type}, but do not set the instruction set or register set that the
-option @option{-mcpu=@var{cpu_type}} would.
+option @option{-mcpu=@var{cpu_type}} does.
The same values for @option{-mcpu=@var{cpu_type}} can be used for
@option{-mtune=@var{cpu_type}}, but the only useful values are those
@opindex merror-reloc
The loader for SPU does not handle dynamic relocations. By default, GCC
-will give an error when it generates code that requires a dynamic
+gives an error when it generates code that requires a dynamic
relocation. @option{-mno-error-reloc} disables the error,
-@option{-mwarn-reloc} will generate a warning instead.
+@option{-mwarn-reloc} generates a warning instead.
@item -msafe-dma
@itemx -munsafe-dma
@item -mbranch-hints
@opindex mbranch-hints
-By default, GCC will generate a branch hint instruction to avoid
-pipeline stalls for always taken or probably taken branches. A hint
-will not be generated closer than 8 instructions away from its branch.
+By default, GCC generates a branch hint instruction to avoid
+pipeline stalls for always-taken or probably-taken branches. A hint
+is not generated closer than 8 instructions away from its branch.
There is little reason to disable them, except for debugging purposes,
or to make an object a little bit smaller.
By default, GCC links against startup code that assumes the SPU-style
main function interface (which has an unconventional parameter list).
-With @option{-mstdmain}, GCC will link your program against startup
+With @option{-mstdmain}, GCC links your program against startup
code that assumes a C99-style interface to @code{main}, including a
local copy of @code{argv} strings.
executable and selects whether atomic updates to the software-managed
cache of PPU-side variables are used. If you use atomic updates, changes
to a PPU variable from SPU code using the @code{__ea} named address space
-qualifier will not interfere with changes to other PPU variables residing
+qualifier do not interfere with changes to other PPU variables residing
in the same cache line from PPU code. If you do not use atomic updates,
-such interference may occur; however, writing back cache lines will be
+such interference may occur; however, writing back cache lines is
more efficient. The default behavior is to use atomic updates.
@item -mdual-nops
@itemx -mdual-nops=@var{n}
@opindex mdual-nops
-By default, GCC will insert nops to increase dual issue when it expects
+By default, GCC inserts nops to increase dual issue when it expects
it to increase performance. @var{n} can be a value from 0 to 10. A
-smaller @var{n} will insert fewer nops. 10 is the default, 0 is the
+smaller @var{n} inserts fewer nops. 10 is the default, 0 is the
same as @option{-mno-dual-nops}. Disabled with @option{-Os}.
@item -mhint-max-nops=@var{n}
@opindex mhint-max-nops
Maximum number of nops to insert for a branch hint. A branch hint must
-be at least 8 instructions away from the branch it is effecting. GCC
-will insert up to @var{n} nops to enforce this, otherwise it will not
+be at least 8 instructions away from the branch it is affecting. GCC
+inserts up to @var{n} nops to enforce this, otherwise it does not
generate the branch hint.
@item -mhint-max-distance=@var{n}
@opindex mhint-max-distance
The encoding of the branch hint instruction limits the hint to be within
-256 instructions of the branch it is effecting. By default, GCC makes
+256 instructions of the branch it is affecting. By default, GCC makes
sure it is within 125.
@item -msafe-hints
@opindex msafe-hints
Work around a hardware bug that causes the SPU to stall indefinitely.
-By default, GCC will insert the @code{hbrp} instruction to make sure
+By default, GCC inserts the @code{hbrp} instruction to make sure
this stall won't happen.
@end table
@opindex mlong-calls
@opindex mno-long-calls
Treat all calls as being far away (near). If calls are assumed to be
-far away, the compiler will always load the functions address up into a
-register, and call indirect through the pointer.
+far away, the compiler always loads the function's address into a
+register, and calls indirect through the pointer.
@item -mno-ep
@itemx -mep
@item -mapp-regs
@opindex mapp-regs
-This option will cause r2 and r5 to be used in the code generated by
+This option causes r2 and r5 to be used in the code generated by
the compiler. This setting is the default.
@item -mno-app-regs
@opindex mno-app-regs
-This option will cause r2 and r5 to be treated as fixed registers.
+This option causes r2 and r5 to be treated as fixed registers.
@item -mv850e2v3
@opindex mv850e2v3
Specify that the target processor is the V850E2V3. The preprocessor
-constants @samp{__v850e2v3__} will be defined if
+constant @samp{__v850e2v3__} is defined if
this option is used.
@item -mv850e2
@opindex mv850e2
Specify that the target processor is the V850E2. The preprocessor
-constants @samp{__v850e2__} will be defined if this option is used.
+constant @samp{__v850e2__} is defined if this option is used.
@item -mv850e1
@opindex mv850e1
Specify that the target processor is the V850E1. The preprocessor
-constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
+constants @samp{__v850e1__} and @samp{__v850e__} are defined if
this option is used.
@item -mv850es
@item -mv850e
@opindex mv850e
Specify that the target processor is the V850E@. The preprocessor
-constant @samp{__v850e__} will be defined if this option is used.
+constant @samp{__v850e__} is defined if this option is used.
If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
nor @option{-mv850e2} nor @option{-mv850e2v3}
-are defined then a default target processor will be chosen and the
-relevant @samp{__v850*__} preprocessor constant will be defined.
+are defined then a default target processor is chosen and the
+relevant @samp{__v850*__} preprocessor constant is defined.
The preprocessor constants @samp{__v850} and @samp{__v851__} are always
defined, regardless of which processor variant is the target.
@item -mdisable-callt
@opindex mdisable-callt
-This option will suppress generation of the CALLT instruction for the
+This option suppresses generation of the @code{CALLT} instruction for the
v850e, v850e1, v850e2 and v850e2v3 flavors of the v850 architecture. The default is
-@option{-mno-disable-callt} which allows the CALLT instruction to be used.
+@option{-mno-disable-callt} which allows the @code{CALLT} instruction to be used.
@end table
@item -mgnu
@opindex mgnu
-Do output those jump instructions, on the assumption that you
-will assemble with the GNU assembler.
+Do output those jump instructions, on the assumption that the
+GNU assembler is being used.
@item -mg
@opindex mg
expense of some code density. The assembler attempts to widen density
instructions to align branch targets and the instructions following call
instructions. If there are not enough preceding safe density
-instructions to align a target, no widening will be performed. The
+instructions to align a target, no widening is performed. The
default is @option{-mtarget-align}. These options do not affect the
treatment of auto-aligned instructions like @code{LOOP}, which the
-assembler will always align, either by widening density instructions or
-by inserting no-op instructions.
+assembler always aligns, either by widening density instructions or
+by inserting NOP instructions.
@item -mlongcalls
@itemx -mno-longcalls
The default is @option{-mno-longcalls}. This option should be used in
programs where the call target can potentially be out of range. This
option is implemented in the assembler, not the compiler, so the
-assembly code generated by GCC will still show direct call
+assembly code generated by GCC still shows direct call
instructions---look at the disassembled object code to see the actual
-instructions. Note that the assembler will use an indirect call for
-every cross-file call, not just those that really will be out of range.
+instructions. Note that the assembler uses an indirect call for
+every cross-file call, not just those that really are out of range.
@end table
@node zSeries Options
used in code generation.
Most of them have both positive and negative forms; the negative form
-of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
+of @option{-ffoo} is @option{-fno-foo}. In the table below, only
one of the forms is listed---the one that is not the default. You
can figure out the other form by either removing @samp{no-} or adding
it.
@item -fexceptions
@opindex fexceptions
Enable exception handling. Generates extra code needed to propagate
-exceptions. For some targets, this implies GCC will generate frame
+exceptions. For some targets, this implies GCC generates frame
unwind information for all functions, which can produce significant data
size overhead, although it does not affect execution. If you do not
-specify this option, GCC will enable it by default for languages like
-C++ that normally require exception handling, and disable it for
+specify this option, GCC enables it by default for languages like
+C++ that normally require exception handling, and disables it for
languages like C that do not normally require it. However, you may need
to enable this option when compiling C code that needs to interoperate
properly with exception handlers written in C++. You may also wish to
@item -funwind-tables
@opindex funwind-tables
-Similar to @option{-fexceptions}, except that it will just generate any needed
-static data, but will not affect the generated code in any other way.
-You will normally not enable this option; instead, a language processor
-that needs this handling would enable it on your behalf.
+Similar to @option{-fexceptions}, except that it just generates any needed
+static data, but does not affect the generated code in any other way.
+You normally do not need to enable this option; instead, a language processor
+that needs this handling enables it on your behalf.
@item -fasynchronous-unwind-tables
@opindex fasynchronous-unwind-tables
@opindex fshort-enums
Allocate to an @code{enum} type only as many bytes as it needs for the
declared range of possible values. Specifically, the @code{enum} type
-will be equivalent to the smallest integer type that has enough room.
+is equivalent to the smallest integer type that has enough room.
@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
code that is not binary compatible with code generated without that switch.
rather than generating them as common blocks.
This has the effect that if the same variable is declared
(without @code{extern}) in two different compilations,
-you will get a multiple-definition error when you link them.
+you get a multiple-definition error when you link them.
In this case, you must compile with @option{-fcommon} instead.
Compiling with @option{-fno-common} is useful on targets for which
it provides better performance, or if you wish to verify that the
@item -frecord-gcc-switches
@opindex frecord-gcc-switches
-This switch causes the command line that was used to invoke the
+This switch causes the command line used to invoke the
compiler to be recorded into the object file that is being created.
This switch is only implemented on some targets and the exact format
of the recording is target and binary file format dependent, but it
@opindex fPIE
These options are similar to @option{-fpic} and @option{-fPIC}, but
generated position independent code can be only linked into executables.
-Usually these options are used when @option{-pie} GCC option will be
+Usually these options are used when @option{-pie} GCC option is
used during linking.
@option{-fpie} and @option{-fPIE} both define the macros
Treat the register named @var{reg} as an allocable register that is
clobbered by function calls. It may be allocated for temporaries or
variables that do not live across a call. Functions compiled this way
-will not save and restore the register @var{reg}.
+do not save and restore the register @var{reg}.
-It is an error to used this flag with the frame pointer or stack pointer.
+It is an error to use this flag with the frame pointer or stack pointer.
Use of this flag for other registers that have fixed pervasive roles in
-the machine's execution model will produce disastrous results.
+the machine's execution model produces disastrous results.
This flag does not have a negative form, because it specifies a
three-way choice.
@opindex fcall-saved
Treat the register named @var{reg} as an allocable register saved by
functions. It may be allocated even for temporaries or variables that
-live across a call. Functions compiled this way will save and restore
+live across a call. Functions compiled this way save and restore
the register @var{reg} if they use it.
-It is an error to used this flag with the frame pointer or stack pointer.
+It is an error to use this flag with the frame pointer or stack pointer.
Use of this flag for other registers that have fixed pervasive roles in
-the machine's execution model will produce disastrous results.
+the machine's execution model produces disastrous results.
-A different sort of disaster will result from the use of this flag for
+A different sort of disaster results from the use of this flag for
a register in which function values may be returned.
This flag does not have a negative form, because it specifies a
holes. When a value is specified (which must be a small power of two), pack
structure members according to this value, representing the maximum
alignment (that is, objects with default alignment requirements larger than
-this will be output potentially unaligned at the next fitting location.
+this are output potentially unaligned at the next fitting location.
@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
code that is not binary compatible with code generated without that switch.
@opindex finstrument-functions
Generate instrumentation calls for entry and exit to functions. Just
after function entry and just before function exit, the following
-profiling functions will be called with the address of the current
+profiling functions are called with the address of the current
function and its call site. (On some platforms,
@code{__builtin_return_address} does not work beyond the current
function, so the call site information may not be available to the
which may be looked up exactly in the symbol table.
This instrumentation is also done for functions expanded inline in other
-functions. The profiling calls will indicate where, conceptually, the
+functions. The profiling calls indicate where, conceptually, the
inline function is entered and exited. This means that addressable
versions of such functions must be available. If all your uses of a
function are expanded inline, this may mean an additional expansion of
code size. If you use @samp{extern inline} in your C code, an
addressable version of such functions must be provided. (This is
-normally the case anyways, but if you get lucky and the optimizer always
+normally the case anyway, but if you get lucky and the optimizer always
expands the functions inline, you might have gotten away without
providing static copies.)
A function may be given the attribute @code{no_instrument_function}, in
-which case this instrumentation will not be done. This can be used, for
+which case this instrumentation is not done. This can be used, for
example, for the profiling functions listed above, high-priority
interrupt routines, and any functions from which the profiling functions
cannot safely be called (perhaps signal handlers, if the profiling
@end smallexample
@noindent
-will exclude any inline function defined in files whose pathnames
+excludes any inline function defined in files whose pathnames
contain @code{/bits/stl} or @code{include/sys}.
If, for some reason, you want to include letter @code{','} in one of
@enumerate
@item
-Modified allocation strategy for large objects: they will always be
+Modified allocation strategy for large objects: they are always
allocated dynamically if their size exceeds a fixed threshold.
@item
@opindex fstack-limit-symbol
@opindex fno-stack-limit
Generate code to ensure that the stack does not grow beyond a certain value,
-either the value of a register or the address of a symbol. If the stack
-would grow beyond the value, a signal is raised. For most targets,
+either the value of a register or the address of a symbol. If a larger
+stack is required, a signal is raised at run time. For most targets,
the signal is raised before the stack overruns the boundary, so
it is possible to catch the signal without taking special precautions.
@item -fvisibility=@var{default|internal|hidden|protected}
@opindex fvisibility
Set the default ELF image symbol visibility to the specified option---all
-symbols will be marked with this unless overridden within the code.
+symbols are marked with this unless overridden within the code.
Using this feature can very substantially improve linking and
load times of shared object libraries, produce more optimized
code, provide near-perfect API export and prevent symbol clashes.
Despite the nomenclature, @code{default} always means public; i.e.,
available to be linked against from outside the shared object.
@code{protected} and @code{internal} are pretty useless in real-world
-usage so the only other commonly used option will be @code{hidden}.
+usage so the only other commonly used option is @code{hidden}.
The default if @option{-fvisibility} isn't specified is
@code{default}, i.e., make every
symbol public---this causes the same behavior as previous versions of
@samp{extern} declarations are not affected by @option{-fvisibility}, so
a lot of code can be recompiled with @option{-fvisibility=hidden} with
no modifications. However, this means that calls to @code{extern}
-functions with no explicit visibility will use the PLT, so it is more
+functions with no explicit visibility use the PLT, so it is more
effective to use @code{__attribute ((visibility))} and/or
@code{#pragma GCC visibility} to tell the compiler which @code{extern}
declarations should be treated as hidden.
Note that @option{-fvisibility} does affect C++ vague linkage
-entities. This means that, for instance, an exception class that will
+entities. This means that, for instance, an exception class that is
be thrown between DSOs must be explicitly marked with default
-visibility so that the @samp{type_info} nodes will be unified between
+visibility so that the @samp{type_info} nodes are unified between
the DSOs.
An overview of these techniques, their benefits and how to use them
is 16 bits on these targets) to force GCC to use 16-bit accesses
instead of, perhaps, a more efficient 32-bit access.
-If this option is disabled, the compiler will use the most efficient
+If this option is disabled, the compiler uses the most efficient
instruction. In the previous example, that might be a 32-bit load
-instruction, even though that will access bytes that do not contain
+instruction, even though that accesses bytes that do not contain
any portion of the bit-field, or memory-mapped registers unrelated to
the one being updated.
The @env{LC_CTYPE} environment variable specifies character
classification. GCC uses it to determine the character boundaries in
a string; this is needed for some multibyte encodings that contain quote
-and escape characters that would otherwise be interpreted as a string
+and escape characters that are otherwise interpreted as a string
end or escape.
The @env{LC_MESSAGES} environment variable specifies the language to
when this prefix is combined with the name of a subprogram, but you can
specify a prefix that ends with a slash if you wish.
-If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
-an appropriate prefix to use based on the pathname it was invoked with.
+If @env{GCC_EXEC_PREFIX} is not set, GCC attempts to figure out
+an appropriate prefix to use based on the pathname it is invoked with.
If GCC cannot find the subprogram using the specified prefix, it
tries looking in the usual places for the subprogram.
directories whose name normally begins with @samp{/usr/local/lib/gcc}
(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
replacing that beginning with the specified prefix to produce an
-alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
-@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
-These alternate directories are searched first; the standard directories
-come next. If a standard directory begins with the configured
+alternate directory name. Thus, with @option{-Bfoo/}, GCC searches
+@file{foo/bar} just before it searches the standard directory
+@file{/usr/local/lib/bar}.
+If a standard directory begins with the configured
@var{prefix} then the value of @var{prefix} is replaced by
@env{GCC_EXEC_PREFIX} when looking for header files.
@end table
If @env{LANG} is not defined, or if it has some other value, then the
-compiler will use mblen and mbtowc as defined by the default locale to
+compiler uses @code{mblen} and @code{mbtowc} as defined by the default locale to
recognize and translate multibyte characters.
@end table
@noindent
-Some additional environments variables affect the behavior of the
+Some additional environment variables affect the behavior of the
preprocessor.
@include cppenv.texi
Often large projects have many header files that are included in every
source file. The time the compiler takes to process these header files
over and over again can account for nearly all of the time required to
-build the project. To make builds faster, GCC allows users to
-@dfn{precompile} a header file; then, if builds can use the precompiled
-header file they will be much faster.
+build the project. To make builds faster, GCC allows you to
+@dfn{precompile} a header file.
To create a precompiled header file, simply compile it as you would any
other file, if necessary using the @option{-x} option to make the driver
-treat it as a C or C++ header file. You will probably want to use a
+treat it as a C or C++ header file. You may want to use a
tool like @command{make} to keep the precompiled header up-to-date when
the headers it contains change.
-A precompiled header file will be searched for when @code{#include} is
+A precompiled header file is searched for when @code{#include} is
seen in the compilation. As it searches for the included file
(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
compiler looks for a precompiled header in each directory just before it
For instance, if you have @code{#include "all.h"}, and you have
@file{all.h.gch} in the same directory as @file{all.h}, then the
-precompiled header file will be used if possible, and the original
-header will be used otherwise.
+precompiled header file is used if possible, and the original
+header is used otherwise.
Alternatively, you might decide to put the precompiled header file in a
directory and use @option{-I} to ensure that directory is searched
header files in mind, is to simply take most of the header files used by
a project, include them from another header file, precompile that header
file, and @option{-include} the precompiled header. If the header files
-have guards against multiple inclusion, they will be skipped because
+have guards against multiple inclusion, they are skipped because
they've already been included (in the precompiled header).
If you need to precompile the same header file for different
languages, targets, or compiler options, you can instead make a
@emph{directory} named like @file{all.h.gch}, and put each precompiled
header in the directory, perhaps using @option{-o}. It doesn't matter
-what you call the files in the directory, every precompiled header in
-the directory will be considered. The first precompiled header
-encountered in the directory that is valid for this compilation will
-be used; they're searched in no particular order.
+what you call the files in the directory; every precompiled header in
+the directory is considered. The first precompiled header
+encountered in the directory that is valid for this compilation is
+used; they're searched in no particular order.
There are many other possibilities, limited only by your imagination,
good sense, and the constraints of your build system.
@end itemize
-For all of these except the last, the compiler will automatically
-ignore the precompiled header if the conditions aren't met. If you
+For all of these except the last, the compiler automatically
+ignores the precompiled header if the conditions aren't met. If you
find an option combination that doesn't work and doesn't cause the
precompiled header to be ignored, please consider filing a bug report,
see @ref{Bugs}.
If you do use differing options when generating and using the
-precompiled header, the actual behavior will be a mixture of the
+precompiled header, the actual behavior is a mixture of the
behavior for the options. For instance, if you use @option{-g} to
generate the precompiled header but not when using it, you may or may
not get debugging information for routines in the precompiled header.