gcc: Spec Files
1
1 3.19 Specifying Subprocesses and the Switches to Pass to Them
1 =============================================================
1
1 'gcc' is a driver program. It performs its job by invoking a sequence
1 of other programs to do the work of compiling, assembling and linking.
1 GCC interprets its command-line parameters and uses these to deduce
1 which programs it should invoke, and which command-line options it ought
1 to place on their command lines. This behavior is controlled by "spec
1 strings". In most cases there is one spec string for each program that
1 GCC can invoke, but a few programs have multiple spec strings to control
1 their behavior. The spec strings built into GCC can be overridden by
1 using the '-specs=' command-line switch to specify a spec file.
1
1 "Spec files" are plain-text files that are used to construct spec
1 strings. They consist of a sequence of directives separated by blank
1 lines. The type of directive is determined by the first non-whitespace
1 character on the line, which can be one of the following:
1
1 '%COMMAND'
1 Issues a COMMAND to the spec file processor. The commands that can
1 appear here are:
1
1 '%include <FILE>'
1 Search for FILE and insert its text at the current point in
1 the specs file.
1
1 '%include_noerr <FILE>'
1 Just like '%include', but do not generate an error message if
1 the include file cannot be found.
1
1 '%rename OLD_NAME NEW_NAME'
1 Rename the spec string OLD_NAME to NEW_NAME.
1
1 '*[SPEC_NAME]:'
1 This tells the compiler to create, override or delete the named
1 spec string. All lines after this directive up to the next
1 directive or blank line are considered to be the text for the spec
1 string. If this results in an empty string then the spec is
1 deleted. (Or, if the spec did not exist, then nothing happens.)
1 Otherwise, if the spec does not currently exist a new spec is
1 created. If the spec does exist then its contents are overridden
1 by the text of this directive, unless the first character of that
1 text is the '+' character, in which case the text is appended to
1 the spec.
1
1 '[SUFFIX]:'
1 Creates a new '[SUFFIX] spec' pair. All lines after this directive
1 and up to the next directive or blank line are considered to make
1 up the spec string for the indicated suffix. When the compiler
1 encounters an input file with the named suffix, it processes the
1 spec string in order to work out how to compile that file. For
1 example:
1
1 .ZZ:
1 z-compile -input %i
1
1 This says that any input file whose name ends in '.ZZ' should be
1 passed to the program 'z-compile', which should be invoked with the
1 command-line switch '-input' and with the result of performing the
1 '%i' substitution. (See below.)
1
1 As an alternative to providing a spec string, the text following a
1 suffix directive can be one of the following:
1
1 '@LANGUAGE'
1 This says that the suffix is an alias for a known LANGUAGE.
1 This is similar to using the '-x' command-line switch to GCC
1 to specify a language explicitly. For example:
1
1 .ZZ:
1 @c++
1
1 Says that .ZZ files are, in fact, C++ source files.
1
1 '#NAME'
1 This causes an error messages saying:
1
1 NAME compiler not installed on this system.
1
1 GCC already has an extensive list of suffixes built into it. This
1 directive adds an entry to the end of the list of suffixes, but
1 since the list is searched from the end backwards, it is
1 effectively possible to override earlier entries using this
1 technique.
1
1 GCC has the following spec strings built into it. Spec files can
1 override these strings or create their own. Note that individual
1 targets can also add their own spec strings to this list.
1
1 asm Options to pass to the assembler
1 asm_final Options to pass to the assembler post-processor
1 cpp Options to pass to the C preprocessor
1 cc1 Options to pass to the C compiler
1 cc1plus Options to pass to the C++ compiler
1 endfile Object files to include at the end of the link
1 link Options to pass to the linker
1 lib Libraries to include on the command line to the linker
1 libgcc Decides which GCC support library to pass to the linker
1 linker Sets the name of the linker
1 predefines Defines to be passed to the C preprocessor
1 signed_char Defines to pass to CPP to say whether char is signed
1 by default
1 startfile Object files to include at the start of the link
1
1 Here is a small example of a spec file:
1
1 %rename lib old_lib
1
1 *lib:
1 --start-group -lgcc -lc -leval1 --end-group %(old_lib)
1
1 This example renames the spec called 'lib' to 'old_lib' and then
1 overrides the previous definition of 'lib' with a new one. The new
1 definition adds in some extra command-line options before including the
1 text of the old definition.
1
1 "Spec strings" are a list of command-line options to be passed to their
1 corresponding program. In addition, the spec strings can contain
1 '%'-prefixed sequences to substitute variable text or to conditionally
1 insert text into the command line. Using these constructs it is
1 possible to generate quite complex command lines.
1
1 Here is a table of all defined '%'-sequences for spec strings. Note
1 that spaces are not generated automatically around the results of
1 expanding these sequences. Therefore you can concatenate them together
1 or combine them with constant text in a single argument.
1
1 '%%'
1 Substitute one '%' into the program name or argument.
1
1 '%i'
1 Substitute the name of the input file being processed.
1
1 '%b'
1 Substitute the basename of the input file being processed. This is
1 the substring up to (and not including) the last period and not
1 including the directory.
1
1 '%B'
1 This is the same as '%b', but include the file suffix (text after
1 the last period).
1
1 '%d'
1 Marks the argument containing or following the '%d' as a temporary
1 file name, so that that file is deleted if GCC exits successfully.
1 Unlike '%g', this contributes no text to the argument.
1
1 '%gSUFFIX'
1 Substitute a file name that has suffix SUFFIX and is chosen once
1 per compilation, and mark the argument in the same way as '%d'. To
1 reduce exposure to denial-of-service attacks, the file name is now
1 chosen in a way that is hard to predict even when previously chosen
1 file names are known. For example, '%g.s ... %g.o ... %g.s' might
1 turn into 'ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s'. SUFFIX matches the
1 regexp '[.A-Za-z]*' or the special string '%O', which is treated
1 exactly as if '%O' had been preprocessed. Previously, '%g' was
1 simply substituted with a file name chosen once per compilation,
1 without regard to any appended suffix (which was therefore treated
1 just like ordinary text), making such attacks more likely to
1 succeed.
1
1 '%uSUFFIX'
1 Like '%g', but generates a new temporary file name each time it
1 appears instead of once per compilation.
1
1 '%USUFFIX'
1 Substitutes the last file name generated with '%uSUFFIX',
1 generating a new one if there is no such last file name. In the
1 absence of any '%uSUFFIX', this is just like '%gSUFFIX', except
1 they don't share the same suffix _space_, so '%g.s ... %U.s ...
1 %g.s ... %U.s' involves the generation of two distinct file names,
1 one for each '%g.s' and another for each '%U.s'. Previously, '%U'
1 was simply substituted with a file name chosen for the previous
1 '%u', without regard to any appended suffix.
1
1 '%jSUFFIX'
1 Substitutes the name of the 'HOST_BIT_BUCKET', if any, and if it is
1 writable, and if '-save-temps' is not used; otherwise, substitute
1 the name of a temporary file, just like '%u'. This temporary file
1 is not meant for communication between processes, but rather as a
1 junk disposal mechanism.
1
1 '%|SUFFIX'
1 '%mSUFFIX'
1 Like '%g', except if '-pipe' is in effect. In that case '%|'
1 substitutes a single dash and '%m' substitutes nothing at all.
1 These are the two most common ways to instruct a program that it
1 should read from standard input or write to standard output. If
1 you need something more elaborate you can use an '%{pipe:'X'}'
1 construct: see for example 'f/lang-specs.h'.
1
1 '%.SUFFIX'
1 Substitutes .SUFFIX for the suffixes of a matched switch's args
1 when it is subsequently output with '%*'. SUFFIX is terminated by
1 the next space or %.
1
1 '%w'
1 Marks the argument containing or following the '%w' as the
1 designated output file of this compilation. This puts the argument
1 into the sequence of arguments that '%o' substitutes.
1
1 '%o'
1 Substitutes the names of all the output files, with spaces
1 automatically placed around them. You should write spaces around
1 the '%o' as well or the results are undefined. '%o' is for use in
1 the specs for running the linker. Input files whose names have no
1 recognized suffix are not compiled at all, but they are included
1 among the output files, so they are linked.
1
1 '%O'
1 Substitutes the suffix for object files. Note that this is handled
1 specially when it immediately follows '%g, %u, or %U', because of
1 the need for those to form complete file names. The handling is
1 such that '%O' is treated exactly as if it had already been
1 substituted, except that '%g, %u, and %U' do not currently support
1 additional SUFFIX characters following '%O' as they do following,
1 for example, '.o'.
1
1 '%p'
1 Substitutes the standard macro predefinitions for the current
1 target machine. Use this when running 'cpp'.
1
1 '%P'
1 Like '%p', but puts '__' before and after the name of each
1 predefined macro, except for macros that start with '__' or with
1 '_L', where L is an uppercase letter. This is for ISO C.
1
1 '%I'
1 Substitute any of '-iprefix' (made from 'GCC_EXEC_PREFIX'),
1 '-isysroot' (made from 'TARGET_SYSTEM_ROOT'), '-isystem' (made from
1 'COMPILER_PATH' and '-B' options) and '-imultilib' as necessary.
1
1 '%s'
1 Current argument is the name of a library or startup file of some
1 sort. Search for that file in a standard list of directories and
1 substitute the full name found. The current working directory is
1 included in the list of directories scanned.
1
1 '%T'
1 Current argument is the name of a linker script. Search for that
1 file in the current list of directories to scan for libraries. If
1 the file is located insert a '--script' option into the command
1 line followed by the full path name found. If the file is not
1 found then generate an error message. Note: the current working
1 directory is not searched.
1
1 '%eSTR'
1 Print STR as an error message. STR is terminated by a newline.
1 Use this when inconsistent options are detected.
1
1 '%(NAME)'
1 Substitute the contents of spec string NAME at this point.
1
1 '%x{OPTION}'
1 Accumulate an option for '%X'.
1
1 '%X'
1 Output the accumulated linker options specified by '-Wl' or a '%x'
1 spec string.
1
1 '%Y'
1 Output the accumulated assembler options specified by '-Wa'.
1
1 '%Z'
1 Output the accumulated preprocessor options specified by '-Wp'.
1
1 '%a'
1 Process the 'asm' spec. This is used to compute the switches to be
1 passed to the assembler.
1
1 '%A'
1 Process the 'asm_final' spec. This is a spec string for passing
1 switches to an assembler post-processor, if such a program is
1 needed.
1
1 '%l'
1 Process the 'link' spec. This is the spec for computing the
1 command line passed to the linker. Typically it makes use of the
1 '%L %G %S %D and %E' sequences.
1
1 '%D'
1 Dump out a '-L' option for each directory that GCC believes might
1 contain startup files. If the target supports multilibs then the
1 current multilib directory is prepended to each of these paths.
1
1 '%L'
1 Process the 'lib' spec. This is a spec string for deciding which
1 libraries are included on the command line to the linker.
1
1 '%G'
1 Process the 'libgcc' spec. This is a spec string for deciding
1 which GCC support library is included on the command line to the
1 linker.
1
1 '%S'
1 Process the 'startfile' spec. This is a spec for deciding which
1 object files are the first ones passed to the linker. Typically
1 this might be a file named 'crt0.o'.
1
1 '%E'
1 Process the 'endfile' spec. This is a spec string that specifies
1 the last object files that are passed to the linker.
1
1 '%C'
1 Process the 'cpp' spec. This is used to construct the arguments to
1 be passed to the C preprocessor.
1
1 '%1'
1 Process the 'cc1' spec. This is used to construct the options to
1 be passed to the actual C compiler ('cc1').
1
1 '%2'
1 Process the 'cc1plus' spec. This is used to construct the options
1 to be passed to the actual C++ compiler ('cc1plus').
1
1 '%*'
1 Substitute the variable part of a matched option. See below. Note
1 that each comma in the substituted string is replaced by a single
1 space.
1
1 '%<S'
1 Remove all occurrences of '-S' from the command line. Note--this
1 command is position dependent. '%' commands in the spec string
1 before this one see '-S', '%' commands in the spec string after
1 this one do not.
1
1 '%:FUNCTION(ARGS)'
1 Call the named function FUNCTION, passing it ARGS. ARGS is first
1 processed as a nested spec string, then split into an argument
1 vector in the usual fashion. The function returns a string which
1 is processed as if it had appeared literally as part of the current
1 spec.
1
1 The following built-in spec functions are provided:
1
1 'getenv'
1 The 'getenv' spec function takes two arguments: an environment
1 variable name and a string. If the environment variable is
1 not defined, a fatal error is issued. Otherwise, the return
1 value is the value of the environment variable concatenated
1 with the string. For example, if 'TOPDIR' is defined as
1 '/path/to/top', then:
1
1 %:getenv(TOPDIR /include)
1
1 expands to '/path/to/top/include'.
1
1 'if-exists'
1 The 'if-exists' spec function takes one argument, an absolute
1 pathname to a file. If the file exists, 'if-exists' returns
1 the pathname. Here is a small example of its usage:
1
1 *startfile:
1 crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
1
1 'if-exists-else'
1 The 'if-exists-else' spec function is similar to the
1 'if-exists' spec function, except that it takes two arguments.
1 The first argument is an absolute pathname to a file. If the
1 file exists, 'if-exists-else' returns the pathname. If it
1 does not exist, it returns the second argument. This way,
1 'if-exists-else' can be used to select one file or another,
1 based on the existence of the first. Here is a small example
1 of its usage:
1
1 *startfile:
1 crt0%O%s %:if-exists(crti%O%s) \
1 %:if-exists-else(crtbeginT%O%s crtbegin%O%s)
1
1 'replace-outfile'
1 The 'replace-outfile' spec function takes two arguments. It
1 looks for the first argument in the outfiles array and
1 replaces it with the second argument. Here is a small example
1 of its usage:
1
1 %{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)}
1
1 'remove-outfile'
1 The 'remove-outfile' spec function takes one argument. It
1 looks for the first argument in the outfiles array and removes
1 it. Here is a small example its usage:
1
1 %:remove-outfile(-lm)
1
1 'pass-through-libs'
1 The 'pass-through-libs' spec function takes any number of
1 arguments. It finds any '-l' options and any non-options
1 ending in '.a' (which it assumes are the names of linker input
1 library archive files) and returns a result containing all the
1 found arguments each prepended by '-plugin-opt=-pass-through='
1 and joined by spaces. This list is intended to be passed to
1 the LTO linker plugin.
1
1 %:pass-through-libs(%G %L %G)
1
1 'print-asm-header'
1 The 'print-asm-header' function takes no arguments and simply
1 prints a banner like:
1
1 Assembler options
1 =================
1
1 Use "-Wa,OPTION" to pass "OPTION" to the assembler.
1
1 It is used to separate compiler options from assembler options
1 in the '--target-help' output.
1
1 '%{S}'
1 Substitutes the '-S' switch, if that switch is given to GCC. If
1 that switch is not specified, this substitutes nothing. Note that
1 the leading dash is omitted when specifying this option, and it is
1 automatically inserted if the substitution is performed. Thus the
1 spec string '%{foo}' matches the command-line option '-foo' and
1 outputs the command-line option '-foo'.
1
1 '%W{S}'
1 Like %{'S'} but mark last argument supplied within as a file to be
1 deleted on failure.
1
1 '%{S*}'
1 Substitutes all the switches specified to GCC whose names start
1 with '-S', but which also take an argument. This is used for
1 switches like '-o', '-D', '-I', etc. GCC considers '-o foo' as
1 being one switch whose name starts with 'o'. %{o*} substitutes
1 this text, including the space. Thus two arguments are generated.
1
1 '%{S*&T*}'
1 Like %{'S'*}, but preserve order of 'S' and 'T' options (the order
1 of 'S' and 'T' in the spec is not significant). There can be any
1 number of ampersand-separated variables; for each the wild card is
1 optional. Useful for CPP as '%{D*&U*&A*}'.
1
1 '%{S:X}'
1 Substitutes 'X', if the '-S' switch is given to GCC.
1
1 '%{!S:X}'
1 Substitutes 'X', if the '-S' switch is _not_ given to GCC.
1
1 '%{S*:X}'
1 Substitutes 'X' if one or more switches whose names start with '-S'
1 are specified to GCC. Normally 'X' is substituted only once, no
1 matter how many such switches appeared. However, if '%*' appears
1 somewhere in 'X', then 'X' is substituted once for each matching
1 switch, with the '%*' replaced by the part of that switch matching
1 the '*'.
1
1 If '%*' appears as the last part of a spec sequence then a space is
1 added after the end of the last substitution. If there is more
1 text in the sequence, however, then a space is not generated. This
1 allows the '%*' substitution to be used as part of a larger string.
1 For example, a spec string like this:
1
1 %{mcu=*:--script=%*/memory.ld}
1
1 when matching an option like '-mcu=newchip' produces:
1
1 --script=newchip/memory.ld
1
1 '%{.S:X}'
1 Substitutes 'X', if processing a file with suffix 'S'.
1
1 '%{!.S:X}'
1 Substitutes 'X', if _not_ processing a file with suffix 'S'.
1
1 '%{,S:X}'
1 Substitutes 'X', if processing a file for language 'S'.
1
1 '%{!,S:X}'
1 Substitutes 'X', if not processing a file for language 'S'.
1
1 '%{S|P:X}'
1 Substitutes 'X' if either '-S' or '-P' is given to GCC. This may
1 be combined with '!', '.', ',', and '*' sequences as well, although
1 they have a stronger binding than the '|'. If '%*' appears in 'X',
1 all of the alternatives must be starred, and only the first
1 matching alternative is substituted.
1
1 For example, a spec string like this:
1
1 %{.c:-foo} %{!.c:-bar} %{.c|d:-baz} %{!.c|d:-boggle}
1
1 outputs the following command-line options from the following input
1 command-line options:
1
1 fred.c -foo -baz
1 jim.d -bar -boggle
1 -d fred.c -foo -baz -boggle
1 -d jim.d -bar -baz -boggle
1
1 '%{S:X; T:Y; :D}'
1
1 If 'S' is given to GCC, substitutes 'X'; else if 'T' is given to
1 GCC, substitutes 'Y'; else substitutes 'D'. There can be as many
1 clauses as you need. This may be combined with '.', ',', '!', '|',
1 and '*' as needed.
1
1 The switch matching text 'S' in a '%{S}', '%{S:X}' or similar construct
1 can use a backslash to ignore the special meaning of the character
1 following it, thus allowing literal matching of a character that is
1 otherwise specially treated. For example, '%{std=iso9899\:1999:X}'
1 substitutes 'X' if the '-std=iso9899:1999' option is given.
1
1 The conditional text 'X' in a '%{S:X}' or similar construct may contain
1 other nested '%' constructs or spaces, or even newlines. They are
1 processed as usual, as described above. Trailing white space in 'X' is
1 ignored. White space may also appear anywhere on the left side of the
1 colon in these constructs, except between '.' or '*' and the
1 corresponding word.
1
1 The '-O', '-f', '-m', and '-W' switches are handled specifically in
1 these constructs. If another value of '-O' or the negated form of a
1 '-f', '-m', or '-W' switch is found later in the command line, the
1 earlier switch value is ignored, except with {'S'*} where 'S' is just
1 one letter, which passes all matching options.
1
1 The character '|' at the beginning of the predicate text is used to
1 indicate that a command should be piped to the following command, but
1 only if '-pipe' is specified.
1
1 It is built into GCC which switches take arguments and which do not.
1 (You might think it would be useful to generalize this to allow each
1 compiler's spec to say which switches take arguments. But this cannot
1 be done in a consistent fashion. GCC cannot even decide which input
1 files have been specified without knowing which switches take arguments,
1 and it must know which input files to compile in order to tell which
1 compilers to run).
1
1 GCC also knows implicitly that arguments starting in '-l' are to be
1 treated as compiler output files, and passed to the linker in their
1 proper position among the other output files.
1