728 lines
31 KiB
HTML
728 lines
31 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<!-- Copyright (C) 1988-2016 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 5.2, http://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<title>Using the GNU Compiler Collection (GCC): Spec Files</title>
|
|
|
|
<meta name="description" content="Using the GNU Compiler Collection (GCC): Spec Files">
|
|
<meta name="keywords" content="Using the GNU Compiler Collection (GCC): Spec Files">
|
|
<meta name="resource-type" content="document">
|
|
<meta name="distribution" content="global">
|
|
<meta name="Generator" content="makeinfo">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<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.smallquotation {font-size: smaller}
|
|
div.display {margin-left: 3.2em}
|
|
div.example {margin-left: 3.2em}
|
|
div.indentedblock {margin-left: 3.2em}
|
|
div.lisp {margin-left: 3.2em}
|
|
div.smalldisplay {margin-left: 3.2em}
|
|
div.smallexample {margin-left: 3.2em}
|
|
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
|
|
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.nocodebreak {white-space:nowrap}
|
|
span.nolinebreak {white-space:nowrap}
|
|
span.roman {font-family:serif; font-weight:normal}
|
|
span.sansserif {font-family:sans-serif; font-weight:normal}
|
|
ul.no-bullet {list-style: none}
|
|
-->
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
|
|
<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> [<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.19 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 <<var>file</var>></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 <<var>file</var>></code></dt>
|
|
<dd><a name="index-_0025include_005fnoerr"></a>
|
|
<p>Just like ‘<samp>%include</samp>’, 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 ‘<samp>+</samp>’
|
|
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 ‘<samp>[<var>suffix</var>] spec</samp>’ 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 ‘<samp>.ZZ</samp>’ should be
|
|
passed to the program ‘<samp>z-compile</samp>’, which should be invoked with the
|
|
command-line switch <samp>-input</samp> and with the result of performing the
|
|
‘<samp>%i</samp>’ 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 ‘<samp>lib</samp>’ to ‘<samp>old_lib</samp>’ and
|
|
then overrides the previous definition of ‘<samp>lib</samp>’ 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
|
|
‘<samp>%</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.
|
|
</p>
|
|
<p>Here is a table of all defined ‘<samp>%</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.
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>%%</code></dt>
|
|
<dd><p>Substitute one ‘<samp>%</samp>’ 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 ‘<samp>%b</samp>’, 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 ‘<samp>%d</samp>’ as a
|
|
temporary file name, so that that file is deleted if GCC exits
|
|
successfully. Unlike ‘<samp>%g</samp>’, 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
|
|
‘<samp>%d</samp>’. 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 … %g.o … %g.s</samp>’
|
|
might turn into ‘<samp>ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s</samp>’. <var>suffix</var> matches
|
|
the regexp ‘<samp>[.A-Za-z]*</samp>’ or the special string ‘<samp>%O</samp>’, which is
|
|
treated exactly as if ‘<samp>%O</samp>’ had been preprocessed. Previously, ‘<samp>%g</samp>’
|
|
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 ‘<samp>%g</samp>’, 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 ‘<samp>%u<var>suffix</var></samp>’, generating a
|
|
new one if there is no such last file name. In the absence of any
|
|
‘<samp>%u<var>suffix</var></samp>’, this is just like ‘<samp>%g<var>suffix</var></samp>’, except they don’t share
|
|
the same suffix <em>space</em>, so ‘<samp>%g.s … %U.s … %g.s … %U.s</samp>’
|
|
involves the generation of two distinct file names, one
|
|
for each ‘<samp>%g.s</samp>’ and another for each ‘<samp>%U.s</samp>’. Previously, ‘<samp>%U</samp>’ was
|
|
simply substituted with a file name chosen for the previous ‘<samp>%u</samp>’,
|
|
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 ‘<samp>%u</samp>’. 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 ‘<samp>%g</samp>’, except if <samp>-pipe</samp> is in effect. In that case
|
|
‘<samp>%|</samp>’ substitutes a single dash and ‘<samp>%m</samp>’ 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</code>}</samp>’
|
|
construct: see for example <samp>f/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’s args
|
|
when it is subsequently output with ‘<samp>%*</samp>’. <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 ‘<samp>%w</samp>’ as the
|
|
designated output file of this compilation. This puts the argument
|
|
into the sequence of arguments that ‘<samp>%o</samp>’ 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 ‘<samp>%o</samp>’ as well or the results are undefined.
|
|
‘<samp>%o</samp>’ 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 ‘<samp>%g, %u, or %U</samp>’,
|
|
because of the need for those to form complete file names. The
|
|
handling is such that ‘<samp>%O</samp>’ is treated exactly as if it had already
|
|
been substituted, except that ‘<samp>%g, %u, and %U</samp>’ do not currently
|
|
support additional <var>suffix</var> characters following ‘<samp>%O</samp>’ as they do
|
|
following, for example, ‘<samp>.o</samp>’.
|
|
</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 ‘<samp>%p</samp>’, but puts ‘<samp>__</samp>’ before and after the name of each
|
|
predefined macro, except for macros that start with ‘<samp>__</samp>’ or with
|
|
‘<samp>_<var>L</var></samp>’, 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 ‘<samp>%X</samp>’.
|
|
</p>
|
|
</dd>
|
|
<dt><code>%X</code></dt>
|
|
<dd><p>Output the accumulated linker options specified by <samp>-Wl</samp> or a ‘<samp>%x</samp>’
|
|
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
|
|
‘<samp>%L %G %S %D and %E</samp>’ 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>%<<code>S</code></code></dt>
|
|
<dd><p>Remove all occurrences of <code>-S</code> from the command line. Note—this
|
|
command is position dependent. ‘<samp>%</samp>’ commands in the spec string
|
|
before this one see <code>-S</code>, ‘<samp>%</samp>’ 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 "-Wa,OPTION" to pass "OPTION" 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>%{<code>S</code>}</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 ‘<samp>%{foo}</samp>’ matches the command-line option <samp>-foo</samp>
|
|
and outputs the command-line option <samp>-foo</samp>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>%W{<code>S</code>}</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>%{<code>S</code>*}</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 ‘<samp>o</samp>’. %{o*} substitutes this
|
|
text, including the space. Thus two arguments are generated.
|
|
</p>
|
|
</dd>
|
|
<dt><code>%{<code>S</code>*&<code>T</code>*}</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 ‘<samp>%{D*&U*&A*}</samp>’.
|
|
</p>
|
|
</dd>
|
|
<dt><code>%{<code>S</code>:<code>X</code>}</code></dt>
|
|
<dd><p>Substitutes <code>X</code>, if the <samp>-S</samp> switch is given to GCC.
|
|
</p>
|
|
</dd>
|
|
<dt><code>%{!<code>S</code>:<code>X</code>}</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>%{<code>S</code>*:<code>X</code>}</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>%{.<code>S</code>:<code>X</code>}</code></dt>
|
|
<dd><p>Substitutes <code>X</code>, if processing a file with suffix <code>S</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>%{!.<code>S</code>:<code>X</code>}</code></dt>
|
|
<dd><p>Substitutes <code>X</code>, if <em>not</em> processing a file with suffix <code>S</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>%{,<code>S</code>:<code>X</code>}</code></dt>
|
|
<dd><p>Substitutes <code>X</code>, if processing a file for language <code>S</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>%{!,<code>S</code>:<code>X</code>}</code></dt>
|
|
<dd><p>Substitutes <code>X</code>, if not processing a file for language <code>S</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>%{<code>S</code>|<code>P</code>:<code>X</code>}</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 ‘<samp>!</samp>’, ‘<samp>.</samp>’, ‘<samp>,</samp>’, and
|
|
<code>*</code> sequences as well, although they have a stronger binding than
|
|
the ‘<samp>|</samp>’. 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 conditional text <code>X</code> in a %{<code>S</code>:<code>X</code>} or similar
|
|
construct may contain other nested ‘<samp>%</samp>’ 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 ‘<samp>|</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 <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’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> [<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>
|