path: root/devdocs/gcc~13/spec-files.html

<div class="section-level-extent" id="Spec-Files"> <div class="nav-panel"> <p> Next: <a href="environment-variables" accesskey="n" rel="next">Environment Variables Affecting GCC</a>, Previous: <a href="submodel-options" accesskey="p" rel="prev">Machine-Dependent Options</a>, Up: <a href="invoking-gcc" accesskey="u" rel="up">GCC Command Options</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div>  <h1 class="section" id="Specifying-Subprocesses-and-the-Switches-to-Pass-to-Them"><span>3.20 Specifying Subprocesses and the Switches to Pass to Them<a class="copiable-link" href="#Specifying-Subprocesses-and-the-Switches-to-Pass-to-Them"> ¶</a></span></h1>  <p><code class="command">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 class="dfn">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 class="option">-specs=</samp> command-line switch to specify a spec file. </p> <p><em class="dfn">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 class="table"> <dt><code class="code">%<var class="var">command</var></code></dt> <dd>
<p>Issues a <var class="var">command</var> to the spec file processor. The commands that can appear here are: </p> <dl class="table"> <dt>
<span><code class="code">%include &lt;<var class="var">file</var>&gt;</code><a class="copiable-link" href="#index-_0025include"> ¶</a></span>
</dt> <dd>
<p>Search for <var class="var">file</var> and insert its text at the current point in the specs file. </p> </dd> <dt>
<span><code class="code">%include_noerr &lt;<var class="var">file</var>&gt;</code><a class="copiable-link" href="#index-_0025include_005fnoerr"> ¶</a></span>
</dt> <dd>
<p>Just like ‘<samp class="samp">%include</samp>’, but do not generate an error message if the include file cannot be found. </p> </dd> <dt>
<span><code class="code">%rename <var class="var">old_name</var> <var class="var">new_name</var></code><a class="copiable-link" href="#index-_0025rename"> ¶</a></span>
</dt> <dd>
<p>Rename the spec string <var class="var">old_name</var> to <var class="var">new_name</var>. </p> </dd> </dl> </dd> <dt><code class="code">*[<var class="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 class="samp">+</samp>’ character, in which case the text is appended to the spec. </p> </dd> <dt><code class="code">[<var class="var">suffix</var>]:</code></dt> <dd>
<p>Creates a new ‘<samp class="samp">[<var class="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="example smallexample"> <pre class="example-preformatted" data-language="cpp">.ZZ:
z-compile -input %i</pre>
</div> <p>This says that any input file whose name ends in ‘<samp class="samp">.ZZ</samp>’ should be passed to the program ‘<samp class="samp">z-compile</samp>’, which should be invoked with the command-line switch <samp class="option">-input</samp> and with the result of performing the ‘<samp class="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 class="table"> <dt><code class="code">@<var class="var">language</var></code></dt> <dd>
<p>This says that the suffix is an alias for a known <var class="var">language</var>. This is similar to using the <samp class="option">-x</samp> command-line switch to GCC to specify a language explicitly. For example: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">.ZZ:
@c++</pre>
</div> <p>Says that .ZZ files are, in fact, C++ source files. </p> </dd> <dt><code class="code">#<var class="var">name</var></code></dt> <dd>
<p>This causes an error messages saying: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp"><var class="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="example smallexample"> <pre class="example-preformatted" data-language="cpp">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 class="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="example smallexample"> <pre class="example-preformatted" data-language="cpp">%rename lib                 old_lib

*lib:
--start-group -lgcc -lc -leval1 --end-group %(old_lib)</pre>
</div> <p>This example renames the spec called ‘<samp class="samp">lib</samp>’ to ‘<samp class="samp">old_lib</samp>’ and then overrides the previous definition of ‘<samp class="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 class="dfn">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 class="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 class="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 class="table"> <dt><code class="code">%%</code></dt> <dd>
<p>Substitute one ‘<samp class="samp">%</samp>’ into the program name or argument. </p> </dd> <dt><code class="code">%"</code></dt> <dd>
<p>Substitute an empty argument. </p> </dd> <dt><code class="code">%i</code></dt> <dd>
<p>Substitute the name of the input file being processed. </p> </dd> <dt><code class="code">%b</code></dt> <dd>
<p>Substitute the basename for outputs related with the input file being processed. This is often the substring up to (and not including) the last period and not including the directory but, unless %w is active, it expands to the basename for auxiliary outputs, which may be influenced by an explicit output name, and by various other options that control how auxiliary outputs are named. </p> </dd> <dt><code class="code">%B</code></dt> <dd>
<p>This is the same as ‘<samp class="samp">%b</samp>’, but include the file suffix (text after the last period). Without %w, it expands to the basename for dump outputs. </p> </dd> <dt><code class="code">%d</code></dt> <dd>
<p>Marks the argument containing or following the ‘<samp class="samp">%d</samp>’ as a temporary file name, so that that file is deleted if GCC exits successfully. Unlike ‘<samp class="samp">%g</samp>’, this contributes no text to the argument. </p> </dd> <dt><code class="code">%g<var class="var">suffix</var></code></dt> <dd>
<p>Substitute a file name that has suffix <var class="var">suffix</var> and is chosen once per compilation, and mark the argument in the same way as ‘<samp class="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 class="samp">%g.s … %g.o … %g.s</samp>’ might turn into ‘<samp class="samp">ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s</samp>’. <var class="var">suffix</var> matches the regexp ‘<samp class="samp">[.A-Za-z]*</samp>’ or the special string ‘<samp class="samp">%O</samp>’, which is treated exactly as if ‘<samp class="samp">%O</samp>’ had been preprocessed. Previously, ‘<samp class="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 class="code">%u<var class="var">suffix</var></code></dt> <dd>
<p>Like ‘<samp class="samp">%g</samp>’, but generates a new temporary file name each time it appears instead of once per compilation. </p> </dd> <dt><code class="code">%U<var class="var">suffix</var></code></dt> <dd>
<p>Substitutes the last file name generated with ‘<samp class="samp">%u<var class="var">suffix</var></samp>’, generating a new one if there is no such last file name. In the absence of any ‘<samp class="samp">%u<var class="var">suffix</var></samp>’, this is just like ‘<samp class="samp">%g<var class="var">suffix</var></samp>’, except they don’t share the same suffix <em class="emph">space</em>, so ‘<samp class="samp">%g.s … %U.s … %g.s … %U.s</samp>’ involves the generation of two distinct file names, one for each ‘<samp class="samp">%g.s</samp>’ and another for each ‘<samp class="samp">%U.s</samp>’. Previously, ‘<samp class="samp">%U</samp>’ was simply substituted with a file name chosen for the previous ‘<samp class="samp">%u</samp>’, without regard to any appended suffix. </p> </dd> <dt><code class="code">%j<var class="var">suffix</var></code></dt> <dd>
<p>Substitutes the name of the <code class="code">HOST_BIT_BUCKET</code>, if any, and if it is writable, and if <samp class="option">-save-temps</samp> is not used; otherwise, substitute the name of a temporary file, just like ‘<samp class="samp">%u</samp>’. This temporary file is not meant for communication between processes, but rather as a junk disposal mechanism. </p> </dd> <dt><code class="code">%|<var class="var">suffix</var></code></dt> <dt><code class="code">%m<var class="var">suffix</var></code></dt> <dd>
<p>Like ‘<samp class="samp">%g</samp>’, except if <samp class="option">-pipe</samp> is in effect. In that case ‘<samp class="samp">%|</samp>’ substitutes a single dash and ‘<samp class="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 class="samp">%{pipe:<code class="code">X</code>}</samp>’ construct: see for example <samp class="file">gcc/fortran/lang-specs.h</samp>. </p> </dd> <dt><code class="code">%.<var class="var">SUFFIX</var></code></dt> <dd>
<p>Substitutes <var class="var">.SUFFIX</var> for the suffixes of a matched switch’s args when it is subsequently output with ‘<samp class="samp">%*</samp>’. <var class="var">SUFFIX</var> is terminated by the next space or %. </p> </dd> <dt><code class="code">%w</code></dt> <dd>
<p>Marks the argument containing or following the ‘<samp class="samp">%w</samp>’ as the designated output file of this compilation. This puts the argument into the sequence of arguments that ‘<samp class="samp">%o</samp>’ substitutes. </p> </dd> <dt><code class="code">%V</code></dt> <dd>
<p>Indicates that this compilation produces no output file. </p> </dd> <dt><code class="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 class="samp">%o</samp>’ as well or the results are undefined. ‘<samp class="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 class="code">%O</code></dt> <dd>
<p>Substitutes the suffix for object files. Note that this is handled specially when it immediately follows ‘<samp class="samp">%g, %u, or %U</samp>’, because of the need for those to form complete file names. The handling is such that ‘<samp class="samp">%O</samp>’ is treated exactly as if it had already been substituted, except that ‘<samp class="samp">%g, %u, and %U</samp>’ do not currently support additional <var class="var">suffix</var> characters following ‘<samp class="samp">%O</samp>’ as they do following, for example, ‘<samp class="samp">.o</samp>’. </p> </dd> <dt><code class="code">%I</code></dt> <dd>
<p>Substitute any of <samp class="option">-iprefix</samp> (made from <code class="env">GCC_EXEC_PREFIX</code>), <samp class="option">-isysroot</samp> (made from <code class="env">TARGET_SYSTEM_ROOT</code>), <samp class="option">-isystem</samp> (made from <code class="env">COMPILER_PATH</code> and <samp class="option">-B</samp> options) and <samp class="option">-imultilib</samp> as necessary. </p> </dd> <dt><code class="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 class="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 class="option">--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 class="code">%e<var class="var">str</var></code></dt> <dd>
<p>Print <var class="var">str</var> as an error message. <var class="var">str</var> is terminated by a newline. Use this when inconsistent options are detected. </p> </dd> <dt><code class="code">%n<var class="var">str</var></code></dt> <dd>
<p>Print <var class="var">str</var> as a notice. <var class="var">str</var> is terminated by a newline. </p> </dd> <dt><code class="code">%(<var class="var">name</var>)</code></dt> <dd>
<p>Substitute the contents of spec string <var class="var">name</var> at this point. </p> </dd> <dt><code class="code">%x{<var class="var">option</var>}</code></dt> <dd>
<p>Accumulate an option for ‘<samp class="samp">%X</samp>’. </p> </dd> <dt><code class="code">%X</code></dt> <dd>
<p>Output the accumulated linker options specified by a ‘<samp class="samp">%x</samp>’ spec string. </p> </dd> <dt><code class="code">%Y</code></dt> <dd>
<p>Output the accumulated assembler options specified by <samp class="option">-Wa</samp>. </p> </dd> <dt><code class="code">%Z</code></dt> <dd>
<p>Output the accumulated preprocessor options specified by <samp class="option">-Wp</samp>. </p> </dd> <dt><code class="code">%M</code></dt> <dd>
<p>Output <code class="code">multilib_os_dir</code>. </p> </dd> <dt><code class="code">%R</code></dt> <dd>
<p>Output the concatenation of <code class="code">target_system_root</code> and <code class="code">target_sysroot_suffix</code>. </p> </dd> <dt><code class="code">%a</code></dt> <dd>
<p>Process the <code class="code">asm</code> spec. This is used to compute the switches to be passed to the assembler. </p> </dd> <dt><code class="code">%A</code></dt> <dd>
<p>Process the <code class="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 class="code">%l</code></dt> <dd>
<p>Process the <code class="code">link</code> spec. This is the spec for computing the command line passed to the linker. Typically it makes use of the ‘<samp class="samp">%L %G %S %D and %E</samp>’ sequences. </p> </dd> <dt><code class="code">%D</code></dt> <dd>
<p>Dump out a <samp class="option">-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 class="code">%L</code></dt> <dd>
<p>Process the <code class="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 class="code">%G</code></dt> <dd>
<p>Process the <code class="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 class="code">%S</code></dt> <dd>
<p>Process the <code class="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 class="file">crt0.o</samp>. </p> </dd> <dt><code class="code">%E</code></dt> <dd>
<p>Process the <code class="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 class="code">%C</code></dt> <dd>
<p>Process the <code class="code">cpp</code> spec. This is used to construct the arguments to be passed to the C preprocessor. </p> </dd> <dt><code class="code">%1</code></dt> <dd>
<p>Process the <code class="code">cc1</code> spec. This is used to construct the options to be passed to the actual C compiler (<code class="command">cc1</code>). </p> </dd> <dt><code class="code">%2</code></dt> <dd>
<p>Process the <code class="code">cc1plus</code> spec. This is used to construct the options to be passed to the actual C++ compiler (<code class="command">cc1plus</code>). </p> </dd> <dt><code class="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 class="code">%&lt;S</code></dt> <dd>
<p>Remove all occurrences of <code class="code">-S</code> from the command line. Note—this command is position dependent. ‘<samp class="samp">%</samp>’ commands in the spec string before this one see <code class="code">-S</code>, ‘<samp class="samp">%</samp>’ commands in the spec string after this one do not. </p> </dd> <dt><code class="code">%&lt;S*</code></dt> <dd>
<p>Similar to ‘<samp class="samp">%&lt;S</samp>’, but match all switches beginning with <code class="code">-S</code>. </p> </dd> <dt><code class="code">%&gt;S</code></dt> <dd>
<p>Similar to ‘<samp class="samp">%&lt;S</samp>’, but keep <code class="code">-S</code> in the GCC command line. </p> </dd> <dt><code class="code">%:<var class="var">function</var>(<var class="var">args</var>)</code></dt> <dd>
<p>Call the named function <var class="var">function</var>, passing it <var class="var">args</var>. <var class="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 class="table"> <dt><code class="code"><code class="code">getenv</code></code></dt> <dd>
<p>The <code class="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 class="env">TOPDIR</code> is defined as <samp class="file">/path/to/top</samp>, then: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">%:getenv(TOPDIR /include)</pre>
</div> <p>expands to <samp class="file">/path/to/top/include</samp>. </p> </dd> <dt><code class="code"><code class="code">if-exists</code></code></dt> <dd>
<p>The <code class="code">if-exists</code> spec function takes one argument, an absolute pathname to a file. If the file exists, <code class="code">if-exists</code> returns the pathname. Here is a small example of its usage: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">*startfile:
crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s</pre>
</div> </dd> <dt><code class="code"><code class="code">if-exists-else</code></code></dt> <dd>
<p>The <code class="code">if-exists-else</code> spec function is similar to the <code class="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 class="code">if-exists-else</code> returns the pathname. If it does not exist, it returns the second argument. This way, <code class="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="example smallexample"> <pre class="example-preformatted" data-language="cpp">*startfile:
crt0%O%s %:if-exists(crti%O%s) \
%:if-exists-else(crtbeginT%O%s crtbegin%O%s)</pre>
</div> </dd> <dt><code class="code"><code class="code">if-exists-then-else</code></code></dt> <dd>
<p>The <code class="code">if-exists-then-else</code> spec function takes at least two arguments and an optional third one. The first argument is an absolute pathname to a file. If the file exists, the function returns the second argument. If the file does not exist, the function returns the third argument if there is one, or NULL otherwise. This can be used to expand one text, or optionally another, based on the existence of a file. Here is a small example of its usage: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">-l%:if-exists-then-else(%:getenv(VSB_DIR rtnet.h) rtnet net)</pre>
</div> </dd> <dt><code class="code"><code class="code">sanitize</code></code></dt> <dd>
<p>The <code class="code">sanitize</code> spec function takes no arguments. It returns non-NULL if any address, thread or undefined behavior sanitizers are active. </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">%{%:sanitize(address):-funwind-tables}</pre>
</div> </dd> <dt><code class="code"><code class="code">replace-outfile</code></code></dt> <dd>
<p>The <code class="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="example smallexample"> <pre class="example-preformatted" data-language="cpp">%{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)}</pre>
</div> </dd> <dt><code class="code"><code class="code">remove-outfile</code></code></dt> <dd>
<p>The <code class="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="example smallexample"> <pre class="example-preformatted" data-language="cpp">%:remove-outfile(-lm)</pre>
</div> </dd> <dt><code class="code"><code class="code">version-compare</code></code></dt> <dd>
<p>The <code class="code">version-compare</code> spec function takes four or five arguments of the following form: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">&lt;comparison-op&gt; &lt;arg1&gt; [&lt;arg2&gt;] &lt;switch&gt; &lt;result&gt;</pre>
</div> <p>It returns <code class="code">result</code> if the comparison evaluates to true, and NULL if it doesn’t. The supported <code class="code">comparison-op</code> values are: </p> <dl class="table"> <dt><code class="code">&gt;=</code></dt> <dd>
<p>True if <code class="code">switch</code> is a later (or same) version than <code class="code">arg1</code> </p> </dd> <dt><code class="code">!&gt;</code></dt> <dd>
<p>Opposite of <code class="code">&gt;=</code> </p> </dd> <dt><code class="code">&lt;</code></dt> <dd>
<p>True if <code class="code">switch</code> is an earlier version than <code class="code">arg1</code> </p> </dd> <dt><code class="code">!&lt;</code></dt> <dd>
<p>Opposite of <code class="code">&lt;</code> </p> </dd> <dt><code class="code">&gt;&lt;</code></dt> <dd>
<p>True if <code class="code">switch</code> is <code class="code">arg1</code> or later, and earlier than <code class="code">arg2</code> </p> </dd> <dt><code class="code">&lt;&gt;</code></dt> <dd><p>True if <code class="code">switch</code> is earlier than <code class="code">arg1</code>, or is <code class="code">arg2</code> or later </p></dd> </dl> <p>If the <code class="code">switch</code> is not present at all, the condition is false unless the first character of the <code class="code">comparison-op</code> is <code class="code">!</code>. </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">%:version-compare(&gt;= 10.3 mmacosx-version-min= -lmx)</pre>
</div> <p>The above example would add <samp class="option">-lmx</samp> if <samp class="option">-mmacosx-version-min=10.3.9</samp> was passed. </p> </dd> <dt><code class="code"><code class="code">include</code></code></dt> <dd>
<p>The <code class="code">include</code> spec function behaves much like <code class="code">%include</code>, with the advantage that it can be nested inside a spec and thus be conditionalized. It takes one argument, the filename, and looks for it in the startfile path. It always returns NULL. </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">%{static-libasan|static:%:include(libsanitizer.spec)%(link_libasan)}</pre>
</div> </dd> <dt><code class="code"><code class="code">pass-through-libs</code></code></dt> <dd>
<p>The <code class="code">pass-through-libs</code> spec function takes any number of arguments. It finds any <samp class="option">-l</samp> options and any non-options ending in <samp class="file">.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 class="option">-plugin-opt=-pass-through=</samp> and joined by spaces. This list is intended to be passed to the LTO linker plugin. </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">%:pass-through-libs(%G %L %G)</pre>
</div> </dd> <dt><code class="code"><code class="code">print-asm-header</code></code></dt> <dd>
<p>The <code class="code">print-asm-header</code> function takes no arguments and simply prints a banner like: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">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 class="option">--target-help</samp> output. </p> </dd> <dt><code class="code"><code class="code">gt</code></code></dt> <dd>
<p>The <code class="code">gt</code> spec function takes two or more arguments. It returns <code class="code">""</code> (the empty string) if the second-to-last argument is greater than the last argument, and NULL otherwise. The following example inserts the <code class="code">link_gomp</code> spec if the last <samp class="option">-ftree-parallelize-loops=</samp> option given on the command line is greater than 1: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">%{%:gt(%{ftree-parallelize-loops=*:%*} 1):%:include(libgomp.spec)%(link_gomp)}</pre>
</div> </dd> <dt><code class="code"><code class="code">debug-level-gt</code></code></dt> <dd>
<p>The <code class="code">debug-level-gt</code> spec function takes one argument and returns <code class="code">""</code> (the empty string) if <code class="code">debug_info_level</code> is greater than the specified number, and NULL otherwise. </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">%{%:debug-level-gt(0):%{gdwarf*:--gdwarf2}}</pre>
</div> </dd> </dl> </dd> <dt><code class="code">%{S}</code></dt> <dd>
<p>Substitutes the <code class="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 class="samp">%{foo}</samp>’ matches the command-line option <samp class="option">-foo</samp> and outputs the command-line option <samp class="option">-foo</samp>. </p> </dd> <dt><code class="code">%W{S}</code></dt> <dd>
<p>Like %{<code class="code">S</code>} but mark last argument supplied within as a file to be deleted on failure. </p> </dd> <dt><code class="code">%@{S}</code></dt> <dd>
<p>Like %{<code class="code">S</code>} but puts the result into a <code class="code">FILE</code> and substitutes <code class="code">@FILE</code> if an <code class="code">@file</code> argument has been supplied. </p> </dd> <dt><code class="code">%{S*}</code></dt> <dd>
<p>Substitutes all the switches specified to GCC whose names start with <code class="code">-S</code>, but which also take an argument. This is used for switches like <samp class="option">-o</samp>, <samp class="option">-D</samp>, <samp class="option">-I</samp>, etc. GCC considers <samp class="option">-o foo</samp> as being one switch whose name starts with ‘<samp class="samp">o</samp>’. %{o*} substitutes this text, including the space. Thus two arguments are generated. </p> </dd> <dt><code class="code">%{S*&amp;T*}</code></dt> <dd>
<p>Like %{<code class="code">S</code>*}, but preserve order of <code class="code">S</code> and <code class="code">T</code> options (the order of <code class="code">S</code> and <code class="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 class="samp">%{D*&amp;U*&amp;A*}</samp>’. </p> </dd> <dt><code class="code">%{S:X}</code></dt> <dd>
<p>Substitutes <code class="code">X</code>, if the <samp class="option">-S</samp> switch is given to GCC. </p> </dd> <dt><code class="code">%{!S:X}</code></dt> <dd>
<p>Substitutes <code class="code">X</code>, if the <samp class="option">-S</samp> switch is <em class="emph">not</em> given to GCC. </p> </dd> <dt><code class="code">%{S*:X}</code></dt> <dd>
<p>Substitutes <code class="code">X</code> if one or more switches whose names start with <code class="code">-S</code> are specified to GCC. Normally <code class="code">X</code> is substituted only once, no matter how many such switches appeared. However, if <code class="code">%*</code> appears somewhere in <code class="code">X</code>, then <code class="code">X</code> is substituted once for each matching switch, with the <code class="code">%*</code> replaced by the part of that switch matching the <code class="code">*</code>. </p> <p>If <code class="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 class="code">%*</code> substitution to be used as part of a larger string. For example, a spec string like this: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">%{mcu=*:--script=%*/memory.ld}</pre>
</div> <p>when matching an option like <samp class="option">-mcu=newchip</samp> produces: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">--script=newchip/memory.ld</pre>
</div> </dd> <dt><code class="code">%{.S:X}</code></dt> <dd>
<p>Substitutes <code class="code">X</code>, if processing a file with suffix <code class="code">S</code>. </p> </dd> <dt><code class="code">%{!.S:X}</code></dt> <dd>
<p>Substitutes <code class="code">X</code>, if <em class="emph">not</em> processing a file with suffix <code class="code">S</code>. </p> </dd> <dt><code class="code">%{,S:X}</code></dt> <dd>
<p>Substitutes <code class="code">X</code>, if processing a file for language <code class="code">S</code>. </p> </dd> <dt><code class="code">%{!,S:X}</code></dt> <dd>
<p>Substitutes <code class="code">X</code>, if not processing a file for language <code class="code">S</code>. </p> </dd> <dt><code class="code">%{S|P:X}</code></dt> <dd>
<p>Substitutes <code class="code">X</code> if either <code class="code">-S</code> or <code class="code">-P</code> is given to GCC. This may be combined with ‘<samp class="samp">!</samp>’, ‘<samp class="samp">.</samp>’, ‘<samp class="samp">,</samp>’, and <code class="code">*</code> sequences as well, although they have a stronger binding than the ‘<samp class="samp">|</samp>’. If <code class="code">%*</code> appears in <code class="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="example smallexample"> <pre class="example-preformatted" data-language="cpp">%{.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="example smallexample"> <pre class="example-preformatted" data-language="cpp">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 class="code">%{%:<var class="var">function</var>(<var class="var">args</var>):X}</code></dt> <dd> <p>Call function named <var class="var">function</var> with args <var class="var">args</var>. If the function returns non-NULL, then <code class="code">X</code> is substituted, if it returns NULL, it isn’t substituted. </p> </dd> <dt><code class="code">%{S:X; T:Y; :D}</code></dt> <dd> <p>If <code class="code">S</code> is given to GCC, substitutes <code class="code">X</code>; else if <code class="code">T</code> is given to GCC, substitutes <code class="code">Y</code>; else substitutes <code class="code">D</code>. There can be as many clauses as you need. This may be combined with <code class="code">.</code>, <code class="code">,</code>, <code class="code">!</code>, <code class="code">|</code>, and <code class="code">*</code> as needed. </p> </dd> </dl> <p>The switch matching text <code class="code">S</code> in a ‘<samp class="samp">%{S}</samp>’, ‘<samp class="samp">%{S:X}</samp>’ 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, ‘<samp class="samp">%{std=iso9899\:1999:X}</samp>’ substitutes <code class="code">X</code> if the <samp class="option">-std=iso9899:1999</samp> option is given. </p> <p>The conditional text <code class="code">X</code> in a ‘<samp class="samp">%{S:X}</samp>’ or similar construct may contain other nested ‘<samp class="samp">%</samp>’ constructs or spaces, or even newlines. They are processed as usual, as described above. Trailing white space in <code class="code">X</code> is ignored. White space may also appear anywhere on the left side of the colon in these constructs, except between <code class="code">.</code> or <code class="code">*</code> and the corresponding word. </p> <p>The <samp class="option">-O</samp>, <samp class="option">-f</samp>, <samp class="option">-m</samp>, and <samp class="option">-W</samp> switches are handled specifically in these constructs. If another value of <samp class="option">-O</samp> or the negated form of a <samp class="option">-f</samp>, <samp class="option">-m</samp>, or <samp class="option">-W</samp> switch is found later in the command line, the earlier switch value is ignored, except with {<code class="code">S</code>*} where <code class="code">S</code> is just one letter, which passes all matching options. </p> <p>The character ‘<samp class="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 class="option">-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 class="option">-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> </div>  <div class="nav-panel"> <p> Next: <a href="environment-variables">Environment Variables Affecting GCC</a>, Previous: <a href="submodel-options">Machine-Dependent Options</a>, Up: <a href="invoking-gcc">GCC Command Options</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div><div class="_attribution">
  <p class="_attribution-p">
    &copy; Free Software Foundation<br>Licensed under the GNU Free Documentation License, Version 1.3.<br>
    <a href="https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/Spec-Files.html" class="_attribution-link">https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/Spec-Files.html</a>
  </p>
</div>