2016-01-12 Sandra Loosemore <sandra@codesourcery.com>

	gcc/
	* doc/invoke.texi (Spec Files): Move section down in file, past
	all command-line option descriptions.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@232311 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 577 insertions, 581 deletions

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 3bbc267dbb2..d532aab3197 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -146,11 +146,11 @@ only one of these two forms, whichever one is not the default.
 * Link Options::        Specifying libraries and so on.
 * Directory Options::   Where to find header files and libraries.
                         Where to find the compiler executable files.
-* Spec Files::          How to pass switches to sub-processes.
 * Submodel Options::    Specifying minor hardware or convention variations,
                         such as 68010 vs 68020.
 * Code Gen Options::    Specifying conventions for function calls, data layout
                         and register usage.
+* Spec Files::          How to pass switches to sub-processes.
 * Environment Variables:: Env vars that affect GCC.
 * Precompiled Headers:: Compiling a header once, and using it many times.
 @end menu
@@ -11840,586 +11840,6 @@ for header files.  Thus, @option{-I-} and @option{-nostdinc} are
 independent.
 @end table
 
-@c man end
-
-@node Spec Files
-@section Specifying Subprocesses and the Switches to Pass to Them
-@cindex Spec Files
-
-@command{gcc} is a driver program.  It performs its job by invoking a
-sequence of other programs to do the work of compiling, assembling and
-linking.  GCC interprets its command-line parameters and uses these to
-deduce which programs it should invoke, and which command-line options
-it ought to place on their command lines.  This behavior is controlled
-by @dfn{spec strings}.  In most cases there is one spec string for each
-program that GCC can invoke, but a few programs have multiple spec
-strings to control their behavior.  The spec strings built into GCC can
-be overridden by using the @option{-specs=} command-line switch to specify
-a spec file.
-
-@dfn{Spec files} are plaintext files that are used to construct spec
-strings.  They consist of a sequence of directives separated by blank
-lines.  The type of directive is determined by the first non-whitespace
-character on the line, which can be one of the following:
-
-@table @code
-@item %@var{command}
-Issues a @var{command} to the spec file processor.  The commands that can
-appear here are:
-
-@table @code
-@item %include <@var{file}>
-@cindex @code{%include}
-Search for @var{file} and insert its text at the current point in the
-specs file.
-
-@item %include_noerr <@var{file}>
-@cindex @code{%include_noerr}
-Just like @samp{%include}, but do not generate an error message if the include
-file cannot be found.
-
-@item %rename @var{old_name} @var{new_name}
-@cindex @code{%rename}
-Rename the spec string @var{old_name} to @var{new_name}.
-
-@end table
-
-@item *[@var{spec_name}]:
-This tells the compiler to create, override or delete the named spec
-string.  All lines after this directive up to the next directive or
-blank line are considered to be the text for the spec string.  If this
-results in an empty string then the spec is deleted.  (Or, if the
-spec did not exist, then nothing happens.)  Otherwise, if the spec
-does not currently exist a new spec is created.  If the spec does
-exist then its contents are overridden by the text of this
-directive, unless the first character of that text is the @samp{+}
-character, in which case the text is appended to the spec.
-
-@item [@var{suffix}]:
-Creates a new @samp{[@var{suffix}] spec} pair.  All lines after this directive
-and up to the next directive or blank line are considered to make up the
-spec string for the indicated suffix.  When the compiler encounters an
-input file with the named suffix, it processes the spec string in
-order to work out how to compile that file.  For example:
-
-@smallexample
-.ZZ:
-z-compile -input %i
-@end smallexample
-
-This says that any input file whose name ends in @samp{.ZZ} should be
-passed to the program @samp{z-compile}, which should be invoked with the
-command-line switch @option{-input} and with the result of performing the
-@samp{%i} substitution.  (See below.)
-
-As an alternative to providing a spec string, the text following a
-suffix directive can be one of the following:
-
-@table @code
-@item @@@var{language}
-This says that the suffix is an alias for a known @var{language}.  This is
-similar to using the @option{-x} command-line switch to GCC to specify a
-language explicitly.  For example:
-
-@smallexample
-.ZZ:
-@@c++
-@end smallexample
-
-Says that .ZZ files are, in fact, C++ source files.
-
-@item #@var{name}
-This causes an error messages saying:
-
-@smallexample
-@var{name} compiler not installed on this system.
-@end smallexample
-@end table
-
-GCC already has an extensive list of suffixes built into it.
-This directive adds an entry to the end of the list of suffixes, but
-since the list is searched from the end backwards, it is effectively
-possible to override earlier entries using this technique.
-
-@end table
-
-GCC has the following spec strings built into it.  Spec files can
-override these strings or create their own.  Note that individual
-targets can also add their own spec strings to this list.
-
-@smallexample
-asm          Options to pass to the assembler
-asm_final    Options to pass to the assembler post-processor
-cpp          Options to pass to the C preprocessor
-cc1          Options to pass to the C compiler
-cc1plus      Options to pass to the C++ compiler
-endfile      Object files to include at the end of the link
-link         Options to pass to the linker
-lib          Libraries to include on the command line to the linker
-libgcc       Decides which GCC support library to pass to the linker
-linker       Sets the name of the linker
-predefines   Defines to be passed to the C preprocessor
-signed_char  Defines to pass to CPP to say whether @code{char} is signed
-             by default
-startfile    Object files to include at the start of the link
-@end smallexample
-
-Here is a small example of a spec file:
-
-@smallexample
-%rename lib                 old_lib
-
-*lib:
---start-group -lgcc -lc -leval1 --end-group %(old_lib)
-@end smallexample
-
-This example renames the spec called @samp{lib} to @samp{old_lib} and
-then overrides the previous definition of @samp{lib} with a new one.
-The new definition adds in some extra command-line options before
-including the text of the old definition.
-
-@dfn{Spec strings} are a list of command-line options to be passed to their
-corresponding program.  In addition, the spec strings can contain
-@samp{%}-prefixed sequences to substitute variable text or to
-conditionally insert text into the command line.  Using these constructs
-it is possible to generate quite complex command lines.
-
-Here is a table of all defined @samp{%}-sequences for spec
-strings.  Note that spaces are not generated automatically around the
-results of expanding these sequences.  Therefore you can concatenate them
-together or combine them with constant text in a single argument.
-
-@table @code
-@item %%
-Substitute one @samp{%} into the program name or argument.
-
-@item %i
-Substitute the name of the input file being processed.
-
-@item %b
-Substitute the basename of the input file being processed.
-This is the substring up to (and not including) the last period
-and not including the directory.
-
-@item %B
-This is the same as @samp{%b}, but include the file suffix (text after
-the last period).
-
-@item %d
-Marks the argument containing or following the @samp{%d} as a
-temporary file name, so that that file is deleted if GCC exits
-successfully.  Unlike @samp{%g}, this contributes no text to the
-argument.
-
-@item %g@var{suffix}
-Substitute a file name that has suffix @var{suffix} and is chosen
-once per compilation, and mark the argument in the same way as
-@samp{%d}.  To reduce exposure to denial-of-service attacks, the file
-name is now chosen in a way that is hard to predict even when previously
-chosen file names are known.  For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
-might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}.  @var{suffix} matches
-the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
-treated exactly as if @samp{%O} had been preprocessed.  Previously, @samp{%g}
-was simply substituted with a file name chosen once per compilation,
-without regard to any appended suffix (which was therefore treated
-just like ordinary text), making such attacks more likely to succeed.
-
-@item %u@var{suffix}
-Like @samp{%g}, but generates a new temporary file name
-each time it appears instead of once per compilation.
-
-@item %U@var{suffix}
-Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
-new one if there is no such last file name.  In the absence of any
-@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
-the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
-involves the generation of two distinct file names, one
-for each @samp{%g.s} and another for each @samp{%U.s}.  Previously, @samp{%U} was
-simply substituted with a file name chosen for the previous @samp{%u},
-without regard to any appended suffix.
-
-@item %j@var{suffix}
-Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
-writable, and if @option{-save-temps} is not used; 
-otherwise, substitute the name
-of a temporary file, just like @samp{%u}.  This temporary file is not
-meant for communication between processes, but rather as a junk
-disposal mechanism.
-
-@item %|@var{suffix}
-@itemx %m@var{suffix}
-Like @samp{%g}, except if @option{-pipe} is in effect.  In that case
-@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
-all.  These are the two most common ways to instruct a program that it
-should read from standard input or write to standard output.  If you
-need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
-construct: see for example @file{f/lang-specs.h}.
-
-@item %.@var{SUFFIX}
-Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
-when it is subsequently output with @samp{%*}.  @var{SUFFIX} is
-terminated by the next space or %.
-
-@item %w
-Marks the argument containing or following the @samp{%w} as the
-designated output file of this compilation.  This puts the argument
-into the sequence of arguments that @samp{%o} substitutes.
-
-@item %o
-Substitutes the names of all the output files, with spaces
-automatically placed around them.  You should write spaces
-around the @samp{%o} as well or the results are undefined.
-@samp{%o} is for use in the specs for running the linker.
-Input files whose names have no recognized suffix are not compiled
-at all, but they are included among the output files, so they are
-linked.
-
-@item %O
-Substitutes the suffix for object files.  Note that this is
-handled specially when it immediately follows @samp{%g, %u, or %U},
-because of the need for those to form complete file names.  The
-handling is such that @samp{%O} is treated exactly as if it had already
-been substituted, except that @samp{%g, %u, and %U} do not currently
-support additional @var{suffix} characters following @samp{%O} as they do
-following, for example, @samp{.o}.
-
-@item %p
-Substitutes the standard macro predefinitions for the
-current target machine.  Use this when running @command{cpp}.
-
-@item %P
-Like @samp{%p}, but puts @samp{__} before and after the name of each
-predefined macro, except for macros that start with @samp{__} or with
-@samp{_@var{L}}, where @var{L} is an uppercase letter.  This is for ISO
-C@.
-
-@item %I
-Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
-@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
-@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
-and @option{-imultilib} as necessary.
-
-@item %s
-Current argument is the name of a library or startup file of some sort.
-Search for that file in a standard list of directories and substitute
-the full name found.  The current working directory is included in the
-list of directories scanned.
-
-@item %T
-Current argument is the name of a linker script.  Search for that file
-in the current list of directories to scan for libraries. If the file
-is located insert a @option{--script} option into the command line
-followed by the full path name found.  If the file is not found then
-generate an error message.  Note: the current working directory is not
-searched.
-
-@item %e@var{str}
-Print @var{str} as an error message.  @var{str} is terminated by a newline.
-Use this when inconsistent options are detected.
-
-@item %(@var{name})
-Substitute the contents of spec string @var{name} at this point.
-
-@item %x@{@var{option}@}
-Accumulate an option for @samp{%X}.
-
-@item %X
-Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
-spec string.
-
-@item %Y
-Output the accumulated assembler options specified by @option{-Wa}.
-
-@item %Z
-Output the accumulated preprocessor options specified by @option{-Wp}.
-
-@item %a
-Process the @code{asm} spec.  This is used to compute the
-switches to be passed to the assembler.
-
-@item %A
-Process the @code{asm_final} spec.  This is a spec string for
-passing switches to an assembler post-processor, if such a program is
-needed.
-
-@item %l
-Process the @code{link} spec.  This is the spec for computing the
-command line passed to the linker.  Typically it makes use of the
-@samp{%L %G %S %D and %E} sequences.
-
-@item %D
-Dump out a @option{-L} option for each directory that GCC believes might
-contain startup files.  If the target supports multilibs then the
-current multilib directory is prepended to each of these paths.
-
-@item %L
-Process the @code{lib} spec.  This is a spec string for deciding which
-libraries are included on the command line to the linker.
-
-@item %G
-Process the @code{libgcc} spec.  This is a spec string for deciding
-which GCC support library is included on the command line to the linker.
-
-@item %S
-Process the @code{startfile} spec.  This is a spec for deciding which
-object files are the first ones passed to the linker.  Typically
-this might be a file named @file{crt0.o}.
-
-@item %E
-Process the @code{endfile} spec.  This is a spec string that specifies
-the last object files that are passed to the linker.
-
-@item %C
-Process the @code{cpp} spec.  This is used to construct the arguments
-to be passed to the C preprocessor.
-
-@item %1
-Process the @code{cc1} spec.  This is used to construct the options to be
-passed to the actual C compiler (@command{cc1}).
-
-@item %2
-Process the @code{cc1plus} spec.  This is used to construct the options to be
-passed to the actual C++ compiler (@command{cc1plus}).
-
-@item %*
-Substitute the variable part of a matched option.  See below.
-Note that each comma in the substituted string is replaced by
-a single space.
-
-@item %<@code{S}
-Remove all occurrences of @code{-S} from the command line.  Note---this
-command is position dependent.  @samp{%} commands in the spec string
-before this one see @code{-S}, @samp{%} commands in the spec string
-after this one do not.
-
-@item %:@var{function}(@var{args})
-Call the named function @var{function}, passing it @var{args}.
-@var{args} is first processed as a nested spec string, then split
-into an argument vector in the usual fashion.  The function returns
-a string which is processed as if it had appeared literally as part
-of the current spec.
-
-The following built-in spec functions are provided:
-
-@table @code
-@item @code{getenv}
-The @code{getenv} spec function takes two arguments: an environment
-variable name and a string.  If the environment variable is not
-defined, a fatal error is issued.  Otherwise, the return value is the
-value of the environment variable concatenated with the string.  For
-example, if @env{TOPDIR} is defined as @file{/path/to/top}, then:
-
-@smallexample
-%:getenv(TOPDIR /include)
-@end smallexample
-
-expands to @file{/path/to/top/include}.
-
-@item @code{if-exists}
-The @code{if-exists} spec function takes one argument, an absolute
-pathname to a file.  If the file exists, @code{if-exists} returns the
-pathname.  Here is a small example of its usage:
-
-@smallexample
-*startfile:
-crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
-@end smallexample
-
-@item @code{if-exists-else}
-The @code{if-exists-else} spec function is similar to the @code{if-exists}
-spec function, except that it takes two arguments.  The first argument is
-an absolute pathname to a file.  If the file exists, @code{if-exists-else}
-returns the pathname.  If it does not exist, it returns the second argument.
-This way, @code{if-exists-else} can be used to select one file or another,
-based on the existence of the first.  Here is a small example of its usage:
-
-@smallexample
-*startfile:
-crt0%O%s %:if-exists(crti%O%s) \
-%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
-@end smallexample
-
-@item @code{replace-outfile}
-The @code{replace-outfile} spec function takes two arguments.  It looks for the
-first argument in the outfiles array and replaces it with the second argument.  Here
-is a small example of its usage:
-
-@smallexample
-%@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
-@end smallexample
-
-@item @code{remove-outfile}
-The @code{remove-outfile} spec function takes one argument.  It looks for the
-first argument in the outfiles array and removes it.  Here is a small example
-its usage:
-
-@smallexample
-%:remove-outfile(-lm)
-@end smallexample
-
-@item @code{pass-through-libs}
-The @code{pass-through-libs} spec function takes any number of arguments.  It
-finds any @option{-l} options and any non-options ending in @file{.a} (which it
-assumes are the names of linker input library archive files) and returns a
-result containing all the found arguments each prepended by
-@option{-plugin-opt=-pass-through=} and joined by spaces.  This list is
-intended to be passed to the LTO linker plugin.
-
-@smallexample
-%:pass-through-libs(%G %L %G)
-@end smallexample
-
-@item @code{print-asm-header}
-The @code{print-asm-header} function takes no arguments and simply
-prints a banner like:
-
-@smallexample
-Assembler options
-=================
-
-Use "-Wa,OPTION" to pass "OPTION" to the assembler.
-@end smallexample
-
-It is used to separate compiler options from assembler options
-in the @option{--target-help} output.
-@end table
-
-@item %@{@code{S}@}
-Substitutes the @code{-S} switch, if that switch is given to GCC@.
-If that switch is not specified, this substitutes nothing.  Note that
-the leading dash is omitted when specifying this option, and it is
-automatically inserted if the substitution is performed.  Thus the spec
-string @samp{%@{foo@}} matches the command-line option @option{-foo}
-and outputs the command-line option @option{-foo}.
-
-@item %W@{@code{S}@}
-Like %@{@code{S}@} but mark last argument supplied within as a file to be
-deleted on failure.
-
-@item %@{@code{S}*@}
-Substitutes all the switches specified to GCC whose names start
-with @code{-S}, but which also take an argument.  This is used for
-switches like @option{-o}, @option{-D}, @option{-I}, etc.
-GCC considers @option{-o foo} as being
-one switch whose name starts with @samp{o}.  %@{o*@} substitutes this
-text, including the space.  Thus two arguments are generated.
-
-@item %@{@code{S}*&@code{T}*@}
-Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
-(the order of @code{S} and @code{T} in the spec is not significant).
-There can be any number of ampersand-separated variables; for each the
-wild card is optional.  Useful for CPP as @samp{%@{D*&U*&A*@}}.
-
-@item %@{@code{S}:@code{X}@}
-Substitutes @code{X}, if the @option{-S} switch is given to GCC@.
-
-@item %@{!@code{S}:@code{X}@}
-Substitutes @code{X}, if the @option{-S} switch is @emph{not} given to GCC@.
-
-@item %@{@code{S}*:@code{X}@}
-Substitutes @code{X} if one or more switches whose names start with
-@code{-S} are specified to GCC@.  Normally @code{X} is substituted only
-once, no matter how many such switches appeared.  However, if @code{%*}
-appears somewhere in @code{X}, then @code{X} is substituted once
-for each matching switch, with the @code{%*} replaced by the part of
-that switch matching the @code{*}.
-
-If @code{%*} appears as the last part of a spec sequence then a space
-is added after the end of the last substitution.  If there is more
-text in the sequence, however, then a space is not generated.  This
-allows the @code{%*} substitution to be used as part of a larger
-string.  For example, a spec string like this:
-
-@smallexample
-%@{mcu=*:--script=%*/memory.ld@}
-@end smallexample
-
-@noindent
-when matching an option like @option{-mcu=newchip} produces:
-
-@smallexample
---script=newchip/memory.ld
-@end smallexample
-
-@item %@{.@code{S}:@code{X}@}
-Substitutes @code{X}, if processing a file with suffix @code{S}.
-
-@item %@{!.@code{S}:@code{X}@}
-Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
-
-@item %@{,@code{S}:@code{X}@}
-Substitutes @code{X}, if processing a file for language @code{S}.
-
-@item %@{!,@code{S}:@code{X}@}
-Substitutes @code{X}, if not processing a file for language @code{S}.
-
-@item %@{@code{S}|@code{P}:@code{X}@}
-Substitutes @code{X} if either @code{-S} or @code{-P} is given to
-GCC@.  This may be combined with @samp{!}, @samp{.}, @samp{,}, and
-@code{*} sequences as well, although they have a stronger binding than
-the @samp{|}.  If @code{%*} appears in @code{X}, all of the
-alternatives must be starred, and only the first matching alternative
-is substituted.
-
-For example, a spec string like this:
-
-@smallexample
-%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
-@end smallexample
-
-@noindent
-outputs the following command-line options from the following input
-command-line options:
-
-@smallexample
-fred.c        -foo -baz
-jim.d         -bar -boggle
--d fred.c     -foo -baz -boggle
--d jim.d      -bar -baz -boggle
-@end smallexample
-
-@item %@{S:X; T:Y; :D@}
-
-If @code{S} is given to GCC, substitutes @code{X}; else if @code{T} is
-given to GCC, substitutes @code{Y}; else substitutes @code{D}.  There can
-be as many clauses as you need.  This may be combined with @code{.},
-@code{,}, @code{!}, @code{|}, and @code{*} as needed.
-
-
-@end table
-
-The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
-construct may contain other nested @samp{%} constructs or spaces, or
-even newlines.  They are processed as usual, as described above.
-Trailing white space in @code{X} is ignored.  White space may also
-appear anywhere on the left side of the colon in these constructs,
-except between @code{.} or @code{*} and the corresponding word.
-
-The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
-handled specifically in these constructs.  If another value of
-@option{-O} or the negated form of a @option{-f}, @option{-m}, or
-@option{-W} switch is found later in the command line, the earlier
-switch value is ignored, except with @{@code{S}*@} where @code{S} is
-just one letter, which passes all matching options.
-
-The character @samp{|} at the beginning of the predicate text is used to
-indicate that a command should be piped to the following command, but
-only if @option{-pipe} is specified.
-
-It is built into GCC which switches take arguments and which do not.
-(You might think it would be useful to generalize this to allow each
-compiler's spec to say which switches take arguments.  But this cannot
-be done in a consistent fashion.  GCC cannot even decide which input
-files have been specified without knowing which switches take arguments,
-and it must know which input files to compile in order to tell which
-compilers to run).
-
-GCC also knows implicitly that arguments starting in @option{-l} are to be
-treated as compiler output files, and passed to the linker in their
-proper position among the other output files.
-
-@c man begin OPTIONS
-
 @node Submodel Options
 @section Hardware Models and Configurations
 @cindex submodel options
@@ -24816,6 +24236,582 @@ the implementation of the @file{libatomic} runtime library.
 
 @c man end
 
+@node Spec Files
+@section Specifying Subprocesses and the Switches to Pass to Them
+@cindex Spec Files
+
+@command{gcc} is a driver program.  It performs its job by invoking a
+sequence of other programs to do the work of compiling, assembling and
+linking.  GCC interprets its command-line parameters and uses these to
+deduce which programs it should invoke, and which command-line options
+it ought to place on their command lines.  This behavior is controlled
+by @dfn{spec strings}.  In most cases there is one spec string for each
+program that GCC can invoke, but a few programs have multiple spec
+strings to control their behavior.  The spec strings built into GCC can
+be overridden by using the @option{-specs=} command-line switch to specify
+a spec file.
+
+@dfn{Spec files} are plaintext files that are used to construct spec
+strings.  They consist of a sequence of directives separated by blank
+lines.  The type of directive is determined by the first non-whitespace
+character on the line, which can be one of the following:
+
+@table @code
+@item %@var{command}
+Issues a @var{command} to the spec file processor.  The commands that can
+appear here are:
+
+@table @code
+@item %include <@var{file}>
+@cindex @code{%include}
+Search for @var{file} and insert its text at the current point in the
+specs file.
+
+@item %include_noerr <@var{file}>
+@cindex @code{%include_noerr}
+Just like @samp{%include}, but do not generate an error message if the include
+file cannot be found.
+
+@item %rename @var{old_name} @var{new_name}
+@cindex @code{%rename}
+Rename the spec string @var{old_name} to @var{new_name}.
+
+@end table
+
+@item *[@var{spec_name}]:
+This tells the compiler to create, override or delete the named spec
+string.  All lines after this directive up to the next directive or
+blank line are considered to be the text for the spec string.  If this
+results in an empty string then the spec is deleted.  (Or, if the
+spec did not exist, then nothing happens.)  Otherwise, if the spec
+does not currently exist a new spec is created.  If the spec does
+exist then its contents are overridden by the text of this
+directive, unless the first character of that text is the @samp{+}
+character, in which case the text is appended to the spec.
+
+@item [@var{suffix}]:
+Creates a new @samp{[@var{suffix}] spec} pair.  All lines after this directive
+and up to the next directive or blank line are considered to make up the
+spec string for the indicated suffix.  When the compiler encounters an
+input file with the named suffix, it processes the spec string in
+order to work out how to compile that file.  For example:
+
+@smallexample
+.ZZ:
+z-compile -input %i
+@end smallexample
+
+This says that any input file whose name ends in @samp{.ZZ} should be
+passed to the program @samp{z-compile}, which should be invoked with the
+command-line switch @option{-input} and with the result of performing the
+@samp{%i} substitution.  (See below.)
+
+As an alternative to providing a spec string, the text following a
+suffix directive can be one of the following:
+
+@table @code
+@item @@@var{language}
+This says that the suffix is an alias for a known @var{language}.  This is
+similar to using the @option{-x} command-line switch to GCC to specify a
+language explicitly.  For example:
+
+@smallexample
+.ZZ:
+@@c++
+@end smallexample
+
+Says that .ZZ files are, in fact, C++ source files.
+
+@item #@var{name}
+This causes an error messages saying:
+
+@smallexample
+@var{name} compiler not installed on this system.
+@end smallexample
+@end table
+
+GCC already has an extensive list of suffixes built into it.
+This directive adds an entry to the end of the list of suffixes, but
+since the list is searched from the end backwards, it is effectively
+possible to override earlier entries using this technique.
+
+@end table
+
+GCC has the following spec strings built into it.  Spec files can
+override these strings or create their own.  Note that individual
+targets can also add their own spec strings to this list.
+
+@smallexample
+asm          Options to pass to the assembler
+asm_final    Options to pass to the assembler post-processor
+cpp          Options to pass to the C preprocessor
+cc1          Options to pass to the C compiler
+cc1plus      Options to pass to the C++ compiler
+endfile      Object files to include at the end of the link
+link         Options to pass to the linker
+lib          Libraries to include on the command line to the linker
+libgcc       Decides which GCC support library to pass to the linker
+linker       Sets the name of the linker
+predefines   Defines to be passed to the C preprocessor
+signed_char  Defines to pass to CPP to say whether @code{char} is signed
+             by default
+startfile    Object files to include at the start of the link
+@end smallexample
+
+Here is a small example of a spec file:
+
+@smallexample
+%rename lib                 old_lib
+
+*lib:
+--start-group -lgcc -lc -leval1 --end-group %(old_lib)
+@end smallexample
+
+This example renames the spec called @samp{lib} to @samp{old_lib} and
+then overrides the previous definition of @samp{lib} with a new one.
+The new definition adds in some extra command-line options before
+including the text of the old definition.
+
+@dfn{Spec strings} are a list of command-line options to be passed to their
+corresponding program.  In addition, the spec strings can contain
+@samp{%}-prefixed sequences to substitute variable text or to
+conditionally insert text into the command line.  Using these constructs
+it is possible to generate quite complex command lines.
+
+Here is a table of all defined @samp{%}-sequences for spec
+strings.  Note that spaces are not generated automatically around the
+results of expanding these sequences.  Therefore you can concatenate them
+together or combine them with constant text in a single argument.
+
+@table @code
+@item %%
+Substitute one @samp{%} into the program name or argument.
+
+@item %i
+Substitute the name of the input file being processed.
+
+@item %b
+Substitute the basename of the input file being processed.
+This is the substring up to (and not including) the last period
+and not including the directory.
+
+@item %B
+This is the same as @samp{%b}, but include the file suffix (text after
+the last period).
+
+@item %d
+Marks the argument containing or following the @samp{%d} as a
+temporary file name, so that that file is deleted if GCC exits
+successfully.  Unlike @samp{%g}, this contributes no text to the
+argument.
+
+@item %g@var{suffix}
+Substitute a file name that has suffix @var{suffix} and is chosen
+once per compilation, and mark the argument in the same way as
+@samp{%d}.  To reduce exposure to denial-of-service attacks, the file
+name is now chosen in a way that is hard to predict even when previously
+chosen file names are known.  For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
+might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}.  @var{suffix} matches
+the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
+treated exactly as if @samp{%O} had been preprocessed.  Previously, @samp{%g}
+was simply substituted with a file name chosen once per compilation,
+without regard to any appended suffix (which was therefore treated
+just like ordinary text), making such attacks more likely to succeed.
+
+@item %u@var{suffix}
+Like @samp{%g}, but generates a new temporary file name
+each time it appears instead of once per compilation.
+
+@item %U@var{suffix}
+Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
+new one if there is no such last file name.  In the absence of any
+@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
+the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
+involves the generation of two distinct file names, one
+for each @samp{%g.s} and another for each @samp{%U.s}.  Previously, @samp{%U} was
+simply substituted with a file name chosen for the previous @samp{%u},
+without regard to any appended suffix.
+
+@item %j@var{suffix}
+Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
+writable, and if @option{-save-temps} is not used; 
+otherwise, substitute the name
+of a temporary file, just like @samp{%u}.  This temporary file is not
+meant for communication between processes, but rather as a junk
+disposal mechanism.
+
+@item %|@var{suffix}
+@itemx %m@var{suffix}
+Like @samp{%g}, except if @option{-pipe} is in effect.  In that case
+@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
+all.  These are the two most common ways to instruct a program that it
+should read from standard input or write to standard output.  If you
+need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
+construct: see for example @file{f/lang-specs.h}.
+
+@item %.@var{SUFFIX}
+Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
+when it is subsequently output with @samp{%*}.  @var{SUFFIX} is
+terminated by the next space or %.
+
+@item %w
+Marks the argument containing or following the @samp{%w} as the
+designated output file of this compilation.  This puts the argument
+into the sequence of arguments that @samp{%o} substitutes.
+
+@item %o
+Substitutes the names of all the output files, with spaces
+automatically placed around them.  You should write spaces
+around the @samp{%o} as well or the results are undefined.
+@samp{%o} is for use in the specs for running the linker.
+Input files whose names have no recognized suffix are not compiled
+at all, but they are included among the output files, so they are
+linked.
+
+@item %O
+Substitutes the suffix for object files.  Note that this is
+handled specially when it immediately follows @samp{%g, %u, or %U},
+because of the need for those to form complete file names.  The
+handling is such that @samp{%O} is treated exactly as if it had already
+been substituted, except that @samp{%g, %u, and %U} do not currently
+support additional @var{suffix} characters following @samp{%O} as they do
+following, for example, @samp{.o}.
+
+@item %p
+Substitutes the standard macro predefinitions for the
+current target machine.  Use this when running @command{cpp}.
+
+@item %P
+Like @samp{%p}, but puts @samp{__} before and after the name of each
+predefined macro, except for macros that start with @samp{__} or with
+@samp{_@var{L}}, where @var{L} is an uppercase letter.  This is for ISO
+C@.
+
+@item %I
+Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
+@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
+@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
+and @option{-imultilib} as necessary.
+
+@item %s
+Current argument is the name of a library or startup file of some sort.
+Search for that file in a standard list of directories and substitute
+the full name found.  The current working directory is included in the
+list of directories scanned.
+
+@item %T
+Current argument is the name of a linker script.  Search for that file
+in the current list of directories to scan for libraries. If the file
+is located insert a @option{--script} option into the command line
+followed by the full path name found.  If the file is not found then
+generate an error message.  Note: the current working directory is not
+searched.
+
+@item %e@var{str}
+Print @var{str} as an error message.  @var{str} is terminated by a newline.
+Use this when inconsistent options are detected.
+
+@item %(@var{name})
+Substitute the contents of spec string @var{name} at this point.
+
+@item %x@{@var{option}@}
+Accumulate an option for @samp{%X}.
+
+@item %X
+Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
+spec string.
+
+@item %Y
+Output the accumulated assembler options specified by @option{-Wa}.
+
+@item %Z
+Output the accumulated preprocessor options specified by @option{-Wp}.
+
+@item %a
+Process the @code{asm} spec.  This is used to compute the
+switches to be passed to the assembler.
+
+@item %A
+Process the @code{asm_final} spec.  This is a spec string for
+passing switches to an assembler post-processor, if such a program is
+needed.
+
+@item %l
+Process the @code{link} spec.  This is the spec for computing the
+command line passed to the linker.  Typically it makes use of the
+@samp{%L %G %S %D and %E} sequences.
+
+@item %D
+Dump out a @option{-L} option for each directory that GCC believes might
+contain startup files.  If the target supports multilibs then the
+current multilib directory is prepended to each of these paths.
+
+@item %L
+Process the @code{lib} spec.  This is a spec string for deciding which
+libraries are included on the command line to the linker.
+
+@item %G
+Process the @code{libgcc} spec.  This is a spec string for deciding
+which GCC support library is included on the command line to the linker.
+
+@item %S
+Process the @code{startfile} spec.  This is a spec for deciding which
+object files are the first ones passed to the linker.  Typically
+this might be a file named @file{crt0.o}.
+
+@item %E
+Process the @code{endfile} spec.  This is a spec string that specifies
+the last object files that are passed to the linker.
+
+@item %C
+Process the @code{cpp} spec.  This is used to construct the arguments
+to be passed to the C preprocessor.
+
+@item %1
+Process the @code{cc1} spec.  This is used to construct the options to be
+passed to the actual C compiler (@command{cc1}).
+
+@item %2
+Process the @code{cc1plus} spec.  This is used to construct the options to be
+passed to the actual C++ compiler (@command{cc1plus}).
+
+@item %*
+Substitute the variable part of a matched option.  See below.
+Note that each comma in the substituted string is replaced by
+a single space.
+
+@item %<@code{S}
+Remove all occurrences of @code{-S} from the command line.  Note---this
+command is position dependent.  @samp{%} commands in the spec string
+before this one see @code{-S}, @samp{%} commands in the spec string
+after this one do not.
+
+@item %:@var{function}(@var{args})
+Call the named function @var{function}, passing it @var{args}.
+@var{args} is first processed as a nested spec string, then split
+into an argument vector in the usual fashion.  The function returns
+a string which is processed as if it had appeared literally as part
+of the current spec.
+
+The following built-in spec functions are provided:
+
+@table @code
+@item @code{getenv}
+The @code{getenv} spec function takes two arguments: an environment
+variable name and a string.  If the environment variable is not
+defined, a fatal error is issued.  Otherwise, the return value is the
+value of the environment variable concatenated with the string.  For
+example, if @env{TOPDIR} is defined as @file{/path/to/top}, then:
+
+@smallexample
+%:getenv(TOPDIR /include)
+@end smallexample
+
+expands to @file{/path/to/top/include}.
+
+@item @code{if-exists}
+The @code{if-exists} spec function takes one argument, an absolute
+pathname to a file.  If the file exists, @code{if-exists} returns the
+pathname.  Here is a small example of its usage:
+
+@smallexample
+*startfile:
+crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
+@end smallexample
+
+@item @code{if-exists-else}
+The @code{if-exists-else} spec function is similar to the @code{if-exists}
+spec function, except that it takes two arguments.  The first argument is
+an absolute pathname to a file.  If the file exists, @code{if-exists-else}
+returns the pathname.  If it does not exist, it returns the second argument.
+This way, @code{if-exists-else} can be used to select one file or another,
+based on the existence of the first.  Here is a small example of its usage:
+
+@smallexample
+*startfile:
+crt0%O%s %:if-exists(crti%O%s) \
+%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
+@end smallexample
+
+@item @code{replace-outfile}
+The @code{replace-outfile} spec function takes two arguments.  It looks for the
+first argument in the outfiles array and replaces it with the second argument.  Here
+is a small example of its usage:
+
+@smallexample
+%@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
+@end smallexample
+
+@item @code{remove-outfile}
+The @code{remove-outfile} spec function takes one argument.  It looks for the
+first argument in the outfiles array and removes it.  Here is a small example
+its usage:
+
+@smallexample
+%:remove-outfile(-lm)
+@end smallexample
+
+@item @code{pass-through-libs}
+The @code{pass-through-libs} spec function takes any number of arguments.  It
+finds any @option{-l} options and any non-options ending in @file{.a} (which it
+assumes are the names of linker input library archive files) and returns a
+result containing all the found arguments each prepended by
+@option{-plugin-opt=-pass-through=} and joined by spaces.  This list is
+intended to be passed to the LTO linker plugin.
+
+@smallexample
+%:pass-through-libs(%G %L %G)
+@end smallexample
+
+@item @code{print-asm-header}
+The @code{print-asm-header} function takes no arguments and simply
+prints a banner like:
+
+@smallexample
+Assembler options
+=================
+
+Use "-Wa,OPTION" to pass "OPTION" to the assembler.
+@end smallexample
+
+It is used to separate compiler options from assembler options
+in the @option{--target-help} output.
+@end table
+
+@item %@{@code{S}@}
+Substitutes the @code{-S} switch, if that switch is given to GCC@.
+If that switch is not specified, this substitutes nothing.  Note that
+the leading dash is omitted when specifying this option, and it is
+automatically inserted if the substitution is performed.  Thus the spec
+string @samp{%@{foo@}} matches the command-line option @option{-foo}
+and outputs the command-line option @option{-foo}.
+
+@item %W@{@code{S}@}
+Like %@{@code{S}@} but mark last argument supplied within as a file to be
+deleted on failure.
+
+@item %@{@code{S}*@}
+Substitutes all the switches specified to GCC whose names start
+with @code{-S}, but which also take an argument.  This is used for
+switches like @option{-o}, @option{-D}, @option{-I}, etc.
+GCC considers @option{-o foo} as being
+one switch whose name starts with @samp{o}.  %@{o*@} substitutes this
+text, including the space.  Thus two arguments are generated.
+
+@item %@{@code{S}*&@code{T}*@}
+Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
+(the order of @code{S} and @code{T} in the spec is not significant).
+There can be any number of ampersand-separated variables; for each the
+wild card is optional.  Useful for CPP as @samp{%@{D*&U*&A*@}}.
+
+@item %@{@code{S}:@code{X}@}
+Substitutes @code{X}, if the @option{-S} switch is given to GCC@.
+
+@item %@{!@code{S}:@code{X}@}
+Substitutes @code{X}, if the @option{-S} switch is @emph{not} given to GCC@.
+
+@item %@{@code{S}*:@code{X}@}
+Substitutes @code{X} if one or more switches whose names start with
+@code{-S} are specified to GCC@.  Normally @code{X} is substituted only
+once, no matter how many such switches appeared.  However, if @code{%*}
+appears somewhere in @code{X}, then @code{X} is substituted once
+for each matching switch, with the @code{%*} replaced by the part of
+that switch matching the @code{*}.
+
+If @code{%*} appears as the last part of a spec sequence then a space
+is added after the end of the last substitution.  If there is more
+text in the sequence, however, then a space is not generated.  This
+allows the @code{%*} substitution to be used as part of a larger
+string.  For example, a spec string like this:
+
+@smallexample
+%@{mcu=*:--script=%*/memory.ld@}
+@end smallexample
+
+@noindent
+when matching an option like @option{-mcu=newchip} produces:
+
+@smallexample
+--script=newchip/memory.ld
+@end smallexample
+
+@item %@{.@code{S}:@code{X}@}
+Substitutes @code{X}, if processing a file with suffix @code{S}.
+
+@item %@{!.@code{S}:@code{X}@}
+Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
+
+@item %@{,@code{S}:@code{X}@}
+Substitutes @code{X}, if processing a file for language @code{S}.
+
+@item %@{!,@code{S}:@code{X}@}
+Substitutes @code{X}, if not processing a file for language @code{S}.
+
+@item %@{@code{S}|@code{P}:@code{X}@}
+Substitutes @code{X} if either @code{-S} or @code{-P} is given to
+GCC@.  This may be combined with @samp{!}, @samp{.}, @samp{,}, and
+@code{*} sequences as well, although they have a stronger binding than
+the @samp{|}.  If @code{%*} appears in @code{X}, all of the
+alternatives must be starred, and only the first matching alternative
+is substituted.
+
+For example, a spec string like this:
+
+@smallexample
+%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
+@end smallexample
+
+@noindent
+outputs the following command-line options from the following input
+command-line options:
+
+@smallexample
+fred.c        -foo -baz
+jim.d         -bar -boggle
+-d fred.c     -foo -baz -boggle
+-d jim.d      -bar -baz -boggle
+@end smallexample
+
+@item %@{S:X; T:Y; :D@}
+
+If @code{S} is given to GCC, substitutes @code{X}; else if @code{T} is
+given to GCC, substitutes @code{Y}; else substitutes @code{D}.  There can
+be as many clauses as you need.  This may be combined with @code{.},
+@code{,}, @code{!}, @code{|}, and @code{*} as needed.
+
+
+@end table
+
+The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
+construct may contain other nested @samp{%} constructs or spaces, or
+even newlines.  They are processed as usual, as described above.
+Trailing white space in @code{X} is ignored.  White space may also
+appear anywhere on the left side of the colon in these constructs,
+except between @code{.} or @code{*} and the corresponding word.
+
+The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
+handled specifically in these constructs.  If another value of
+@option{-O} or the negated form of a @option{-f}, @option{-m}, or
+@option{-W} switch is found later in the command line, the earlier
+switch value is ignored, except with @{@code{S}*@} where @code{S} is
+just one letter, which passes all matching options.
+
+The character @samp{|} at the beginning of the predicate text is used to
+indicate that a command should be piped to the following command, but
+only if @option{-pipe} is specified.
+
+It is built into GCC which switches take arguments and which do not.
+(You might think it would be useful to generalize this to allow each
+compiler's spec to say which switches take arguments.  But this cannot
+be done in a consistent fashion.  GCC cannot even decide which input
+files have been specified without knowing which switches take arguments,
+and it must know which input files to compile in order to tell which
+compilers to run).
+
+GCC also knows implicitly that arguments starting in @option{-l} are to be
+treated as compiler output files, and passed to the linker in their
+proper position among the other output files.
+
 @node Environment Variables
 @section Environment Variables Affecting GCC
 @cindex environment variables