diff options
Diffstat (limited to 'share/doc/gcc/Spec-Files.html')
| -rw-r--r-- | share/doc/gcc/Spec-Files.html | 870 |
1 files changed, 870 insertions, 0 deletions
diff --git a/share/doc/gcc/Spec-Files.html b/share/doc/gcc/Spec-Files.html new file mode 100644 index 0000000..80d22a1 --- /dev/null +++ b/share/doc/gcc/Spec-Files.html @@ -0,0 +1,870 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- This file documents the use of the GNU compilers. + +Copyright (C) 1988-2023 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.1, 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="Indices.html#Indices" rel="index" title="Indices"> +<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="previous" 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_US" 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="previous">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="Indices.html#Indices" 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"> +<dd><a name="index-_0025include"></a> +</dd> +<dt><code>%include <<var>file</var>></code></dt> +<dd><p>Search for <var>file</var> and insert its text at the current point in the +specs file. +</p> +<a name="index-_0025include_005fnoerr"></a> +</dd> +<dt><code>%include_noerr <<var>file</var>></code></dt> +<dd><p>Just like ‘<samp>%include</samp>’, but do not generate an error message if the include +file cannot be found. +</p> +<a name="index-_0025rename"></a> +</dd> +<dt><code>%rename <var>old_name</var> <var>new_name</var></code></dt> +<dd><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>%"</code></dt> +<dd><p>Substitute an empty 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 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>%B</code></dt> +<dd><p>This is the same as ‘<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>%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>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’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>%V</code></dt> +<dd><p>Indicates that this compilation produces no output file. +</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>%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>%n<var>str</var></code></dt> +<dd><p>Print <var>str</var> as a notice. <var>str</var> is terminated by a newline. +</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 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>%M</code></dt> +<dd><p>Output <code>multilib_os_dir</code>. +</p> +</dd> +<dt><code>%R</code></dt> +<dd><p>Output the concatenation of <code>target_system_root</code> and <code>target_sysroot_suffix</code>. +</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>%<S</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>%<S*</code></dt> +<dd><p>Similar to ‘<samp>%<S</samp>’, but match all switches beginning with <code>-S</code>. +</p> +</dd> +<dt><code>%>S</code></dt> +<dd><p>Similar to ‘<samp>%<S</samp>’, but keep <code>-S</code> in the GCC command line. +</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>if-exists-then-else</code></code></dt> +<dd><p>The <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="smallexample"> +<pre class="smallexample">-l%:if-exists-then-else(%:getenv(VSB_DIR rtnet.h) rtnet net) +</pre></div> + +</dd> +<dt><code><code>sanitize</code></code></dt> +<dd><p>The <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="smallexample"> +<pre class="smallexample">%{%:sanitize(address):-funwind-tables} +</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>version-compare</code></code></dt> +<dd><p>The <code>version-compare</code> spec function takes four or five arguments of the following +form: +</p> +<div class="smallexample"> +<pre class="smallexample"><comparison-op> <arg1> [<arg2>] <switch> <result> +</pre></div> + +<p>It returns <code>result</code> if the comparison evaluates to true, and NULL if it doesn’t. +The supported <code>comparison-op</code> values are: +</p> +<dl compact="compact"> +<dt><code>>=</code></dt> +<dd><p>True if <code>switch</code> is a later (or same) version than <code>arg1</code> +</p> +</dd> +<dt><code>!></code></dt> +<dd><p>Opposite of <code>>=</code> +</p> +</dd> +<dt><code><</code></dt> +<dd><p>True if <code>switch</code> is an earlier version than <code>arg1</code> +</p> +</dd> +<dt><code>!<</code></dt> +<dd><p>Opposite of <code><</code> +</p> +</dd> +<dt><code>><</code></dt> +<dd><p>True if <code>switch</code> is <code>arg1</code> or later, and earlier than <code>arg2</code> +</p> +</dd> +<dt><code><></code></dt> +<dd><p>True if <code>switch</code> is earlier than <code>arg1</code>, or is <code>arg2</code> or later +</p></dd> +</dl> + +<p>If the <code>switch</code> is not present at all, the condition is false unless the first character +of the <code>comparison-op</code> is <code>!</code>. +</p> +<div class="smallexample"> +<pre class="smallexample">%:version-compare(>= 10.3 mmacosx-version-min= -lmx) +</pre></div> + +<p>The above example would add <samp>-lmx</samp> if <samp>-mmacosx-version-min=10.3.9</samp> was +passed. +</p> +</dd> +<dt><code><code>include</code></code></dt> +<dd><p>The <code>include</code> spec function behaves much like <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="smallexample"> +<pre class="smallexample">%{static-libasan|static:%:include(libsanitizer.spec)%(link_libasan)} +</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> +<dt><code><code>gt</code></code></dt> +<dd><p>The <code>gt</code> spec function takes two or more arguments. It returns <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>link_gomp</code> spec if the last +<samp>-ftree-parallelize-loops=</samp> option given on the command line is greater than 1: +</p> +<div class="smallexample"> +<pre class="smallexample">%{%:gt(%{ftree-parallelize-loops=*:%*} 1):%:include(libgomp.spec)%(link_gomp)} +</pre></div> + +</dd> +<dt><code><code>debug-level-gt</code></code></dt> +<dd><p>The <code>debug-level-gt</code> spec function takes one argument and returns <code>""</code> (the +empty string) if <code>debug_info_level</code> is greater than the specified number, and NULL +otherwise. +</p> +<div class="smallexample"> +<pre class="smallexample">%{%:debug-level-gt(0):%{gdwarf*:--gdwarf2}} +</pre></div> +</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 ‘<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{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>Like %{<code>S</code>} but puts the result into a <code>FILE</code> and substitutes +<code>@FILE</code> if an <code>@file</code> argument has been supplied. +</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 ‘<samp>o</samp>’. %{o*} substitutes this +text, including the space. Thus two arguments are generated. +</p> +</dd> +<dt><code>%{S*&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 ‘<samp>%{D*&U*&A*}</samp>’. +</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 ‘<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>%{%:<var>function</var>(<var>args</var>):X}</code></dt> +<dd> +<p>Call function named <var>function</var> with args <var>args</var>. If the +function returns non-NULL, then <code>X</code> is substituted, if it returns +NULL, it isn’t substituted. +</p> +</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 ‘<samp>%{S}</samp>’, ‘<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>%{std=iso9899\:1999:X}</samp>’ substitutes <code>X</code> if the +<samp>-std=iso9899:1999</samp> option is given. +</p> +<p>The conditional text <code>X</code> in a ‘<samp>%{S:X}</samp>’ 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="previous">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="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |