https://gcc.gnu.org/g:c600bb7aefca1ac43e57ac8dde957183a8fca7a9
commit r16-7947-gc600bb7aefca1ac43e57ac8dde957183a8fca7a9 Author: Sandra Loosemore <[email protected]> Date: Tue Mar 3 03:52:03 2026 +0000 doc: Move specs documentation to GCC internals manual [PR69367] [PR69849] The description of specs should have ended up in the GCC internals manual instead of the user-facing documentation when the two manuals were split many years ago. gcc/ChangeLog PR driver/69367 PR driver/69849 * Makefile.in (TEXI_GCCINT_FILES): Add specs.texi. * doc/gccint.texi: Include it. * doc/install.texi: Fix cross-references. * doc/invoke.texi: Likewise. (Option Summary): Reclassify -specs/--specs as a developer option. (Overall Options): Move -specs= documentation to... (Developer Options): ...here. (Spec Files): Move entire section to.... * doc/specs.texi: ....new file. * common.opt.urls: Regenerated. Diff: --- gcc/Makefile.in | 2 +- gcc/common.opt.urls | 4 +- gcc/doc/gccint.texi | 2 + gcc/doc/install.texi | 7 +- gcc/doc/invoke.texi | 740 ++------------------------------------------------- gcc/doc/specs.texi | 693 +++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 727 insertions(+), 721 deletions(-) diff --git a/gcc/Makefile.in b/gcc/Makefile.in index b97cc7a0d133..807e5751642b 100644 --- a/gcc/Makefile.in +++ b/gcc/Makefile.in @@ -3809,7 +3809,7 @@ TEXI_GCCINT_FILES = gccint.texi gcc-common.texi gcc-vers.texi \ sourcebuild.texi gty.texi libgcc.texi cfg.texi tree-ssa.texi \ loop.texi generic.texi gimple.texi plugins.texi optinfo.texi \ match-and-simplify.texi analyzer.texi ux.texi poly-int.texi \ - params.texi + params.texi specs.texi TEXI_GCCINSTALL_FILES = install.texi fdl.texi \ gcc-common.texi gcc-vers.texi diff --git a/gcc/common.opt.urls b/gcc/common.opt.urls index ed4c9d55e3b3..b2d7a20da81a 100644 --- a/gcc/common.opt.urls +++ b/gcc/common.opt.urls @@ -2003,10 +2003,10 @@ shared-libgcc UrlSuffix(gcc/Link-Options.html#index-shared-libgcc) specs -UrlSuffix(gcc/Overall-Options.html#index-specs) +UrlSuffix(gcc/Developer-Options.html#index-specs) specs= -UrlSuffix(gcc/Overall-Options.html#index-specs) +UrlSuffix(gcc/Developer-Options.html#index-specs) static UrlSuffix(gcc/Link-Options.html#index-static) diff --git a/gcc/doc/gccint.texi b/gcc/doc/gccint.texi index dee6206d57b1..9d3b2f234289 100644 --- a/gcc/doc/gccint.texi +++ b/gcc/doc/gccint.texi @@ -108,6 +108,7 @@ Additional tutorial information is linked to from * Source Tree:: GCC source tree structure and build system. * Testsuites:: GCC testsuites. * Options:: Option specification files. +* Spec Files:: Specifying subprocesses and the switches to pass to them. * Passes:: Order of passes, what they do, and what each file is for. * poly_int:: Representation of runtime sizes and offsets. * GENERIC:: Language-independent representation generated by Front Ends @@ -149,6 +150,7 @@ Additional tutorial information is linked to from @include languages.texi @include sourcebuild.texi @include options.texi +@include specs.texi @include passes.texi @include poly-int.texi @include generic.texi diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi index d40f0c3a11df..2000046b9d21 100644 --- a/gcc/doc/install.texi +++ b/gcc/doc/install.texi @@ -986,13 +986,12 @@ This can be useful if you need to turn on a non-standard feature by default without modifying the compiler's source code, for instance @option{--with-specs=%@{!fcommon:%@{!fno-common:-fno-common@}@}}. @ifnothtml -@xref{Spec Files,, Specifying subprocesses and the switches to pass to them, -gcc, Using the GNU Compiler Collection (GCC)}, +@xref{Spec Files,, Specifying Subprocesses and the Switches to Pass to Them, +gccint, GNU Compiler Collection (GCC) Internals}. @end ifnothtml @ifhtml -See ``Spec Files'' in the main manual +See ``Spec Files'' in the GCC Internals manual. @end ifhtml - @end table @item --program-prefix=@var{prefix} diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 6440e7cd3696..4b8200152157 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -171,7 +171,6 @@ listing and explanation of the binary and decimal byte size prefixes. debugging dumps. * Submodel Options:: Target-specific options, such as compiling for a specific processor variant. -* Spec Files:: How to pass switches to sub-processes. * Environment Variables:: Env vars that affect GCC. * Precompiled Headers:: Compiling a header once, and using it many times. * C++ Modules:: Experimental C++20 module system. @@ -192,7 +191,7 @@ in the following sections. -dumpbase @var{dumpbase} -dumpbase-ext @var{auxdropsuf} -dumpdir @var{dumppfx} -x @var{language} -v -### --help@r{[}=@var{class}@r{[},@dots{}@r{]]} --target-help --version --pass-exit-codes -pipe -specs=@var{file} -wrapper +-pass-exit-codes -pipe -wrapper @@@var{file} -ffile-prefix-map=@var{old}=@var{new} -fcanon-prefix-map -fplugin=@var{file} -fplugin-arg-@var{name}=@var{arg} -fdump-ada-spec@r{[}-slim@r{]} -fada-spec-parent=@var{unit} @@ -200,7 +199,7 @@ in the following sections. --assemble --compile --dumpbase @var{dumpbase} --dumpbase-ext @var{auxdropsuf} --dumpdir @var{dumppfx} --language=@var{language} --output=@var{file} --pass-exit-codes ---pipe --preprocess --specs=@var{file} --verbose} +--pipe --preprocess --verbose} @item C Language Options @xref{C Dialect Options,,Options Controlling C Dialect}. @@ -870,13 +869,14 @@ Objective-C and Objective-C++ Dialects}. -print-multiarch -print-prog-name=@var{program} -print-search-dirs -Q -print-sysroot -print-sysroot-headers-suffix --save-temps -save-temps=cwd -save-temps=obj -time@r{[}=@var{file}@r{]} +-save-temps -save-temps=cwd -save-temps=obj +-specs=@var{file} -time@r{[}=@var{file}@r{]} --dump=@var{letters} --print-file-name=@var{library} --print-libgcc-file-file-name --print-multi-directory --print-multi-lib --print-multi-os-directory --print-multiarch --print-prog-name=@var{program} --print-search-dirs --print-sysroot --print-sysroot-headers-suffix ---save-temps +--save-temps --specs=@var{file} --param @var{name}=@var{value} } @@ -2329,18 +2329,6 @@ various stages of compilation. This fails to work on some systems where the assembler is unable to read from a pipe; but the GNU assembler has no trouble. -@opindex specs -@item -specs=@var{file} -@itemx --specs=@var{file} -@itemx --specs @var{file} -Process @var{file} after the compiler reads in the standard @file{specs} -file, in order to override the defaults which the @command{gcc} driver -program uses when determining what switches to pass to @command{cc1}, -@command{cc1plus}, @command{as}, @command{ld}, etc. More than one -@option{-specs=@var{file}} can be specified on the command line, and they -are processed in order, from left to right. @xref{Spec Files}, for -information about the format of the @var{file}. - @opindex wrapper @item -wrapper Invoke all subcommands under a wrapper program. The name of the @@ -20765,6 +20753,20 @@ Equivalent to @option{-save-temps -dumpdir @file{outdir/}}, where @option{-o} option is not used, the @option{-save-temps=obj} switch behaves like @option{-save-temps=cwd}. +@opindex specs +@item -specs=@var{file} +@itemx --specs=@var{file} +@itemx --specs @var{file} +Process @var{file} after the compiler reads in the standard @file{specs} +file, in order to override the defaults which the @command{gcc} driver +program uses when determining what switches to pass to @command{cc1}, +@command{cc1plus}, @command{as}, @command{ld}, etc. More than one +@option{-specs=@var{file}} can be specified on the command line, and they +are processed in order, from left to right. +@xref{Spec Files,, Specifying Subprocesses and the Switches to Pass to Them, +gccint, GNU Compiler Collection (GCC) Internals}, for +information about the format of the @var{file}. + @opindex time @item -time@r{[}=@var{file}@r{]} Report the CPU time taken by each subprocess in the compilation @@ -20935,8 +20937,10 @@ allocation before or after interprocedural optimization. @item -fmultiflags This option enables multilib-aware @code{TFLAGS} to be used to build target libraries with options different from those the compiler is -configured to use by default, through the use of specs (@pxref{Spec -Files}) set up by compiler internals, by the target, or by builders at +configured to use by default, through the use of specs +(@pxref{Spec Files,, Specifying Subprocesses and the Switches to Pass to Them, +gccint, GNU Compiler Collection (GCC) Internals}) +set up by compiler internals, by the target, or by builders at configure time. Like @code{TFLAGS}, this allows the target libraries to be built for @@ -21136,7 +21140,9 @@ always three numbers separated by dots, major, minor and patchlevel version. @opindex dumpspecs @item -dumpspecs Print the compiler's built-in specs---and don't do anything else. (This -is used when GCC itself is being built.) @xref{Spec Files}. +is used when GCC itself is being built.) +@xref{Spec Files,, Specifying Subprocesses and the Switches to Pass to Them, +gccint, GNU Compiler Collection (GCC) Internals}. @opindex param @item --param @var{name}=@var{value} @@ -37354,700 +37360,6 @@ These are listed under @xref{S/390 and zSeries Options}. @c man end -@node Spec Files -@section Specifying Subprocesses and the Switches to Pass to Them -@cindex Spec Files - -@command{gcc} is a driver program. It performs its job by invoking a -sequence of other programs to do the work of compiling, assembling and -linking. GCC interprets its command-line parameters and uses these to -deduce which programs it should invoke, and which command-line options -it ought to place on their command lines. This behavior is controlled -by @dfn{spec strings}. In most cases there is one spec string for each -program that GCC can invoke, but a few programs have multiple spec -strings to control their behavior. The spec strings built into GCC can -be overridden by using the @option{-specs=} command-line switch to specify -a spec file. - -@dfn{Spec files} are 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: - -@table @code -@item %@var{command} -Issues a @var{command} to the spec file processor. The commands that can -appear here are: - -@table @code -@cindex @code{%include} -@item %include <@var{file}> -Search for @var{file} and insert its text at the current point in the -specs file. - -@cindex @code{%include_noerr} -@item %include_noerr <@var{file}> -Just like @samp{%include}, but do not generate an error message if the include -file cannot be found. - -@cindex @code{%rename} -@item %rename @var{old_name} @var{new_name} -Rename the spec string @var{old_name} to @var{new_name}. - -@end table - -@item *[@var{spec_name}]: -This tells the compiler to create, override or delete the named spec -string. All lines after this directive up to the next directive or -blank line are considered to be the text for the spec string. If this -results in an empty string then the spec is deleted. (Or, if the -spec did not exist, then nothing happens.) Otherwise, if the spec -does not currently exist a new spec is created. If the spec does -exist then its contents are overridden by the text of this -directive, unless the first character of that text is the @samp{+} -character, in which case the text is appended to the spec. - -@item [@var{suffix}]: -Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive -and up to the next directive or blank line are considered to make up the -spec string for the indicated suffix. When the compiler encounters an -input file with the named suffix, it processes the spec string in -order to work out how to compile that file. For example: - -@smallexample -.ZZ: -z-compile -input %i -@end smallexample - -This says that any input file whose name ends in @samp{.ZZ} should be -passed to the program @samp{z-compile}, which should be invoked with the -command-line switch @option{-input} and with the result of performing the -@samp{%i} substitution. (See below.) - -As an alternative to providing a spec string, the text following a -suffix directive can be one of the following: - -@table @code -@item @@@var{language} -This says that the suffix is an alias for a known @var{language}. This is -similar to using the @option{-x} command-line switch to GCC to specify a -language explicitly. For example: - -@smallexample -.ZZ: -@@c++ -@end smallexample - -Says that .ZZ files are, in fact, C++ source files. - -@item #@var{name} -This causes an error messages saying: - -@smallexample -@var{name} compiler not installed on this system. -@end smallexample -@end table - -GCC already has an extensive list of suffixes built into it. -This directive adds an entry to the end of the list of suffixes, but -since the list is searched from the end backwards, it is effectively -possible to override earlier entries using this technique. - -@end table - -GCC has the following spec strings built into it. Spec files can -override these strings or create their own. Note that individual -targets can also add their own spec strings to this list. - -@smallexample -asm Options to pass to the assembler -asm_final Options to pass to the assembler post-processor -cpp Options to pass to the C preprocessor -cc1 Options to pass to the C compiler -cc1plus Options to pass to the C++ compiler -endfile Object files to include at the end of the link -link Options to pass to the linker -lib Libraries to include on the command line to the linker -libgcc Decides which GCC support library to pass to the linker -linker Sets the name of the linker -startfile Object files to include at the start of the link -@end smallexample - -Here is a small example of a spec file: - -@smallexample -%rename lib old_lib - -*lib: ---start-group -lgcc -lc -leval1 --end-group %(old_lib) -@end smallexample - -This example renames the spec called @samp{lib} to @samp{old_lib} and -then overrides the previous definition of @samp{lib} with a new one. -The new definition adds in some extra command-line options before -including the text of the old definition. - -@dfn{Spec strings} are a list of command-line options to be passed to their -corresponding program. In addition, the spec strings can contain -@samp{%}-prefixed sequences to substitute variable text or to -conditionally insert text into the command line. Using these constructs -it is possible to generate quite complex command lines. - -Here is a table of all defined @samp{%}-sequences for spec -strings. Note that spaces are not generated automatically around the -results of expanding these sequences. Therefore you can concatenate them -together or combine them with constant text in a single argument. - -@table @code -@item %% -Substitute one @samp{%} into the program name or argument. - -@item %" -Substitute an empty argument. - -@item %i -Substitute the name of the input file being processed. - -@item %b -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. - -@item %B -This is the same as @samp{%b}, but include the file suffix (text after -the last period). Without %w, it expands to the basename for dump -outputs. - -@item %d -Marks the argument containing or following the @samp{%d} as a -temporary file name, so that that file is deleted if GCC exits -successfully. Unlike @samp{%g}, this contributes no text to the -argument. - -@item %g@var{suffix} -Substitute a file name that has suffix @var{suffix} and is chosen -once per compilation, and mark the argument in the same way as -@samp{%d}. To reduce exposure to denial-of-service attacks, the file -name is now chosen in a way that is hard to predict even when previously -chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s} -might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches -the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is -treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g} -was simply substituted with a file name chosen once per compilation, -without regard to any appended suffix (which was therefore treated -just like ordinary text), making such attacks more likely to succeed. - -@item %u@var{suffix} -Like @samp{%g}, but generates a new temporary file name -each time it appears instead of once per compilation. - -@item %U@var{suffix} -Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a -new one if there is no such last file name. In the absence of any -@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share -the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s} -involves the generation of two distinct file names, one -for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was -simply substituted with a file name chosen for the previous @samp{%u}, -without regard to any appended suffix. - -@item %j@var{suffix} -Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is -writable, and if @option{-save-temps} is not used; -otherwise, substitute the name -of a temporary file, just like @samp{%u}. This temporary file is not -meant for communication between processes, but rather as a junk -disposal mechanism. - -@item %|@var{suffix} -@itemx %m@var{suffix} -Like @samp{%g}, except if @option{-pipe} is in effect. In that case -@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at -all. These are the two most common ways to instruct a program that it -should read from standard input or write to standard output. If you -need something more elaborate you can use an @samp{%@{pipe:@code{X}@}} -construct: see for example @file{gcc/fortran/lang-specs.h}. - -@item %.@var{SUFFIX} -Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args -when it is subsequently output with @samp{%*}. @var{SUFFIX} is -terminated by the next space or %. - -@item %w -Marks the argument containing or following the @samp{%w} as the -designated output file of this compilation. This puts the argument -into the sequence of arguments that @samp{%o} substitutes. - -@item %V -Indicates that this compilation produces no output file. - -@item %o -Substitutes the names of all the output files, with spaces -automatically placed around them. You should write spaces -around the @samp{%o} as well or the results are undefined. -@samp{%o} is for use in the specs for running the linker. -Input files whose names have no recognized suffix are not compiled -at all, but they are included among the output files, so they are -linked. - -@item %O -Substitutes the suffix for object files. Note that this is -handled specially when it immediately follows @samp{%g, %u, or %U}, -because of the need for those to form complete file names. The -handling is such that @samp{%O} is treated exactly as if it had already -been substituted, except that @samp{%g, %u, and %U} do not currently -support additional @var{suffix} characters following @samp{%O} as they do -following, for example, @samp{.o}. - -@item %I -Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}), -@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}), -@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options) -and @option{-imultilib} as necessary. - -@item %s -Current argument is the name of a library or startup file of some sort. -Search for that file in a standard list of directories and substitute -the full name found. The current working directory is included in the -list of directories scanned. - -@item %T -Current argument is the name of a linker script. Search for that file -in the current list of directories to scan for libraries. If the file -is located insert a @option{--script} option into the command line -followed by the full path name found. If the file is not found then -generate an error message. Note: the current working directory is not -searched. - -@item %e@var{str} -Print @var{str} as an error message. @var{str} is terminated by a newline. -Use this when inconsistent options are detected. - -@item %n@var{str} -Print @var{str} as a notice. @var{str} is terminated by a newline. - -@item %(@var{name}) -Substitute the contents of spec string @var{name} at this point. - -@item %x@{@var{option}@} -Accumulate an option for @samp{%X}. - -@item %X -Output the accumulated linker options specified by a @samp{%x} spec string. - -@item %Y -Output the accumulated assembler options specified by @option{-Wa}. - -@item %Z -Output the accumulated preprocessor options specified by @option{-Wp}. - -@item %M -Output @code{multilib_os_dir}. - -@item %R -Output the concatenation of @code{target_system_root} and @code{target_sysroot_suffix}. - -@item %a -Process the @code{asm} spec. This is used to compute the -switches to be passed to the assembler. - -@item %A -Process the @code{asm_final} spec. This is a spec string for -passing switches to an assembler post-processor, if such a program is -needed. - -@item %l -Process the @code{link} spec. This is the spec for computing the -command line passed to the linker. Typically it makes use of the -@samp{%L %G %S %D and %E} sequences. - -@item %D -Dump out a @option{-L} option for each directory that GCC believes might -contain startup files. If the target supports multilibs then the -current multilib directory is prepended to each of these paths. - -@item %L -Process the @code{lib} spec. This is a spec string for deciding which -libraries are included on the command line to the linker. - -@item %G -Process the @code{libgcc} spec. This is a spec string for deciding -which GCC support library is included on the command line to the linker. - -@item %S -Process the @code{startfile} spec. This is a spec for deciding which -object files are the first ones passed to the linker. Typically -this might be a file named @file{crt0.o}. - -@item %E -Process the @code{endfile} spec. This is a spec string that specifies -the last object files that are passed to the linker. - -@item %C -Process the @code{cpp} spec. This is used to construct the arguments -to be passed to the C preprocessor. - -@item %1 -Process the @code{cc1} spec. This is used to construct the options to be -passed to the actual C compiler (@command{cc1}). - -@item %2 -Process the @code{cc1plus} spec. This is used to construct the options to be -passed to the actual C++ compiler (@command{cc1plus}). - -@item %* -Substitute the variable part of a matched option. See below. -Note that each comma in the substituted string is replaced by -a single space. - -@item %<@var{S} -Remove all occurrences of @code{-@var{S}} from the command line. Note---this -command is position dependent. @samp{%} commands in the spec string -before this one see @code{-@var{S}}, @samp{%} commands in the spec string -after this one do not. - -@item %<@var{S}* -Similar to @samp{%<@var{S}}, but match all switches beginning with @code{-@var{S}}. - -@item %>@var{S} -Similar to @samp{%<@var{S}}, but keep @code{-@var{S}} in the GCC command line. - -@item %:@var{function}(@var{args}) -Call the named function @var{function}, passing it @var{args}. -@var{args} is first processed as a nested spec string, then split -into an argument vector in the usual fashion. The function returns -a string which is processed as if it had appeared literally as part -of the current spec. - -The following built-in spec functions are provided: - -@table @code -@item @code{getenv} -The @code{getenv} spec function takes two arguments: an environment -variable name and a string. If the environment variable is not -defined, a fatal error is issued. Otherwise, the return value is the -value of the environment variable concatenated with the string. For -example, if @env{TOPDIR} is defined as @file{/path/to/top}, then: - -@smallexample -%:getenv(TOPDIR /include) -@end smallexample - -expands to @file{/path/to/top/include}. - -@item @code{if-exists} -The @code{if-exists} spec function takes one argument, an absolute -pathname to a file. If the file exists, @code{if-exists} returns the -pathname. Here is a small example of its usage: - -@smallexample -*startfile: -crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s -@end smallexample - -@item @code{if-exists-else} -The @code{if-exists-else} spec function is similar to the @code{if-exists} -spec function, except that it takes two arguments. The first argument is -an absolute pathname to a file. If the file exists, @code{if-exists-else} -returns the pathname. If it does not exist, it returns the second argument. -This way, @code{if-exists-else} can be used to select one file or another, -based on the existence of the first. Here is a small example of its usage: - -@smallexample -*startfile: -crt0%O%s %:if-exists(crti%O%s) \ -%:if-exists-else(crtbeginT%O%s crtbegin%O%s) -@end smallexample - -@item @code{if-exists-then-else} -The @code{if-exists-then-else} 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: - -@smallexample --l%:if-exists-then-else(%:getenv(VSB_DIR rtnet.h) rtnet net) -@end smallexample - -@item @code{sanitize} -The @code{sanitize} spec function takes no arguments. It returns non-NULL if -any address, thread or undefined behavior sanitizers are active. - -@smallexample -%@{%:sanitize(address):-funwind-tables@} -@end smallexample - -@item @code{replace-outfile} -The @code{replace-outfile} spec function takes two arguments. It looks for the -first argument in the outfiles array and replaces it with the second argument. Here -is a small example of its usage: - -@smallexample -%@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@} -@end smallexample - -@item @code{remove-outfile} -The @code{remove-outfile} spec function takes one argument. It looks for the -first argument in the outfiles array and removes it. Here is a small example -its usage: - -@smallexample -%:remove-outfile(-lm) -@end smallexample - -@item @code{version-compare} -The @code{version-compare} spec function takes four or five arguments of the following -form: - -@smallexample -<comparison-op> <arg1> [<arg2>] <switch> <result> -@end smallexample - -It returns @code{result} if the comparison evaluates to true, and NULL if it doesn't. -The supported @code{comparison-op} values are: - -@table @code -@item >= -True if @code{switch} is a later (or same) version than @code{arg1} - -@item !> -Opposite of @code{>=} - -@item < -True if @code{switch} is an earlier version than @code{arg1} - -@item !< -Opposite of @code{<} - -@item >< -True if @code{switch} is @code{arg1} or later, and earlier than @code{arg2} - -@item <> -True if @code{switch} is earlier than @code{arg1}, or is @code{arg2} or later -@end table - -If the @code{switch} is not present at all, the condition is false unless the first character -of the @code{comparison-op} is @code{!}. - -@smallexample -%:version-compare(>= 10.3 mmacosx-version-min= -lmx) -@end smallexample - -The above example would add @option{-lmx} if @option{-mmacosx-version-min=10.3.9} was -passed. - -@item @code{include} -The @code{include} spec function behaves much like @code{%include}, 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. - -@smallexample -%@{static-libasan|static:%:include(libsanitizer.spec)%(link_libasan)@} -@end smallexample - -@item @code{pass-through-libs} -The @code{pass-through-libs} spec function takes any number of arguments. It -finds any @option{-l} options and any non-options ending in @file{.a} (which it -assumes are the names of linker input library archive files) and returns a -result containing all the found arguments each prepended by -@option{-plugin-opt=-pass-through=} and joined by spaces. This list is -intended to be passed to the LTO linker plugin. - -@smallexample -%:pass-through-libs(%G %L %G) -@end smallexample - -@item @code{print-asm-header} -The @code{print-asm-header} function takes no arguments and simply -prints a banner like: - -@smallexample -Assembler options -================= - -Use "-Wa,OPTION" to pass "OPTION" to the assembler. -@end smallexample - -It is used to separate compiler options from assembler options -in the @option{--target-help} output. - -@item @code{gt} -The @code{gt} spec function takes two or more arguments. It returns @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} spec if the last -@option{-ftree-parallelize-loops=} option given on the command line is greater than 1: - -@smallexample -%@{%:gt(%@{ftree-parallelize-loops=*:%*@} 1):%:include(libgomp.spec)%(link_gomp)@} -@end smallexample - -@item @code{debug-level-gt} -The @code{debug-level-gt} spec function takes one argument and returns @code{""} (the -empty string) if @code{debug_info_level} is greater than the specified number, and NULL -otherwise. - -@smallexample -%@{%:debug-level-gt(0):%@{gdwarf*:--gdwarf2@}@} -@end smallexample -@end table - -@item %@{@var{S}@} -Substitutes the @code{-@var{S}} switch, if that switch is given to GCC@. -If that switch is not specified, this substitutes nothing. Note that -the leading dash is omitted when specifying this option, and it is -automatically inserted if the substitution is performed. Thus the spec -string @samp{%@{foo@}} matches the command-line option @option{-foo} -and outputs the command-line option @option{-foo}. - -@item %W@{@var{S}@} -Like %@{@code{@var{S}}@} but mark last argument supplied within as a file to be -deleted on failure. - -@item %@@@{@var{S}@} -Like %@{@code{@var{S}}@} but puts the result into a @code{FILE} and substitutes -@code{@@FILE} if an @code{@@file} argument has been supplied. - -@item %@{@var{S}*@} -Substitutes all the switches specified to GCC whose names start -with @code{-@var{S}}, but which also take an argument. This is used for -switches like @option{-o}, @option{-D}, @option{-I}, etc. -GCC considers @option{-o foo} as being -one switch whose name starts with @samp{o}. %@{o*@} substitutes this -text, including the space. Thus two arguments are generated. - -@item %@{@var{S}*&@var{T}*@} -Like %@{@code{@var{S}}*@}, but preserve order of @code{@var{S}} and @code{@var{T}} options -(the order of @code{@var{S}} and @code{@var{T}} in the spec is not significant). -There can be any number of ampersand-separated variables; for each the -wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}. - -@item %@{@var{S}:@var{X}@} -Substitutes @code{@var{X}}, if the @option{-@var{S}} switch is given to GCC@. - -@item %@{!@var{S}:@var{X}@} -Substitutes @code{@var{X}}, if the @option{-@var{S}} switch is @emph{not} given to GCC@. - -@item %@{@var{S}*:@var{X}@} -Substitutes @code{@var{X}} if one or more switches whose names start with -@code{-@var{S}} are specified to GCC@. Normally @code{@var{X}} is substituted only -once, no matter how many such switches appeared. However, if @code{%*} -appears somewhere in @code{@var{X}}, then @code{@var{X}} is substituted once -for each matching switch, with the @code{%*} replaced by the part of -that switch matching the @code{*}. - -If @code{%*} appears as the last part of a spec sequence then a space -is added after the end of the last substitution. If there is more -text in the sequence, however, then a space is not generated. This -allows the @code{%*} substitution to be used as part of a larger -string. For example, a spec string like this: - -@smallexample -%@{mcu=*:--script=%*/memory.ld@} -@end smallexample - -@noindent -when matching an option like @option{-mcu=newchip} produces: - -@smallexample ---script=newchip/memory.ld -@end smallexample - -@item %@{.@var{S}:@var{X}@} -Substitutes @code{@var{X}}, if processing a file with suffix @code{@var{S}}. - -@item %@{!.@var{S}:@var{X}@} -Substitutes @code{@var{X}}, if @emph{not} processing a file with suffix @code{@var{S}}. - -@item %@{,@var{S}:@var{X}@} -Substitutes @code{@var{X}}, if processing a file for language @code{@var{S}}. - -@item %@{!,@var{S}:@var{X}@} -Substitutes @code{@var{X}}, if not processing a file for language @code{@var{S}}. - -@item %@{@var{S}|@var{P}:@var{X}@} -Substitutes @code{@var{X}} if either @code{-@var{S}} or @code{-@var{P}} is given to -GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and -@code{*} sequences as well, although they have a stronger binding than -the @samp{|}. If @code{%*} appears in @code{@var{X}}, all of the -alternatives must be starred, and only the first matching alternative -is substituted. - -For example, a spec string like this: - -@smallexample -%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@} -@end smallexample - -@noindent -outputs the following command-line options from the following input -command-line options: - -@smallexample -fred.c -foo -baz -jim.d -bar -boggle --d fred.c -foo -baz -boggle --d jim.d -bar -baz -boggle -@end smallexample - -@item %@{%:@var{function}(@var{args}):@var{X}@} - -Call function named @var{function} with args @var{args}. If the -function returns non-NULL, then @code{@var{X}} is substituted, if it returns -NULL, it isn't substituted. - -@item %@{@var{S}:@var{X}; @var{T}:@var{Y}; :@var{D}@} - -If @code{@var{S}} is given to GCC, substitutes @code{@var{X}}; else if @code{@var{T}} is -given to GCC, substitutes @code{@var{Y}}; else substitutes @code{@var{D}}. There can -be as many clauses as you need. This may be combined with @code{.}, -@code{,}, @code{!}, @code{|}, and @code{*} as needed. - - -@end table - -The switch matching text @code{@var{S}} in a @samp{%@{@var{S}@}}, @samp{%@{@var{S}:@var{X}@}} -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:@var{X}@}} substitutes @code{@var{X}} if the -@option{-std=iso9899:1999} option is given. - -The conditional text @code{@var{X}} in a @samp{%@{@var{S}:@var{X}@}} or similar -construct may contain other nested @samp{%} constructs or spaces, or -even newlines. They are processed as usual, as described above. -Trailing white space in @code{@var{X}} is ignored. White space may also -appear anywhere on the left side of the colon in these constructs, -except between @code{.} or @code{*} and the corresponding word. - -The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are -handled specifically in these constructs. If another value of -@option{-O} or the negated form of a @option{-f}, @option{-m}, or -@option{-W} switch is found later in the command line, the earlier -switch value is ignored, except with @{@code{@var{S}}*@} where @code{@var{S}} is -just one letter, which passes all matching options. - -The character @samp{|} at the beginning of the predicate text is used to -indicate that a command should be piped to the following command, but -only if @option{-pipe} is specified. - -It is built into GCC which switches take arguments and which do not. -(You might think it would be useful to generalize this to allow each -compiler's spec to say which switches take arguments. But this cannot -be done in a consistent fashion. GCC cannot even decide which input -files have been specified without knowing which switches take arguments, -and it must know which input files to compile in order to tell which -compilers to run). - -GCC also knows implicitly that arguments starting in @option{-l} are to be -treated as compiler output files, and passed to the linker in their -proper position among the other output files. - @node Environment Variables @section Environment Variables Affecting GCC @cindex environment variables diff --git a/gcc/doc/specs.texi b/gcc/doc/specs.texi new file mode 100644 index 000000000000..8acac9cd65dd --- /dev/null +++ b/gcc/doc/specs.texi @@ -0,0 +1,693 @@ +@node Spec Files +@chapter Specifying Subprocesses and the Switches to Pass to Them +@cindex Spec Files + +@command{gcc} is a driver program. It performs its job by invoking a +sequence of other programs to do the work of compiling, assembling and +linking. GCC interprets its command-line parameters and uses these to +deduce which programs it should invoke, and which command-line options +it ought to place on their command lines. This behavior is controlled +by @dfn{spec strings}. In most cases there is one spec string for each +program that GCC can invoke, but a few programs have multiple spec +strings to control their behavior. The spec strings built into GCC can +be overridden by using the @option{-specs=} command-line switch to specify +a spec file. + +@dfn{Spec files} are 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: + +@table @code +@item %@var{command} +Issues a @var{command} to the spec file processor. The commands that can +appear here are: + +@table @code +@cindex @code{%include} +@item %include <@var{file}> +Search for @var{file} and insert its text at the current point in the +specs file. + +@cindex @code{%include_noerr} +@item %include_noerr <@var{file}> +Just like @samp{%include}, but do not generate an error message if the include +file cannot be found. + +@cindex @code{%rename} +@item %rename @var{old_name} @var{new_name} +Rename the spec string @var{old_name} to @var{new_name}. + +@end table + +@item *[@var{spec_name}]: +This tells the compiler to create, override or delete the named spec +string. All lines after this directive up to the next directive or +blank line are considered to be the text for the spec string. If this +results in an empty string then the spec is deleted. (Or, if the +spec did not exist, then nothing happens.) Otherwise, if the spec +does not currently exist a new spec is created. If the spec does +exist then its contents are overridden by the text of this +directive, unless the first character of that text is the @samp{+} +character, in which case the text is appended to the spec. + +@item [@var{suffix}]: +Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive +and up to the next directive or blank line are considered to make up the +spec string for the indicated suffix. When the compiler encounters an +input file with the named suffix, it processes the spec string in +order to work out how to compile that file. For example: + +@smallexample +.ZZ: +z-compile -input %i +@end smallexample + +This says that any input file whose name ends in @samp{.ZZ} should be +passed to the program @samp{z-compile}, which should be invoked with the +command-line switch @option{-input} and with the result of performing the +@samp{%i} substitution. (See below.) + +As an alternative to providing a spec string, the text following a +suffix directive can be one of the following: + +@table @code +@item @@@var{language} +This says that the suffix is an alias for a known @var{language}. This is +similar to using the @option{-x} command-line switch to GCC to specify a +language explicitly. For example: + +@smallexample +.ZZ: +@@c++ +@end smallexample + +Says that .ZZ files are, in fact, C++ source files. + +@item #@var{name} +This causes an error messages saying: + +@smallexample +@var{name} compiler not installed on this system. +@end smallexample +@end table + +GCC already has an extensive list of suffixes built into it. +This directive adds an entry to the end of the list of suffixes, but +since the list is searched from the end backwards, it is effectively +possible to override earlier entries using this technique. + +@end table + +GCC has the following spec strings built into it. Spec files can +override these strings or create their own. Note that individual +targets can also add their own spec strings to this list. + +@smallexample +asm Options to pass to the assembler +asm_final Options to pass to the assembler post-processor +cpp Options to pass to the C preprocessor +cc1 Options to pass to the C compiler +cc1plus Options to pass to the C++ compiler +endfile Object files to include at the end of the link +link Options to pass to the linker +lib Libraries to include on the command line to the linker +libgcc Decides which GCC support library to pass to the linker +linker Sets the name of the linker +startfile Object files to include at the start of the link +@end smallexample + +Here is a small example of a spec file: + +@smallexample +%rename lib old_lib + +*lib: +--start-group -lgcc -lc -leval1 --end-group %(old_lib) +@end smallexample + +This example renames the spec called @samp{lib} to @samp{old_lib} and +then overrides the previous definition of @samp{lib} with a new one. +The new definition adds in some extra command-line options before +including the text of the old definition. + +@dfn{Spec strings} are a list of command-line options to be passed to their +corresponding program. In addition, the spec strings can contain +@samp{%}-prefixed sequences to substitute variable text or to +conditionally insert text into the command line. Using these constructs +it is possible to generate quite complex command lines. + +Here is a table of all defined @samp{%}-sequences for spec +strings. Note that spaces are not generated automatically around the +results of expanding these sequences. Therefore you can concatenate them +together or combine them with constant text in a single argument. + +@table @code +@item %% +Substitute one @samp{%} into the program name or argument. + +@item %" +Substitute an empty argument. + +@item %i +Substitute the name of the input file being processed. + +@item %b +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. + +@item %B +This is the same as @samp{%b}, but include the file suffix (text after +the last period). Without %w, it expands to the basename for dump +outputs. + +@item %d +Marks the argument containing or following the @samp{%d} as a +temporary file name, so that that file is deleted if GCC exits +successfully. Unlike @samp{%g}, this contributes no text to the +argument. + +@item %g@var{suffix} +Substitute a file name that has suffix @var{suffix} and is chosen +once per compilation, and mark the argument in the same way as +@samp{%d}. To reduce exposure to denial-of-service attacks, the file +name is now chosen in a way that is hard to predict even when previously +chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s} +might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches +the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is +treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g} +was simply substituted with a file name chosen once per compilation, +without regard to any appended suffix (which was therefore treated +just like ordinary text), making such attacks more likely to succeed. + +@item %u@var{suffix} +Like @samp{%g}, but generates a new temporary file name +each time it appears instead of once per compilation. + +@item %U@var{suffix} +Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a +new one if there is no such last file name. In the absence of any +@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share +the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s} +involves the generation of two distinct file names, one +for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was +simply substituted with a file name chosen for the previous @samp{%u}, +without regard to any appended suffix. + +@item %j@var{suffix} +Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is +writable, and if @option{-save-temps} is not used; +otherwise, substitute the name +of a temporary file, just like @samp{%u}. This temporary file is not +meant for communication between processes, but rather as a junk +disposal mechanism. + +@item %|@var{suffix} +@itemx %m@var{suffix} +Like @samp{%g}, except if @option{-pipe} is in effect. In that case +@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at +all. These are the two most common ways to instruct a program that it +should read from standard input or write to standard output. If you +need something more elaborate you can use an @samp{%@{pipe:@code{X}@}} +construct: see for example @file{gcc/fortran/lang-specs.h}. + +@item %.@var{SUFFIX} +Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args +when it is subsequently output with @samp{%*}. @var{SUFFIX} is +terminated by the next space or %. + +@item %w +Marks the argument containing or following the @samp{%w} as the +designated output file of this compilation. This puts the argument +into the sequence of arguments that @samp{%o} substitutes. + +@item %V +Indicates that this compilation produces no output file. + +@item %o +Substitutes the names of all the output files, with spaces +automatically placed around them. You should write spaces +around the @samp{%o} as well or the results are undefined. +@samp{%o} is for use in the specs for running the linker. +Input files whose names have no recognized suffix are not compiled +at all, but they are included among the output files, so they are +linked. + +@item %O +Substitutes the suffix for object files. Note that this is +handled specially when it immediately follows @samp{%g, %u, or %U}, +because of the need for those to form complete file names. The +handling is such that @samp{%O} is treated exactly as if it had already +been substituted, except that @samp{%g, %u, and %U} do not currently +support additional @var{suffix} characters following @samp{%O} as they do +following, for example, @samp{.o}. + +@item %I +Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}), +@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}), +@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options) +and @option{-imultilib} as necessary. + +@item %s +Current argument is the name of a library or startup file of some sort. +Search for that file in a standard list of directories and substitute +the full name found. The current working directory is included in the +list of directories scanned. + +@item %T +Current argument is the name of a linker script. Search for that file +in the current list of directories to scan for libraries. If the file +is located insert a @option{--script} option into the command line +followed by the full path name found. If the file is not found then +generate an error message. Note: the current working directory is not +searched. + +@item %e@var{str} +Print @var{str} as an error message. @var{str} is terminated by a newline. +Use this when inconsistent options are detected. + +@item %n@var{str} +Print @var{str} as a notice. @var{str} is terminated by a newline. + +@item %(@var{name}) +Substitute the contents of spec string @var{name} at this point. + +@item %x@{@var{option}@} +Accumulate an option for @samp{%X}. + +@item %X +Output the accumulated linker options specified by a @samp{%x} spec string. + +@item %Y +Output the accumulated assembler options specified by @option{-Wa}. + +@item %Z +Output the accumulated preprocessor options specified by @option{-Wp}. + +@item %M +Output @code{multilib_os_dir}. + +@item %R +Output the concatenation of @code{target_system_root} and @code{target_sysroot_suffix}. + +@item %a +Process the @code{asm} spec. This is used to compute the +switches to be passed to the assembler. + +@item %A +Process the @code{asm_final} spec. This is a spec string for +passing switches to an assembler post-processor, if such a program is +needed. + +@item %l +Process the @code{link} spec. This is the spec for computing the +command line passed to the linker. Typically it makes use of the +@samp{%L %G %S %D and %E} sequences. + +@item %D +Dump out a @option{-L} option for each directory that GCC believes might +contain startup files. If the target supports multilibs then the +current multilib directory is prepended to each of these paths. + +@item %L +Process the @code{lib} spec. This is a spec string for deciding which +libraries are included on the command line to the linker. + +@item %G +Process the @code{libgcc} spec. This is a spec string for deciding +which GCC support library is included on the command line to the linker. + +@item %S +Process the @code{startfile} spec. This is a spec for deciding which +object files are the first ones passed to the linker. Typically +this might be a file named @file{crt0.o}. + +@item %E +Process the @code{endfile} spec. This is a spec string that specifies +the last object files that are passed to the linker. + +@item %C +Process the @code{cpp} spec. This is used to construct the arguments +to be passed to the C preprocessor. + +@item %1 +Process the @code{cc1} spec. This is used to construct the options to be +passed to the actual C compiler (@command{cc1}). + +@item %2 +Process the @code{cc1plus} spec. This is used to construct the options to be +passed to the actual C++ compiler (@command{cc1plus}). + +@item %* +Substitute the variable part of a matched option. See below. +Note that each comma in the substituted string is replaced by +a single space. + +@item %<@var{S} +Remove all occurrences of @code{-@var{S}} from the command line. Note---this +command is position dependent. @samp{%} commands in the spec string +before this one see @code{-@var{S}}, @samp{%} commands in the spec string +after this one do not. + +@item %<@var{S}* +Similar to @samp{%<@var{S}}, but match all switches beginning with @code{-@var{S}}. + +@item %>@var{S} +Similar to @samp{%<@var{S}}, but keep @code{-@var{S}} in the GCC command line. + +@item %:@var{function}(@var{args}) +Call the named function @var{function}, passing it @var{args}. +@var{args} is first processed as a nested spec string, then split +into an argument vector in the usual fashion. The function returns +a string which is processed as if it had appeared literally as part +of the current spec. + +The following built-in spec functions are provided: + +@table @code +@item @code{getenv} +The @code{getenv} spec function takes two arguments: an environment +variable name and a string. If the environment variable is not +defined, a fatal error is issued. Otherwise, the return value is the +value of the environment variable concatenated with the string. For +example, if @env{TOPDIR} is defined as @file{/path/to/top}, then: + +@smallexample +%:getenv(TOPDIR /include) +@end smallexample + +expands to @file{/path/to/top/include}. + +@item @code{if-exists} +The @code{if-exists} spec function takes one argument, an absolute +pathname to a file. If the file exists, @code{if-exists} returns the +pathname. Here is a small example of its usage: + +@smallexample +*startfile: +crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s +@end smallexample + +@item @code{if-exists-else} +The @code{if-exists-else} spec function is similar to the @code{if-exists} +spec function, except that it takes two arguments. The first argument is +an absolute pathname to a file. If the file exists, @code{if-exists-else} +returns the pathname. If it does not exist, it returns the second argument. +This way, @code{if-exists-else} can be used to select one file or another, +based on the existence of the first. Here is a small example of its usage: + +@smallexample +*startfile: +crt0%O%s %:if-exists(crti%O%s) \ +%:if-exists-else(crtbeginT%O%s crtbegin%O%s) +@end smallexample + +@item @code{if-exists-then-else} +The @code{if-exists-then-else} 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: + +@smallexample +-l%:if-exists-then-else(%:getenv(VSB_DIR rtnet.h) rtnet net) +@end smallexample + +@item @code{sanitize} +The @code{sanitize} spec function takes no arguments. It returns non-NULL if +any address, thread or undefined behavior sanitizers are active. + +@smallexample +%@{%:sanitize(address):-funwind-tables@} +@end smallexample + +@item @code{replace-outfile} +The @code{replace-outfile} spec function takes two arguments. It looks for the +first argument in the outfiles array and replaces it with the second argument. Here +is a small example of its usage: + +@smallexample +%@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@} +@end smallexample + +@item @code{remove-outfile} +The @code{remove-outfile} spec function takes one argument. It looks for the +first argument in the outfiles array and removes it. Here is a small example +its usage: + +@smallexample +%:remove-outfile(-lm) +@end smallexample + +@item @code{version-compare} +The @code{version-compare} spec function takes four or five arguments of the following +form: + +@smallexample +<comparison-op> <arg1> [<arg2>] <switch> <result> +@end smallexample + +It returns @code{result} if the comparison evaluates to true, and NULL if it doesn't. +The supported @code{comparison-op} values are: + +@table @code +@item >= +True if @code{switch} is a later (or same) version than @code{arg1} + +@item !> +Opposite of @code{>=} + +@item < +True if @code{switch} is an earlier version than @code{arg1} + +@item !< +Opposite of @code{<} + +@item >< +True if @code{switch} is @code{arg1} or later, and earlier than @code{arg2} + +@item <> +True if @code{switch} is earlier than @code{arg1}, or is @code{arg2} or later +@end table + +If the @code{switch} is not present at all, the condition is false unless the first character +of the @code{comparison-op} is @code{!}. + +@smallexample +%:version-compare(>= 10.3 mmacosx-version-min= -lmx) +@end smallexample + +The above example would add @option{-lmx} if @option{-mmacosx-version-min=10.3.9} was +passed. + +@item @code{include} +The @code{include} spec function behaves much like @code{%include}, 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. + +@smallexample +%@{static-libasan|static:%:include(libsanitizer.spec)%(link_libasan)@} +@end smallexample + +@item @code{pass-through-libs} +The @code{pass-through-libs} spec function takes any number of arguments. It +finds any @option{-l} options and any non-options ending in @file{.a} (which it +assumes are the names of linker input library archive files) and returns a +result containing all the found arguments each prepended by +@option{-plugin-opt=-pass-through=} and joined by spaces. This list is +intended to be passed to the LTO linker plugin. + +@smallexample +%:pass-through-libs(%G %L %G) +@end smallexample + +@item @code{print-asm-header} +The @code{print-asm-header} function takes no arguments and simply +prints a banner like: + +@smallexample +Assembler options +================= + +Use "-Wa,OPTION" to pass "OPTION" to the assembler. +@end smallexample + +It is used to separate compiler options from assembler options +in the @option{--target-help} output. + +@item @code{gt} +The @code{gt} spec function takes two or more arguments. It returns @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} spec if the last +@option{-ftree-parallelize-loops=} option given on the command line is greater than 1: + +@smallexample +%@{%:gt(%@{ftree-parallelize-loops=*:%*@} 1):%:include(libgomp.spec)%(link_gomp)@} +@end smallexample + +@item @code{debug-level-gt} +The @code{debug-level-gt} spec function takes one argument and returns @code{""} (the +empty string) if @code{debug_info_level} is greater than the specified number, and NULL +otherwise. + +@smallexample +%@{%:debug-level-gt(0):%@{gdwarf*:--gdwarf2@}@} +@end smallexample +@end table + +@item %@{@var{S}@} +Substitutes the @code{-@var{S}} switch, if that switch is given to GCC@. +If that switch is not specified, this substitutes nothing. Note that +the leading dash is omitted when specifying this option, and it is +automatically inserted if the substitution is performed. Thus the spec +string @samp{%@{foo@}} matches the command-line option @option{-foo} +and outputs the command-line option @option{-foo}. + +@item %W@{@var{S}@} +Like %@{@code{@var{S}}@} but mark last argument supplied within as a file to be +deleted on failure. + +@item %@@@{@var{S}@} +Like %@{@code{@var{S}}@} but puts the result into a @code{FILE} and substitutes +@code{@@FILE} if an @code{@@file} argument has been supplied. + +@item %@{@var{S}*@} +Substitutes all the switches specified to GCC whose names start +with @code{-@var{S}}, but which also take an argument. This is used for +switches like @option{-o}, @option{-D}, @option{-I}, etc. +GCC considers @option{-o foo} as being +one switch whose name starts with @samp{o}. %@{o*@} substitutes this +text, including the space. Thus two arguments are generated. + +@item %@{@var{S}*&@var{T}*@} +Like %@{@code{@var{S}}*@}, but preserve order of @code{@var{S}} and @code{@var{T}} options +(the order of @code{@var{S}} and @code{@var{T}} in the spec is not significant). +There can be any number of ampersand-separated variables; for each the +wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}. + +@item %@{@var{S}:@var{X}@} +Substitutes @code{@var{X}}, if the @option{-@var{S}} switch is given to GCC@. + +@item %@{!@var{S}:@var{X}@} +Substitutes @code{@var{X}}, if the @option{-@var{S}} switch is @emph{not} given to GCC@. + +@item %@{@var{S}*:@var{X}@} +Substitutes @code{@var{X}} if one or more switches whose names start with +@code{-@var{S}} are specified to GCC@. Normally @code{@var{X}} is substituted only +once, no matter how many such switches appeared. However, if @code{%*} +appears somewhere in @code{@var{X}}, then @code{@var{X}} is substituted once +for each matching switch, with the @code{%*} replaced by the part of +that switch matching the @code{*}. + +If @code{%*} appears as the last part of a spec sequence then a space +is added after the end of the last substitution. If there is more +text in the sequence, however, then a space is not generated. This +allows the @code{%*} substitution to be used as part of a larger +string. For example, a spec string like this: + +@smallexample +%@{mcu=*:--script=%*/memory.ld@} +@end smallexample + +@noindent +when matching an option like @option{-mcu=newchip} produces: + +@smallexample +--script=newchip/memory.ld +@end smallexample + +@item %@{.@var{S}:@var{X}@} +Substitutes @code{@var{X}}, if processing a file with suffix @code{@var{S}}. + +@item %@{!.@var{S}:@var{X}@} +Substitutes @code{@var{X}}, if @emph{not} processing a file with suffix @code{@var{S}}. + +@item %@{,@var{S}:@var{X}@} +Substitutes @code{@var{X}}, if processing a file for language @code{@var{S}}. + +@item %@{!,@var{S}:@var{X}@} +Substitutes @code{@var{X}}, if not processing a file for language @code{@var{S}}. + +@item %@{@var{S}|@var{P}:@var{X}@} +Substitutes @code{@var{X}} if either @code{-@var{S}} or @code{-@var{P}} is given to +GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and +@code{*} sequences as well, although they have a stronger binding than +the @samp{|}. If @code{%*} appears in @code{@var{X}}, all of the +alternatives must be starred, and only the first matching alternative +is substituted. + +For example, a spec string like this: + +@smallexample +%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@} +@end smallexample + +@noindent +outputs the following command-line options from the following input +command-line options: + +@smallexample +fred.c -foo -baz +jim.d -bar -boggle +-d fred.c -foo -baz -boggle +-d jim.d -bar -baz -boggle +@end smallexample + +@item %@{%:@var{function}(@var{args}):@var{X}@} + +Call function named @var{function} with args @var{args}. If the +function returns non-NULL, then @code{@var{X}} is substituted, if it returns +NULL, it isn't substituted. + +@item %@{@var{S}:@var{X}; @var{T}:@var{Y}; :@var{D}@} + +If @code{@var{S}} is given to GCC, substitutes @code{@var{X}}; else if @code{@var{T}} is +given to GCC, substitutes @code{@var{Y}}; else substitutes @code{@var{D}}. There can +be as many clauses as you need. This may be combined with @code{.}, +@code{,}, @code{!}, @code{|}, and @code{*} as needed. + + +@end table + +The switch matching text @code{@var{S}} in a @samp{%@{@var{S}@}}, @samp{%@{@var{S}:@var{X}@}} +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:@var{X}@}} substitutes @code{@var{X}} if the +@option{-std=iso9899:1999} option is given. + +The conditional text @code{@var{X}} in a @samp{%@{@var{S}:@var{X}@}} or similar +construct may contain other nested @samp{%} constructs or spaces, or +even newlines. They are processed as usual, as described above. +Trailing white space in @code{@var{X}} is ignored. White space may also +appear anywhere on the left side of the colon in these constructs, +except between @code{.} or @code{*} and the corresponding word. + +The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are +handled specifically in these constructs. If another value of +@option{-O} or the negated form of a @option{-f}, @option{-m}, or +@option{-W} switch is found later in the command line, the earlier +switch value is ignored, except with @{@code{@var{S}}*@} where @code{@var{S}} is +just one letter, which passes all matching options. + +The character @samp{|} at the beginning of the predicate text is used to +indicate that a command should be piped to the following command, but +only if @option{-pipe} is specified. + +It is built into GCC which switches take arguments and which do not. +(You might think it would be useful to generalize this to allow each +compiler's spec to say which switches take arguments. But this cannot +be done in a consistent fashion. GCC cannot even decide which input +files have been specified without knowing which switches take arguments, +and it must know which input files to compile in order to tell which +compilers to run). + +GCC also knows implicitly that arguments starting in @option{-l} are to be +treated as compiler output files, and passed to the linker in their +proper position among the other output files.
