visus
/
toolchain-gcc-arm-embedded

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2020 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Spec Files (Using the GNU Compiler Collection (GCC))</title>

<meta name="description" content="Spec Files (Using the GNU Compiler Collection (GCC))">
<meta name="keywords" content="Spec Files (Using the GNU Compiler Collection (GCC))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Invoking-GCC.html#Invoking-GCC" rel="up" title="Invoking GCC">
<link href="Environment-Variables.html#Environment-Variables" rel="next" title="Environment Variables">
<link href="zSeries-Options.html#zSeries-Options" rel="prev" title="zSeries Options">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="Spec-Files"></a>
<div class="header">
<p>
Next: <a href="Environment-Variables.html#Environment-Variables" accesskey="n" rel="next">Environment Variables</a>, Previous: <a href="Submodel-Options.html#Submodel-Options" accesskey="p" rel="prev">Submodel Options</a>, Up: <a href="Invoking-GCC.html#Invoking-GCC" accesskey="u" rel="up">Invoking GCC</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Specifying-Subprocesses-and-the-Switches-to-Pass-to-Them"></a>
<h3 class="section">3.20 Specifying Subprocesses and the Switches to Pass to Them</h3>
<a name="index-Spec-Files"></a>

<p><code>gcc</code> 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 <em>spec strings</em>.  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 <samp>-specs=</samp> command-line switch to specify
a spec file.
</p>
<p><em>Spec files</em> are plain-text 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:
</p>
<dl compact="compact">
<dt><code>%<var>command</var></code></dt>
<dd><p>Issues a <var>command</var> to the spec file processor.  The commands that can
appear here are:
</p>
<dl compact="compact">
<dt><code>%include &lt;<var>file</var>&gt;</code></dt>
<dd><a name="index-_0025include"></a>
<p>Search for <var>file</var> and insert its text at the current point in the
specs file.
</p>
</dd>
<dt><code>%include_noerr &lt;<var>file</var>&gt;</code></dt>
<dd><a name="index-_0025include_005fnoerr"></a>
<p>Just like &lsquo;<samp>%include</samp>&rsquo;, but do not generate an error message if the include
file cannot be found.
</p>
</dd>
<dt><code>%rename <var>old_name</var> <var>new_name</var></code></dt>
<dd><a name="index-_0025rename"></a>
<p>Rename the spec string <var>old_name</var> to <var>new_name</var>.
</p>
</dd>
</dl>

</dd>
<dt><code>*[<var>spec_name</var>]:</code></dt>
<dd><p>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 &lsquo;<samp>+</samp>&rsquo;
character, in which case the text is appended to the spec.
</p>
</dd>
<dt><code>[<var>suffix</var>]:</code></dt>
<dd><p>Creates a new &lsquo;<samp>[<var>suffix</var>] spec</samp>&rsquo; 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:
</p>
<div class="smallexample">
<pre class="smallexample">.ZZ:
z-compile -input %i
</pre></div>

<p>This says that any input file whose name ends in &lsquo;<samp>.ZZ</samp>&rsquo; should be
passed to the program &lsquo;<samp>z-compile</samp>&rsquo;, which should be invoked with the
command-line switch <samp>-input</samp> and with the result of performing the
&lsquo;<samp>%i</samp>&rsquo; substitution.  (See below.)
</p>
<p>As an alternative to providing a spec string, the text following a
suffix directive can be one of the following:
</p>
<dl compact="compact">
<dt><code>@<var>language</var></code></dt>
<dd><p>This says that the suffix is an alias for a known <var>language</var>.  This is
similar to using the <samp>-x</samp> command-line switch to GCC to specify a
language explicitly.  For example:
</p>
<div class="smallexample">
<pre class="smallexample">.ZZ:
@c++
</pre></div>

<p>Says that .ZZ files are, in fact, C++ source files.
</p>
</dd>
<dt><code>#<var>name</var></code></dt>
<dd><p>This causes an error messages saying:
</p>
<div class="smallexample">
<pre class="smallexample"><var>name</var> compiler not installed on this system.
</pre></div>
</dd>
</dl>

<p>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.
</p>
</dd>
</dl>

<p>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.
</p>
<div class="smallexample">
<pre class="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</code> is signed
             by default
startfile    Object files to include at the start of the link
</pre></div>

<p>Here is a small example of a spec file:
</p>
<div class="smallexample">
<pre class="smallexample">%rename lib                 old_lib

*lib:
--start-group -lgcc -lc -leval1 --end-group %(old_lib)
</pre></div>

<p>This example renames the spec called &lsquo;<samp>lib</samp>&rsquo; to &lsquo;<samp>old_lib</samp>&rsquo; and
then overrides the previous definition of &lsquo;<samp>lib</samp>&rsquo; with a new one.
The new definition adds in some extra command-line options before
including the text of the old definition.
</p>
<p><em>Spec strings</em> are a list of command-line options to be passed to their
corresponding program.  In addition, the spec strings can contain
&lsquo;<samp>%</samp>&rsquo;-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.
</p>
<p>Here is a table of all defined &lsquo;<samp>%</samp>&rsquo;-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.
</p>
<dl compact="compact">
<dt><code>%%</code></dt>
<dd><p>Substitute one &lsquo;<samp>%</samp>&rsquo; into the program name or argument.
</p>
</dd>
<dt><code>%i</code></dt>
<dd><p>Substitute the name of the input file being processed.
</p>
</dd>
<dt><code>%b</code></dt>
<dd><p>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.
</p>
</dd>
<dt><code>%B</code></dt>
<dd><p>This is the same as &lsquo;<samp>%b</samp>&rsquo;, but include the file suffix (text after
the last period).
</p>
</dd>
<dt><code>%d</code></dt>
<dd><p>Marks the argument containing or following the &lsquo;<samp>%d</samp>&rsquo; as a
temporary file name, so that that file is deleted if GCC exits
successfully.  Unlike &lsquo;<samp>%g</samp>&rsquo;, this contributes no text to the
argument.
</p>
</dd>
<dt><code>%g<var>suffix</var></code></dt>
<dd><p>Substitute a file name that has suffix <var>suffix</var> and is chosen
once per compilation, and mark the argument in the same way as
&lsquo;<samp>%d</samp>&rsquo;.  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, &lsquo;<samp>%g.s &hellip; %g.o &hellip; %g.s</samp>&rsquo;
might turn into &lsquo;<samp>ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s</samp>&rsquo;.  <var>suffix</var> matches
the regexp &lsquo;<samp>[.A-Za-z]*</samp>&rsquo; or the special string &lsquo;<samp>%O</samp>&rsquo;, which is
treated exactly as if &lsquo;<samp>%O</samp>&rsquo; had been preprocessed.  Previously, &lsquo;<samp>%g</samp>&rsquo;
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.
</p>
</dd>
<dt><code>%u<var>suffix</var></code></dt>
<dd><p>Like &lsquo;<samp>%g</samp>&rsquo;, but generates a new temporary file name
each time it appears instead of once per compilation.
</p>
</dd>
<dt><code>%U<var>suffix</var></code></dt>
<dd><p>Substitutes the last file name generated with &lsquo;<samp>%u<var>suffix</var></samp>&rsquo;, generating a
new one if there is no such last file name.  In the absence of any
&lsquo;<samp>%u<var>suffix</var></samp>&rsquo;, this is just like &lsquo;<samp>%g<var>suffix</var></samp>&rsquo;, except they don&rsquo;t share
the same suffix <em>space</em>, so &lsquo;<samp>%g.s &hellip; %U.s &hellip; %g.s &hellip; %U.s</samp>&rsquo;
involves the generation of two distinct file names, one
for each &lsquo;<samp>%g.s</samp>&rsquo; and another for each &lsquo;<samp>%U.s</samp>&rsquo;.  Previously, &lsquo;<samp>%U</samp>&rsquo; was
simply substituted with a file name chosen for the previous &lsquo;<samp>%u</samp>&rsquo;,
without regard to any appended suffix.
</p>
</dd>
<dt><code>%j<var>suffix</var></code></dt>
<dd><p>Substitutes the name of the <code>HOST_BIT_BUCKET</code>, if any, and if it is
writable, and if <samp>-save-temps</samp> is not used; 
otherwise, substitute the name
of a temporary file, just like &lsquo;<samp>%u</samp>&rsquo;.  This temporary file is not
meant for communication between processes, but rather as a junk
disposal mechanism.
</p>
</dd>
<dt><code>%|<var>suffix</var></code></dt>
<dt><code>%m<var>suffix</var></code></dt>
<dd><p>Like &lsquo;<samp>%g</samp>&rsquo;, except if <samp>-pipe</samp> is in effect.  In that case
&lsquo;<samp>%|</samp>&rsquo; substitutes a single dash and &lsquo;<samp>%m</samp>&rsquo; 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 &lsquo;<samp>%{pipe:<code>X</code>}</samp>&rsquo;
construct: see for example <samp>gcc/fortran/lang-specs.h</samp>.
</p>
</dd>
<dt><code>%.<var>SUFFIX</var></code></dt>
<dd><p>Substitutes <var>.SUFFIX</var> for the suffixes of a matched switch&rsquo;s args
when it is subsequently output with &lsquo;<samp>%*</samp>&rsquo;.  <var>SUFFIX</var> is
terminated by the next space or %.
</p>
</dd>
<dt><code>%w</code></dt>
<dd><p>Marks the argument containing or following the &lsquo;<samp>%w</samp>&rsquo; as the
designated output file of this compilation.  This puts the argument
into the sequence of arguments that &lsquo;<samp>%o</samp>&rsquo; substitutes.
</p>
</dd>
<dt><code>%o</code></dt>
<dd><p>Substitutes the names of all the output files, with spaces
automatically placed around them.  You should write spaces
around the &lsquo;<samp>%o</samp>&rsquo; as well or the results are undefined.
&lsquo;<samp>%o</samp>&rsquo; 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.
</p>
</dd>
<dt><code>%O</code></dt>
<dd><p>Substitutes the suffix for object files.  Note that this is
handled specially when it immediately follows &lsquo;<samp>%g, %u, or %U</samp>&rsquo;,
because of the need for those to form complete file names.  The
handling is such that &lsquo;<samp>%O</samp>&rsquo; is treated exactly as if it had already
been substituted, except that &lsquo;<samp>%g, %u, and %U</samp>&rsquo; do not currently
support additional <var>suffix</var> characters following &lsquo;<samp>%O</samp>&rsquo; as they do
following, for example, &lsquo;<samp>.o</samp>&rsquo;.
</p>
</dd>
<dt><code>%p</code></dt>
<dd><p>Substitutes the standard macro predefinitions for the
current target machine.  Use this when running <code>cpp</code>.
</p>
</dd>
<dt><code>%P</code></dt>
<dd><p>Like &lsquo;<samp>%p</samp>&rsquo;, but puts &lsquo;<samp>__</samp>&rsquo; before and after the name of each
predefined macro, except for macros that start with &lsquo;<samp>__</samp>&rsquo; or with
&lsquo;<samp>_<var>L</var></samp>&rsquo;, where <var>L</var> is an uppercase letter.  This is for ISO
C.
</p>
</dd>
<dt><code>%I</code></dt>
<dd><p>Substitute any of <samp>-iprefix</samp> (made from <code>GCC_EXEC_PREFIX</code>),
<samp>-isysroot</samp> (made from <code>TARGET_SYSTEM_ROOT</code>),
<samp>-isystem</samp> (made from <code>COMPILER_PATH</code> and <samp>-B</samp> options)
and <samp>-imultilib</samp> as necessary.
</p>
</dd>
<dt><code>%s</code></dt>
<dd><p>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.
</p>
</dd>
<dt><code>%T</code></dt>
<dd><p>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 <samp>--script</samp> 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.
</p>
</dd>
<dt><code>%e<var>str</var></code></dt>
<dd><p>Print <var>str</var> as an error message.  <var>str</var> is terminated by a newline.
Use this when inconsistent options are detected.
</p>
</dd>
<dt><code>%(<var>name</var>)</code></dt>
<dd><p>Substitute the contents of spec string <var>name</var> at this point.
</p>
</dd>
<dt><code>%x{<var>option</var>}</code></dt>
<dd><p>Accumulate an option for &lsquo;<samp>%X</samp>&rsquo;.
</p>
</dd>
<dt><code>%X</code></dt>
<dd><p>Output the accumulated linker options specified by <samp>-Wl</samp> or a &lsquo;<samp>%x</samp>&rsquo;
spec string.
</p>
</dd>
<dt><code>%Y</code></dt>
<dd><p>Output the accumulated assembler options specified by <samp>-Wa</samp>.
</p>
</dd>
<dt><code>%Z</code></dt>
<dd><p>Output the accumulated preprocessor options specified by <samp>-Wp</samp>.
</p>
</dd>
<dt><code>%a</code></dt>
<dd><p>Process the <code>asm</code> spec.  This is used to compute the
switches to be passed to the assembler.
</p>
</dd>
<dt><code>%A</code></dt>
<dd><p>Process the <code>asm_final</code> spec.  This is a spec string for
passing switches to an assembler post-processor, if such a program is
needed.
</p>
</dd>
<dt><code>%l</code></dt>
<dd><p>Process the <code>link</code> spec.  This is the spec for computing the
command line passed to the linker.  Typically it makes use of the
&lsquo;<samp>%L %G %S %D and %E</samp>&rsquo; sequences.
</p>
</dd>
<dt><code>%D</code></dt>
<dd><p>Dump out a <samp>-L</samp> 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.
</p>
</dd>
<dt><code>%L</code></dt>
<dd><p>Process the <code>lib</code> spec.  This is a spec string for deciding which
libraries are included on the command line to the linker.
</p>
</dd>
<dt><code>%G</code></dt>
<dd><p>Process the <code>libgcc</code> spec.  This is a spec string for deciding
which GCC support library is included on the command line to the linker.
</p>
</dd>
<dt><code>%S</code></dt>
<dd><p>Process the <code>startfile</code> 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 <samp>crt0.o</samp>.
</p>
</dd>
<dt><code>%E</code></dt>
<dd><p>Process the <code>endfile</code> spec.  This is a spec string that specifies
the last object files that are passed to the linker.
</p>
</dd>
<dt><code>%C</code></dt>
<dd><p>Process the <code>cpp</code> spec.  This is used to construct the arguments
to be passed to the C preprocessor.
</p>
</dd>
<dt><code>%1</code></dt>
<dd><p>Process the <code>cc1</code> spec.  This is used to construct the options to be
passed to the actual C compiler (<code>cc1</code>).
</p>
</dd>
<dt><code>%2</code></dt>
<dd><p>Process the <code>cc1plus</code> spec.  This is used to construct the options to be
passed to the actual C++ compiler (<code>cc1plus</code>).
</p>
</dd>
<dt><code>%*</code></dt>
<dd><p>Substitute the variable part of a matched option.  See below.
Note that each comma in the substituted string is replaced by
a single space.
</p>
</dd>
<dt><code>%&lt;S</code></dt>
<dd><p>Remove all occurrences of <code>-S</code> from the command line.  Note&mdash;this
command is position dependent.  &lsquo;<samp>%</samp>&rsquo; commands in the spec string
before this one see <code>-S</code>, &lsquo;<samp>%</samp>&rsquo; commands in the spec string
after this one do not.
</p>
</dd>
<dt><code>%:<var>function</var>(<var>args</var>)</code></dt>
<dd><p>Call the named function <var>function</var>, passing it <var>args</var>.
<var>args</var> 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.
</p>
<p>The following built-in spec functions are provided:
</p>
<dl compact="compact">
<dt><code><code>getenv</code></code></dt>
<dd><p>The <code>getenv</code> 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 <code>TOPDIR</code> is defined as <samp>/path/to/top</samp>, then:
</p>
<div class="smallexample">
<pre class="smallexample">%:getenv(TOPDIR /include)
</pre></div>

<p>expands to <samp>/path/to/top/include</samp>.
</p>
</dd>
<dt><code><code>if-exists</code></code></dt>
<dd><p>The <code>if-exists</code> spec function takes one argument, an absolute
pathname to a file.  If the file exists, <code>if-exists</code> returns the
pathname.  Here is a small example of its usage:
</p>
<div class="smallexample">
<pre class="smallexample">*startfile:
crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
</pre></div>

</dd>
<dt><code><code>if-exists-else</code></code></dt>
<dd><p>The <code>if-exists-else</code> spec function is similar to the <code>if-exists</code>
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</code>
returns the pathname.  If it does not exist, it returns the second argument.
This way, <code>if-exists-else</code> can be used to select one file or another,
based on the existence of the first.  Here is a small example of its usage:
</p>
<div class="smallexample">
<pre class="smallexample">*startfile:
crt0%O%s %:if-exists(crti%O%s) \
%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
</pre></div>

</dd>
<dt><code><code>replace-outfile</code></code></dt>
<dd><p>The <code>replace-outfile</code> 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:
</p>
<div class="smallexample">
<pre class="smallexample">%{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)}
</pre></div>

</dd>
<dt><code><code>remove-outfile</code></code></dt>
<dd><p>The <code>remove-outfile</code> 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:
</p>
<div class="smallexample">
<pre class="smallexample">%:remove-outfile(-lm)
</pre></div>

</dd>
<dt><code><code>pass-through-libs</code></code></dt>
<dd><p>The <code>pass-through-libs</code> spec function takes any number of arguments.  It
finds any <samp>-l</samp> options and any non-options ending in <samp>.a</samp> (which it
assumes are the names of linker input library archive files) and returns a
result containing all the found arguments each prepended by
<samp>-plugin-opt=-pass-through=</samp> and joined by spaces.  This list is
intended to be passed to the LTO linker plugin.
</p>
<div class="smallexample">
<pre class="smallexample">%:pass-through-libs(%G %L %G)
</pre></div>

</dd>
<dt><code><code>print-asm-header</code></code></dt>
<dd><p>The <code>print-asm-header</code> function takes no arguments and simply
prints a banner like:
</p>
<div class="smallexample">
<pre class="smallexample">Assembler options
=================

Use &quot;-Wa,OPTION&quot; to pass &quot;OPTION&quot; to the assembler.
</pre></div>

<p>It is used to separate compiler options from assembler options
in the <samp>--target-help</samp> output.
</p></dd>
</dl>

</dd>
<dt><code>%{S}</code></dt>
<dd><p>Substitutes the <code>-S</code> 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 &lsquo;<samp>%{foo}</samp>&rsquo; matches the command-line option <samp>-foo</samp>
and outputs the command-line option <samp>-foo</samp>.
</p>
</dd>
<dt><code>%W{S}</code></dt>
<dd><p>Like %{<code>S</code>} but mark last argument supplied within as a file to be
deleted on failure.
</p>
</dd>
<dt><code>%{S*}</code></dt>
<dd><p>Substitutes all the switches specified to GCC whose names start
with <code>-S</code>, but which also take an argument.  This is used for
switches like <samp>-o</samp>, <samp>-D</samp>, <samp>-I</samp>, etc.
GCC considers <samp>-o foo</samp> as being
one switch whose name starts with &lsquo;<samp>o</samp>&rsquo;.  %{o*} substitutes this
text, including the space.  Thus two arguments are generated.
</p>
</dd>
<dt><code>%{S*&amp;T*}</code></dt>
<dd><p>Like %{<code>S</code>*}, but preserve order of <code>S</code> and <code>T</code> options
(the order of <code>S</code> and <code>T</code> 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 &lsquo;<samp>%{D*&amp;U*&amp;A*}</samp>&rsquo;.
</p>
</dd>
<dt><code>%{S:X}</code></dt>
<dd><p>Substitutes <code>X</code>, if the <samp>-S</samp> switch is given to GCC.
</p>
</dd>
<dt><code>%{!S:X}</code></dt>
<dd><p>Substitutes <code>X</code>, if the <samp>-S</samp> switch is <em>not</em> given to GCC.
</p>
</dd>
<dt><code>%{S*:X}</code></dt>
<dd><p>Substitutes <code>X</code> if one or more switches whose names start with
<code>-S</code> are specified to GCC.  Normally <code>X</code> is substituted only
once, no matter how many such switches appeared.  However, if <code>%*</code>
appears somewhere in <code>X</code>, then <code>X</code> is substituted once
for each matching switch, with the <code>%*</code> replaced by the part of
that switch matching the <code>*</code>.
</p>
<p>If <code>%*</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>%*</code> substitution to be used as part of a larger
string.  For example, a spec string like this:
</p>
<div class="smallexample">
<pre class="smallexample">%{mcu=*:--script=%*/memory.ld}
</pre></div>

<p>when matching an option like <samp>-mcu=newchip</samp> produces:
</p>
<div class="smallexample">
<pre class="smallexample">--script=newchip/memory.ld
</pre></div>

</dd>
<dt><code>%{.S:X}</code></dt>
<dd><p>Substitutes <code>X</code>, if processing a file with suffix <code>S</code>.
</p>
</dd>
<dt><code>%{!.S:X}</code></dt>
<dd><p>Substitutes <code>X</code>, if <em>not</em> processing a file with suffix <code>S</code>.
</p>
</dd>
<dt><code>%{,S:X}</code></dt>
<dd><p>Substitutes <code>X</code>, if processing a file for language <code>S</code>.
</p>
</dd>
<dt><code>%{!,S:X}</code></dt>
<dd><p>Substitutes <code>X</code>, if not processing a file for language <code>S</code>.
</p>
</dd>
<dt><code>%{S|P:X}</code></dt>
<dd><p>Substitutes <code>X</code> if either <code>-S</code> or <code>-P</code> is given to
GCC.  This may be combined with &lsquo;<samp>!</samp>&rsquo;, &lsquo;<samp>.</samp>&rsquo;, &lsquo;<samp>,</samp>&rsquo;, and
<code>*</code> sequences as well, although they have a stronger binding than
the &lsquo;<samp>|</samp>&rsquo;.  If <code>%*</code> appears in <code>X</code>, all of the
alternatives must be starred, and only the first matching alternative
is substituted.
</p>
<p>For example, a spec string like this:
</p>
<div class="smallexample">
<pre class="smallexample">%{.c:-foo} %{!.c:-bar} %{.c|d:-baz} %{!.c|d:-boggle}
</pre></div>

<p>outputs the following command-line options from the following input
command-line options:
</p>
<div class="smallexample">
<pre class="smallexample">fred.c        -foo -baz
jim.d         -bar -boggle
-d fred.c     -foo -baz -boggle
-d jim.d      -bar -baz -boggle
</pre></div>

</dd>
<dt><code>%{S:X; T:Y; :D}</code></dt>
<dd>
<p>If <code>S</code> is given to GCC, substitutes <code>X</code>; else if <code>T</code> is
given to GCC, substitutes <code>Y</code>; else substitutes <code>D</code>.  There can
be as many clauses as you need.  This may be combined with <code>.</code>,
<code>,</code>, <code>!</code>, <code>|</code>, and <code>*</code> as needed.
</p>

</dd>
</dl>

<p>The switch matching text <code>S</code> in a &lsquo;<samp>%{S}</samp>&rsquo;, &lsquo;<samp>%{S:X}</samp>&rsquo;
or similar construct can use a backslash to ignore the special meaning
of the character following it, thus allowing literal matching of a
character that is otherwise specially treated.  For example,
&lsquo;<samp>%{std=iso9899\:1999:X}</samp>&rsquo; substitutes <code>X</code> if the
<samp>-std=iso9899:1999</samp> option is given.
</p>
<p>The conditional text <code>X</code> in a &lsquo;<samp>%{S:X}</samp>&rsquo; or similar
construct may contain other nested &lsquo;<samp>%</samp>&rsquo; constructs or spaces, or
even newlines.  They are processed as usual, as described above.
Trailing white space in <code>X</code> is ignored.  White space may also
appear anywhere on the left side of the colon in these constructs,
except between <code>.</code> or <code>*</code> and the corresponding word.
</p>
<p>The <samp>-O</samp>, <samp>-f</samp>, <samp>-m</samp>, and <samp>-W</samp> switches are
handled specifically in these constructs.  If another value of
<samp>-O</samp> or the negated form of a <samp>-f</samp>, <samp>-m</samp>, or
<samp>-W</samp> switch is found later in the command line, the earlier
switch value is ignored, except with {<code>S</code>*} where <code>S</code> is
just one letter, which passes all matching options.
</p>
<p>The character &lsquo;<samp>|</samp>&rsquo; at the beginning of the predicate text is used to
indicate that a command should be piped to the following command, but
only if <samp>-pipe</samp> is specified.
</p>
<p>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&rsquo;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).
</p>
<p>GCC also knows implicitly that arguments starting in <samp>-l</samp> are to be
treated as compiler output files, and passed to the linker in their
proper position among the other output files.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Environment-Variables.html#Environment-Variables" accesskey="n" rel="next">Environment Variables</a>, Previous: <a href="Submodel-Options.html#Submodel-Options" accesskey="p" rel="prev">Submodel Options</a>, Up: <a href="Invoking-GCC.html#Invoking-GCC" accesskey="u" rel="up">Invoking GCC</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
</div>


</body>
</html>