Next: Target Options, Previous: Directory Options, Up: Invoking GCC
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 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 -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%include <
file>
%include_noerr <
file>
%rename
old_name new_name*[
spec_name]:
[
suffix]:
.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.ZZ: @c++
Says that .ZZ files are, in fact, C++ source files.
#
namename 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.
%%
%i
%b
%B
%d
%g
suffix%u
suffix%U
suffix%j
suffixHOST_BIT_BUCKET
, if any, and if it is
writable, and if save-temps is off; otherwise, substitute the name
of a temporary file, just like `%u'. This temporary file is not
meant for communication between processes, but rather as a junk
disposal mechanism.
%|
suffix%m
suffixX
}'
construct: see for example f/lang-specs.h.
%.
SUFFIX%w
%o
%O
%p
cpp
.
%P
%I
%s
%e
str%(
name)
%[
name]
%x{
option}
%X
%Y
%Z
%a
asm
spec. This is used to compute the
switches to be passed to the assembler.
%A
asm_final
spec. This is a spec string for
passing switches to an assembler post-processor, if such a program is
needed.
%l
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
%L
lib
spec. This is a spec string for deciding which
libraries should be included on the command line to the linker.
%G
libgcc
spec. This is a spec string for deciding
which GCC support library should be included on the command line to the linker.
%S
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
endfile
spec. This is a spec string that specifies
the last object files that will be passed to the linker.
%C
cpp
spec. This is used to construct the arguments
to be passed to the C preprocessor.
%1
cc1
spec. This is used to construct the options to be
passed to the actual C compiler (`cc1').
%2
cc1plus
spec. This is used to construct the options to be
passed to the actual C++ compiler (`cc1plus').
%*
%<S
-S
from the command line. Note—this
command is position dependent. `%' commands in the spec string
before this one will see -S
, `%' commands in the spec string
after this one will not.
%:
function(
args)
The following built-in spec functions are provided:
if-exists
if-exists
spec function takes one argument, an absolute
pathname to a file. If the file exists, if-exists
returns the
pathname. Here is a small example of its usage:
*startfile: crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
if-exists-else
if-exists-else
spec function is similar to the if-exists
spec function, except that it takes two arguments. The first argument is
an absolute pathname to a file. If the file exists, if-exists-else
returns the pathname. If it does not exist, it returns the second argument.
This way, 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:
*startfile: crt0%O%s %:if-exists(crti%O%s) \ %:if-exists-else(crtbeginT%O%s crtbegin%O%s)
replace-outfile
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:
%{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)}
%{S}
-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}
S
} but mark last argument supplied within as a file to be
deleted on failure.
%{S*}
-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*&T*}
S
*}, but preserve order of S
and T
options
(the order of S
and 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 `%{D*&U*&A*}'.
%{S:X}
X
, if the `-S' switch was given to GCC.
%{!S:X}
X
, if the `-S' switch was not given to GCC.
%{S*:X}
X
if one or more switches whose names start with
-S
are specified to GCC. Normally X
is substituted only
once, no matter how many such switches appeared. However, if %*
appears somewhere in X
, then X
will be substituted once
for each matching switch, with the %*
replaced by the part of
that switch that matched the *
.
%{.S:X}
X
, if processing a file with suffix S
.
%{!.S:X}
X
, if not processing a file with suffix S
.
%{S|P:X}
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 `|'. If %*
appears in X
, all of the alternatives must be starred, and only
the first matching alternative is substituted.
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
%{S:X; T:Y; :D}
S
was given to GCC, substitutes X
; else if T
was
given to GCC, substitutes Y
; else substitutes D
. There can
be as many clauses as you need. This may be combined with .
,
!
, |
, and *
as needed.
The conditional text X
in a %{S
:X
} or similar
construct may contain other nested `%' constructs or spaces, or
even newlines. They are processed as usual, as described above.
Trailing white space in X
is ignored. White space may also
appear anywhere on the left side of the colon in these constructs,
except between .
or *
and the corresponding word.
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.