Patch to add documentation for spec files
Nick Clifton
nickc@cygnus.com
Wed Jul 7 06:43:00 GMT 1999
Hi Guys,
Below is a patch that adds a description of spec files to
invoke.texi. It is based on the comments found in gcc.c together
with some examples taken from real spec files. It is not 100%
complete, but I think it is a step in the right direction.
Does anyone have any comments ?
May I check this patch in ?
Cheers
Nick
Wed Jul 7 14:38:19 1999 Nick Clifton <nickc@cygnus.com>
* invoke.texi (Spec Files): New node: Describe the contents of
spec files.
Index: invoke.texi
===================================================================
RCS file: /egcs/carton/cvsfiles/egcs/gcc/invoke.texi,v
retrieving revision 1.118
diff -p -r1.118 invoke.texi
*** invoke.texi 1999/07/05 08:44:30 1.118
--- invoke.texi 1999/07/07 13:41:06
*************** only one of these two forms, whichever o
*** 68,73 ****
--- 68,74 ----
* Link Options:: Specifying libraries and so on.
* Directory Options:: Where to find header files and libraries.
Where to find the compiler executable files.
+ * Spec Files:: How to pass switches to sub-processes.
* Target Options:: Running a cross-compiler, or an old version of GNU CC.
* Submodel Options:: Specifying minor hardware or convention variations,
such as 68010 vs 68020.
*************** in the following sections.
*** 447,452 ****
--- 448,454 ----
* Link Options:: Specifying libraries and so on.
* Directory Options:: Where to find header files and libraries.
Where to find the compiler executable files.
+ * Spec Files:: How to pass switches to sub-processes.
* Target Options:: Running a cross-compiler, or an old version of GNU CC.
@end menu
*************** program uses when determining what switc
*** 2988,2993 ****
--- 2990,3390 ----
@samp{-specs=}@var{file} can be specified on the command line, and they
are processed in order, from left to right.
@end table
+
+ @node Spec Files
+ @section Specifying subprocesses and the switches to pass to them
+ @cindex Spec Files
+ @code{GCC} is a driver program. It performs its job by invoking a
+ sequence of other programs to do its work for it. GCC interprets
+ its command line parameters and uses these to deduce which programs it
+ should invoke, and which command line parameters it ought to pass to
+ them. This behaviour is controlled by @code{spec} strings, one (or
+ more) string for each program that GCC can invoke. GCC
+ has a complete set of @code{spec} strings built in to it, but these can
+ be overridden by the @samp{-specs=} command line switch.
+
+ @code{Spec Files} are text based. They consist of a sequence of
+ directives seperated 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:
+
+ @table @code
+ @item %[command]
+ Issues a [command] to the spec file processor. The commands that can
+ appear here are as follows:
+
+ @table @code
+ @item %include <@samp{file}>
+ @cindex %include
+ Search for @samp{file} and insert its text at the current point in the
+ specs file.
+
+ @item %include_noerr <@samp{file}>
+ @cindex %include_noerr
+ Just like %include, but do not generate an error message if the include
+ file cannot be found.
+
+ @item %rename @samp{old_name} @samp{new_name}
+ @cindex %rename
+ Rename the spec string @samp{old_name} to @samp{new_name}.
+
+ @end table
+
+ @item *[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. If the text
+ starts with a + character, then the text will be added to the end of the
+ current text for the spec, otherwise it will override the current text.
+ If the named spec does not exist, then a new spec will be created.
+
+ @item [suffix]:
+ Creates a new @samp{[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:
+
+ @smallexample
+ .ZZ:
+ z-compile -input %i
+ @end smallexample
+
+ Says that any input file whoes name ends in @samp{.ZZ} should be
+ passed to the program @samp{z-compile}, which should be invoked with the
+ command line switch @samp{-input} and with the result of performing the
+ @samp{%i} subsitution. (See below).
+
+ As an alternative to providing a spec string, the text that follows a
+ suffix directive can be one of the following:
+
+ @table @code
+ @item @@[language]
+ This says that the suffix is an alias for a known [language]. This is
+ similar to using the @code{-x} command line switch to GCC to specicy a
+ langauge explicitly. For example:
+
+ @smallexample
+ .ZZ:
+ @@c++
+ @end smallexample
+
+ Says that .ZZ files are infact c++ source files.
+
+ @item #[name]
+ This causes an error messages saying:
+
+ @smallexample
+ [name] compiler not installed on this system.
+ @end smallexample
+ @end table
+
+ 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.
+ @end table
+
+ 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 defintion.
+
+ GCC has the following spec strings built into it. Spec Files can
+ override these strings to 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 pre-processor
+ 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 of 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 pre-processor
+ 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
+ @end smallexample
+
+ @code{Spec} strings are a list of command line switches 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 % into the program name or argument.
+
+ @item %i
+ Substitute the name of the input file being processed.
+
+ @item %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.
+
+ @item %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 @samp{%g}, this contributes no text to the
+ argument.
+
+ @item %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 pre-processed. 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.
+
+ @item %uSUFFIX
+ Like @samp{%g}, but generates a new temporary file name even if %uSUFFIX
+ was already seen.
+
+ @item %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.
+
+ @item %w
+ Marks the argument containing or following the %w as the
+ "output file" of this compilation. This puts the argument
+ into the sequence of arguments that %o will substitute later.
+
+ @item %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.
+
+ @item %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'.
+
+ @item %p
+ Substitutes the standard macro predefinitions for the
+ current target machine. Use this when running cpp.
+
+ @item %P
+ Like @samp{%p}, but puts @samp{__} before and after the name of each macro.
+ (Except macros that already have __.)
+ This is for ANSI C.
+
+ @item %I
+ Substitute a -iprefix option made from GCC_EXEC_PREFIX.
+
+ @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.
+
+ @item %eSTR
+ Print STR as an error message. STR is terminated by a newline.
+ Use this when inconsistent options are detected.
+
+ @item %|
+ Output "-" if the input for the current command is coming from a pipe.
+
+ @item %(@samp{name})
+ Subsitute the contents of spec string @samp{name} at this point.
+
+ @item %[name]
+ Like @samp{%(...)} but put __ around -D arguments.
+
+ @item %x@{OPTION@}
+ Accumulate an option for %X.
+
+ @item %X
+ Output the accumulated linker options specified by @samp{-Wl} or a %x
+ spec string.
+
+ @item %Y
+ Output the accumulated assembler options specified by @samp{-Wa}.
+
+ @item %Z
+ Output the accumulated preprocessor options specified by @samp{-Wp}.
+
+ @item %v1
+ Substitute the major version number of GCC.
+ (For version 2.9.n, this is 2.)
+
+ @item %v2
+ Substitute the minor version number of GCC.
+ (For version 2.9.n, this is 9.)
+
+ @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 %D
+ Dump out a -L option for each directory in startfile_prefixes.
+ If multilib_dir is set, extra entries are generated with it affixed.
+
+ @item %l
+ Process the @code{link} spec. This is the spec for computing the
+ command line passed to the linker. Typically it will make use of the following
+ items:
+
+ @item %L
+ Process the @code{lib} spec. This is a spec string for deciding which
+ libraries shuld be 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 shuld be included on the command line to the linker.
+
+ @item %S
+ Process the @code{startfile} spec. This is a spec for deciding which
+ object files should be the first ones passed to the linker. Typically
+ this would be a file called @samp{crt0.o}.
+
+ @item %E
+ Process the @code{endfile} spec. This is a spec string that specifies
+ the last object files that will be passed to the linker.
+
+ @item %C
+ Process the @code{cpp} spec. This is used to construct the arguments
+ to be passed to the C pre-processor.
+
+ @item %c
+ Process the @code{signed_char} spec. This is intended to be used
+ to tell cpp whether a char is signed or not. It typically has the
+ definition:
+ @smallexample
+ %@{funsigned-char:-D__CHAR_UNSIGNED__@}
+ @end smallexample
+
+ @item %1
+ Process the @code{cc1} spec. This is used to construct the options to be
+ passed to the actual C compiler (@samp{cc1}).
+
+ @item %2
+ Process the @code{cc1plus} spec. This is used to construct the options to be
+ passed to the actual C++ compiler (@samp{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 %@{@samp{S}@}
+ Substitutes the -@samp{S} switch, if that switch was given to GCC.
+ If that switch was not specified, this substitutes nothing. Here
+ @samp{S} is a metasyntactic variable.
+
+ @item %W@{@samp{S}@}
+ Like %@{@samp{S}@} but mark last argument supplied within as a file to be
+ deleted on failure.
+
+ @item %@{@samp{S}*@}
+ Substitutes all the switches specified to GCC whose names start
+ with -@samp{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.
+
+ @item %@{^@samp{S}*@}
+ Like %@{@samp{S}*@}, but don't put a blank between a switch and its
+ argument. Thus %@{^o*@} would only generate one argument, not two.
+
+ @item %@{@samp{S}*:@samp{X}@}
+ Substitutes @samp{X} if one or more switches whose names start with
+ -@samp{S} are specified to GCC. Note that the tail part of the
+ -@samp{S} option (i.e. the part matched by the `*') will be substituted
+ for each occurrence of @samp{%*} within @samp{X}.
+
+ @item %@{@samp{S}:@samp{X}@}
+ Substitutes @samp{X}, but only if the @samp{-S} switch was given to GCC.
+
+ @item %@{!@samp{S}:@samp{X}@}
+ Substitutes @samp{X}, but only if the @samp{-S} switch was @emph{not} given to GCC.
+
+ @item %@{|@samp{S}:@samp{X}@}
+ Like %@{@samp{S}:@samp{X}@}, but if no @samp{S} switch, substitute `-'.
+
+ @item %@{|!@samp{S}:@samp{X}@}
+ Like %@{!@samp{S}:@samp{X}@}, but if there is an @samp{S} switch, substitute `-'.
+
+ @item %@{.@samp{S}:@samp{X}@}
+ Substitutes @samp{X}, but only if processing a file with suffix @samp{S}.
+
+ @item %@{!.@samp{S}:@samp{X}@}
+ Substitutes @samp{X}, but only if @emph{not} processing a file with suffix @samp{S}.
+
+ @item %@{@samp{S}|P:@samp{X}@}
+ Substitutes @samp{X} if either -@samp{S} or -P was given to GCC. This may be
+ combined with ! and . as above binding stronger than the OR.
+
+ @end table
+
+ The conditional text @samp{X} in a %@{@samp{S}:@samp{X}@} or
+ %@{!@samp{S}:@samp{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 @{@samp{S}*@} where @samp{S} is just one
+ letter; this 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.
+
+ Note that 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.
@node Target Options
@section Specifying Target Machine and Compiler Version
More information about the Gcc-patches
mailing list