Add node describing spec files.

From-SVN: r28005

gcc/ChangeLog

+Thu Jul  8 16:50:14 1999  Nick Clifton  <nickc@cygnus.com>
+
+	* invoke.texi (Spec Files): New node: Describe the contents of
+	spec files.
+
 Thu Jul  8 10:28:25 1999  Craig Burley  <craig@jcb-sc.com>
 
 	* invoke.texi (DEC Alpha Options): Put @end table at

gcc/invoke.texi

@@ -68,6 +68,7 @@ only one of these two forms, whichever one is not the default.
 * 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.
@@ -447,6 +448,7 @@ in the following sections.
 * 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
 
@@ -2989,6 +2991,427 @@ program uses when determining what switches to pass to @file{cc1},
 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 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 @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 behaviour.  The spec strings built into GCC can
+be overridden by using the @samp{-specs=} command-line switch to specify
+a spec file.
+
+@dfn{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:
+
+@table @code
+@item %@var{command}
+Issues a @var{command} to the spec file processor.  The commands that can
+appear here are: 
+
+@table @code
+@item %include <@var{file}>
+@cindex %include
+Search for @var{file} and insert its text at the current point in the
+specs file.
+
+@item %include_noerr <@var{file}>
+@cindex %include_noerr
+Just like @samp{%include}, but do not generate an error message if the include
+file cannot be found.
+
+@item %rename @var{old_name} @var{new_name}
+@cindex %rename
+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 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 @samp{+}
+character, in which case the text will be 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 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
+
+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 @samp{-input} and with the result of performing the
+@samp{%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:
+
+@table @code
+@item @@@var{language}
+This says that the suffix is an alias for a known @var{language}.  This is
+similar to using the @code{-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 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
+
+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
+predefines   Defines to be passed to the C preprocessor
+signed_char  Defines to pass to CPP to say whether @code{char} is signed by default
+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 %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 @samp{%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 %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 ... %g.o ... %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 even if
+@samp{%u@var{suffix}} was already seen.
+
+@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 ... %U.s ... %g.s ... %U.s}
+would involve 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 %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} 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 @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 will
+be 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 would
+following, for example, @samp{.o}.
+
+@item %p
+Substitutes the standard macro predefinitions for the
+current target machine.  Use this when running @code{cpp}.
+
+@item %P
+Like @samp{%p}, but puts @samp{__} before and after the name of each
+predefined macro, except for macros that start with @samp{__} or with
+@samp{_@var{L}}, where @var{L} is an uppercase letter.  This is for ANSI
+C.  
+
+@item %I
+Substitute a @samp{-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 %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 %|
+Output @samp{-} if the input for the current command is coming from a pipe.
+
+@item %(@var{name})
+Substitute the contents of spec string @var{name} at this point.
+
+@item %[@var{name}]
+Like @samp{%(...)} but put @samp{__} around @samp{-D} arguments.
+
+@item %x@{@var{option}@}
+Accumulate an option for @samp{%X}.
+
+@item %X
+Output the accumulated linker options specified by @samp{-Wl} or a @samp{%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.5, this is 2.)
+
+@item %v2
+Substitute the minor version number of GCC.
+(For version 2.9.5, 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 %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
+@samp{%L %G %S %D and %E} sequences.
+
+@item %D
+Dump out a @samp{-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. 
+
+@item %L
+Process the @code{lib} spec.  This is a spec string for deciding which
+libraries should 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 should 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 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 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 preprocessor.
+
+@item %c
+Process the @code{signed_char} spec.  This is intended to be used
+to tell cpp whether a char is signed.  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 %@{@code{S}@}
+Substitutes the @code{-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 @samp{%@{foo@}} would match the command-line option @samp{-foo}
+and would output the command line option @samp{-foo}.
+
+@item %W@{@code{S}@}
+Like %@{@code{S}@} but mark last argument supplied within as a file to be
+deleted on failure. 
+
+@item %@{@code{S}*@}
+Substitutes all the switches specified to GCC whose names start
+with @code{-S}, but which also take an argument.  This is used for
+switches like @samp{-o, -D, -I}, etc.  GCC considers @samp{-o foo} as being
+one switch whose names starts with @samp{o}.  %@{o*@} would substitute this
+text, including the space.  Thus two arguments would be generated. 
+
+@item %@{^@code{S}*@}
+Like %@{@code{S}*@}, but don't put a blank between a switch and its
+argument.  Thus %@{^o*@} would only generate one argument, not two.
+
+@item %@{@code{S}*:@code{X}@}
+Substitutes @code{X} if one or more switches whose names start with
+@code{-S} are specified to GCC.  Note that the tail part of the
+@code{-S} option (i.e. the part matched by the @samp{*}) will be substituted
+for each occurrence of @samp{%*} within @code{X}. 
+
+@item %@{@code{S}:@code{X}@}
+Substitutes @code{X}, but only if the @samp{-S} switch was given to GCC.
+
+@item %@{!@code{S}:@code{X}@}
+Substitutes @code{X}, but only if the @samp{-S} switch was @emph{not} given to GCC.
+
+@item %@{|@code{S}:@code{X}@}
+Like %@{@code{S}:@code{X}@}, but if no @code{S} switch, substitute @samp{-}.
+
+@item %@{|!@code{S}:@code{X}@}
+Like %@{!@code{S}:@code{X}@}, but if there is an @code{S} switch, substitute @samp{-}.
+
+@item %@{.@code{S}:@code{X}@}
+Substitutes @code{X}, but only if processing a file with suffix @code{S}.
+
+@item %@{!.@code{S}:@code{X}@}
+Substitutes @code{X}, but only if @emph{not} processing a file with suffix @code{S}.
+
+@item %@{@code{S}|@code{P}:@code{X}@}
+Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC.  This may be
+combined with @samp{!} and @samp{.} sequences as well, although they
+have a stronger binding than the @samp{|}.  For example a spec string
+like this:
+
+@smallexample
+%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
+@end smallexample
+
+will output 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
+
+@end table
+
+The conditional text @code{X} in a %@{@code{S}:@code{X}@} or
+%@{!@code{S}:@code{X}@} construct may contain other nested @samp{%} constructs
+or spaces, or even newlines.  They are processed as usual, as described
+above. 
+
+The @samp{-O, -f, -m, and -W} switches are handled specifically in these
+constructs.  If another value of @samp{-O} or the negated form of a @samp{-f, -m, or
+-W} switch is found later in the command line, the earlier switch
+value is ignored, except with @{@code{S}*@} where @code{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 @samp{-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 @samp{-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
 @cindex target options