GCC Specs File Format Described

PS: This description is also accessible via "info gcc", then "g Spec Files".

 

 

Specifying subprocesses and the switches to pass to them 
========================================================

   `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 behaviour is controlled
by "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 behaviour.  The spec strings built into GCC can
be overridden by using the `-specs=' command-line switch to specify a
spec file.

   "Spec files" are plaintext 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 and it can be one of the following:

`%COMMAND'
     Issues a COMMAND to the spec file processor.  The commands that can
     appear here are:

    `%include '
          Search for FILE and insert its text at the current point in
          the specs file.

    `%include_noerr '
          Just like `%include', but do not generate an error message if
          the include file cannot be found.

    `%rename OLD_NAME NEW_NAME'
          Rename the spec string OLD_NAME to NEW_NAME.

`*[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 will be
     deleted.  (Or, if the spec did not exist, then nothing will
     happened.)  Otherwise, if the spec does not currently exist a new
     spec will be created.  If the spec does exist then its contents
     will be overridden by the text of this directive, unless the first
     character of that text is the `+' character, in which case the
     text will be appended to the spec.

`[SUFFIX]:'
     Creates a new `[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 will processes
     the spec string in order to work out how to compile that file.
     For example:

          .ZZ:
          z-compile -input %i

     This says that any input file whose name ends in `.ZZ' should be
     passed to the program `z-compile', which should be invoked with the
     command-line switch `-input' and with the result of performing the
     `%i' substitution.  (See below.)

     As an alternative to providing a spec string, the text that
     follows a suffix directive can be one of the following:

    `@LANGUAGE'
          This says that the suffix is an alias for a known LANGUAGE.
          This is similar to using the `-x' command-line switch to GCC
          to specify a language explicitly.  For example:

               .ZZ:
               @c++

          Says that .ZZ files are, in fact, C++ source files.

    `#NAME'
          This causes an error messages saying:

               NAME compiler not installed on this system.

     GCC already has an extensive list of suffixes built into it.  This
     directive will add 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.

   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.

     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 `char' is signed by default
     startfile    Object files to include at the start of the link

   Here is a small example of a spec file:

     %rename lib                 old_lib
     
     *lib:
     --start-group -lgcc -lc -leval1 --end-group %(old_lib)

   This example renames the spec called `lib' to `old_lib' and then
overrides the previous definition of `lib' with a new one.  The new
definition adds in some extra command-line options before including the
text of the old definition.

   "Spec strings" are a list of command-line options to be passed to
their corresponding program.  In addition, the spec strings can contain
`%'-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 `%'-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.

`%%'
     Substitute one `%' into the program name or argument.

`%i'
     Substitute the name of the input file being processed.

`%b'
     Substitute the basename of the input file being processed.  This
     is the substring up to (and not including) the last period and not
     including the directory.

`%d'
     Marks the argument containing or following the `%d' as a temporary
     file name, so that that file will be deleted if GCC exits
     successfully.  Unlike `%g', this contributes no text to the
     argument.

`%gSUFFIX'
     Substitute a file name that has suffix SUFFIX and is chosen once
     per compilation, and mark the argument in the same way as `%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, `%g.s ... %g.o ... %g.s'
     might turn into `ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s'.  SUFFIX
     matches the regexp `[.A-Za-z]*' or the special string `%O', which
     is treated exactly as if `%O' had been preprocessed.  Previously,
     `%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.

`%uSUFFIX'
     Like `%g', but generates a new temporary file name even if
     `%uSUFFIX' was already seen.

`%USUFFIX'
     Substitutes the last file name generated with `%uSUFFIX',
     generating a new one if there is no such last file name.  In the
     absence of any `%uSUFFIX', this is just like `%gSUFFIX', except
     they don't share the same suffix *space*, so `%g.s ... %U.s ...
     %g.s ... %U.s' would involve the generation of two distinct file
     names, one for each `%g.s' and another for each `%U.s'.
     Previously, `%U' was simply substituted with a file name chosen
     for the previous `%u', without regard to any appended suffix.

`%w'
     Marks the argument containing or following the `%w' as the
     designated output file of this compilation.  This puts the argument
     into the sequence of arguments that `%o' will substitute later.

`%o'
     Substitutes the names of all the output files, with spaces
     automatically placed around them.  You should write spaces around
     the `%o' as well or the results are undefined.  `%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 will be linked.

`%O'
     Substitutes the suffix for object files.  Note that this is
     handled specially when it immediately follows `%g, %u, or %U',
     because of the need for those to form complete file names.  The
     handling is such that `%O' is treated exactly as if it had already
     been substituted, except that `%g, %u, and %U' do not currently
     support additional SUFFIX characters following `%O' as they would
     following, for example, `.o'.

`%p'
     Substitutes the standard macro predefinitions for the current
     target machine.  Use this when running `cpp'.

`%P'
     Like `%p', but puts `__' before and after the name of each
     predefined macro, except for macros that start with `__' or with
     `_L', where L is an uppercase letter.  This is for ANSI C.

`%I'
     Substitute a `-iprefix' option made from GCC_EXEC_PREFIX.

`%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.

`%eSTR'
     Print STR as an error message.  STR is terminated by a newline.
     Use this when inconsistent options are detected.

`%|'
     Output `-' if the input for the current command is coming from a
     pipe.

`%(NAME)'
     Substitute the contents of spec string NAME at this point.

`%[NAME]'
     Like `%(...)' but put `__' around `-D' arguments.

`%x{OPTION}'
     Accumulate an option for `%X'.

`%X'
     Output the accumulated linker options specified by `-Wl' or a `%x'
     spec string.

`%Y'
     Output the accumulated assembler options specified by `-Wa'.

`%Z'
     Output the accumulated preprocessor options specified by `-Wp'.

`%v1'
     Substitute the major version number of GCC.  (For version 2.9.5,
     this is 2.)

`%v2'
     Substitute the minor version number of GCC.  (For version 2.9.5,
     this is 9.)

`%a'
     Process the `asm' spec.  This is used to compute the switches to
     be passed to the assembler.

`%A'
     Process the `asm_final' spec.  This is a spec string for passing
     switches to an assembler post-processor, if such a program is
     needed.

`%l'
     Process the `link' spec.  This is the spec for computing the
     command line passed to the linker.  Typically it will make use of
     the `%L %G %S %D and %E' sequences.

`%D'
     Dump out a `-L' option for each directory that GCC believes might
     contain startup files.  If the target supports multilibs then the
     current multilib directory will be prepended to each of these
     paths.

`%L'
     Process the `lib' spec.  This is a spec string for deciding which
     libraries should be included on the command line to the linker.

`%G'
     Process the `libgcc' spec.  This is a spec string for deciding
     which GCC support library should be included on the command line
     to the linker.

`%S'
     Process the `startfile' spec.  This is a spec for deciding which
     object files should be the first ones passed to the linker.
     Typically this might be a file named `crt0.o'.

`%E'
     Process the `endfile' spec.  This is a spec string that specifies
     the last object files that will be passed to the linker.

`%C'
     Process the `cpp' spec.  This is used to construct the arguments
     to be passed to the C preprocessor.

`%c'
     Process the `signed_char' spec.  This is intended to be used to
     tell cpp whether a char is signed.  It typically has the
     definition:
          %{funsigned-char:-D__CHAR_UNSIGNED__}

`%1'
     Process the `cc1' spec.  This is used to construct the options to
     be passed to the actual C compiler (`cc1').

`%2'
     Process the `cc1plus' spec.  This is used to construct the options
     to be passed to the actual C++ compiler (`cc1plus').

`%*'
     Substitute the variable part of a matched option.  See below.
     Note that each comma in the substituted string is replaced by a
     single space.

`%{`S'}'
     Substitutes the `-S' switch, if that switch was given to GCC.  If
     that switch was 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 `%{foo}' would match the command-line option `-foo'
     and would output the command line option `-foo'.

`%W{`S'}'
     Like %{`S'} but mark last argument supplied within as a file to be
     deleted on failure.

`%{`S'*}'
     Substitutes all the switches specified to GCC whose names start
     with `-S', but which also take an argument.  This is used for
     switches like `-o, -D, -I', etc.  GCC considers `-o foo' as being
     one switch whose names starts with `o'.  %{o*} would substitute
     this text, including the space.  Thus two arguments would be
     generated.

`%{^`S'*}'
     Like %{`S'*}, but don't put a blank between a switch and its
     argument.  Thus %{^o*} would only generate one argument, not two.

`%{<`S'}'
     Remove all occurrences of `S' from the command line.  Note - this
     command is position dependent.  `%' commands in the spec string
     before this option will see `S', `%' commands in the spec string
     after this option will not.

`%{`S'*:`X'}'
     Substitutes `X' if one or more switches whose names start with
     `-S' are specified to GCC.  Note that the tail part of the `-S'
     option (i.e. the part matched by the `*') will be substituted for
     each occurrence of `%*' within `X'.

`%{`S':`X'}'
     Substitutes `X', but only if the `-S' switch was given to GCC.

`%{!`S':`X'}'
     Substitutes `X', but only if the `-S' switch was *not* given to
     GCC.

`%{|`S':`X'}'
     Like %{`S':`X'}, but if no `S' switch, substitute `-'.

`%{|!`S':`X'}'
     Like %{!`S':`X'}, but if there is an `S' switch, substitute `-'.

`%{.`S':`X'}'
     Substitutes `X', but only if processing a file with suffix `S'.

`%{!.`S':`X'}'
     Substitutes `X', but only if *not* processing a file with suffix
     `S'.

`%{`S'|`P':`X'}'
     Substitutes `X' if either `-S' or `-P' was given to GCC.  This may
     be combined with `!' and `.' sequences as well, although they have
     a stronger binding than the `|'.  For example a spec string like
     this:

          %{.c:-foo} %{!.c:-bar} %{.c|d:-baz} %{!.c|d:-boggle}

     will output the following command-line options from the following
     input command-line options:

          fred.c        -foo -baz
          jim.d         -bar -boggle
          -d fred.c     -foo -baz -boggle
          -d jim.d      -bar -baz -boggle

   The conditional text `X' in a %{`S':`X'} or %{!`S':`X'} construct
may contain other nested `%' constructs or spaces, or even newlines.
They are processed as usual, as described above.

   The `-O, -f, -m, and -W' switches are handled specifically in these
constructs.  If another value of `-O' or the negated form of a `-f, -m,
or -W' switch is found later in the command line, the earlier switch
value is ignored, except with {`S'*} where `S' is just one letter,
which passes all matching options.

   The character `|' at the beginning of the predicate text is used to
indicate that a command should be piped to the following command, but
only if `-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 `-l' are to be
treated as compiler output files, and passed to the linker in their
proper position among the other output files.