From a019766f996f57e53a8d1a9e72033e1e1487a150 Mon Sep 17 00:00:00 2001
From: Armin Brauns via Gcc-patches <gcc-patches@gcc.gnu.org>
Date: Mon, 16 Nov 2020 17:14:31 -0700
Subject: [PATCH] Update documentation for spec files

gcc
	* gcc.c: Document %T spec file directive.
	* doc/invoke.texi: Remove %p, %P spec file directives.
	Add %M, %R, %V, %nSTR, %>S, %<S*, %{%:function(args):X}, %@{...} spec
	file directives add sanitize, version-compare, include, gt and
	debug-level-gt spec functions.
---
 gcc/doc/invoke.texi | 115 ++++++++++++++++++++++++++++++++++++++++----
 gcc/gcc.c           |   6 +++
 2 files changed, 111 insertions(+), 10 deletions(-)

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index e84a3cf422e..3510a54c6c4 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -31727,6 +31727,9 @@ 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} substitutes.
 
+@item %V
+Indicates that this compilation produces no output file.
+
 @item %o
 Substitutes the names of all the output files, with spaces
 automatically placed around them.  You should write spaces
@@ -31745,16 +31748,6 @@ been substituted, except that @samp{%g, %u, and %U} do not currently
 support additional @var{suffix} characters following @samp{%O} as they do
 following, for example, @samp{.o}.
 
-@item %p
-Substitutes the standard macro predefinitions for the
-current target machine.  Use this when running @command{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 ISO
-C@.
-
 @item %I
 Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
 @option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
@@ -31779,6 +31772,9 @@ searched.
 Print @var{str} as an error message.  @var{str} is terminated by a newline.
 Use this when inconsistent options are detected.
 
+@item %n@var{str}
+Print @var{str} as a notice.  @var{str} is terminated by a newline.
+
 @item %(@var{name})
 Substitute the contents of spec string @var{name} at this point.
 
@@ -31795,6 +31791,12 @@ Output the accumulated assembler options specified by @option{-Wa}.
 @item %Z
 Output the accumulated preprocessor options specified by @option{-Wp}.
 
+@item %M
+Output @code{multilib_os_dir}.
+
+@item %R
+Output the concatenation of @code{target_system_root} and @code{target_sysroot_suffix}.
+
 @item %a
 Process the @code{asm} spec.  This is used to compute the
 switches to be passed to the assembler.
@@ -31854,6 +31856,12 @@ command is position dependent.  @samp{%} commands in the spec string
 before this one see @code{-S}, @samp{%} commands in the spec string
 after this one do not.
 
+@item %<S*
+Similar to @samp{%<S}, but match all switches beginning with @code{-S}.
+
+@item %>S
+Similar to @samp{%<S}, but keep @code{-S} in the GCC command line.
+
 @item %:@var{function}(@var{args})
 Call the named function @var{function}, passing it @var{args}.
 @var{args} is first processed as a nested spec string, then split
@@ -31914,6 +31922,14 @@ usage:
 -l%:if-exists-then-else(%:getenv(VSB_DIR rtnet.h) rtnet net)
 @end smallexample
 
+@item @code{sanitize}
+The @code{sanitize} spec function takes no arguments.  It returns non-NULL if
+any address, thread or undefined behaviour sanitizers are active.
+
+@smallexample
+%@{%:sanitize(address):-funwind-tables@}
+@end smallexample
+
 @item @code{replace-outfile}
 The @code{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
@@ -31932,6 +31948,56 @@ its usage:
 %:remove-outfile(-lm)
 @end smallexample
 
+@item @code{version-compare}
+The @code{version-compare} spec function takes four or five arguments of the following
+form:
+
+@smallexample
+<comparison-op> <arg1> [<arg2>] <switch> <result>
+@end smallexample
+
+It returns @code{result} if the comparison evaluates to true, and NULL if it doesn't.
+The supported @code{comparison-op} values are:
+
+@table @code
+@item >=
+True if @code{switch} is a later (or same) version than @code{arg1}
+
+@item !>
+Opposite of @code{>=}
+
+@item <
+True if @code{switch} is an earlier version than @code{arg1}
+
+@item !<
+Opposite of @code{<}
+
+@item ><
+True if @code{switch} is @code{arg1} or later, and earlier than @code{arg2}
+
+@item <>
+True if @code{switch} is earlier than @code{arg1}, or is @code{arg2} or later
+@end table
+
+If the @code{switch} is not present at all, the condition is false unless the first character
+of the @code{comparison-op} is @code{!}.
+
+@smallexample
+%:version-compare(>= 10.3 mmacosx-version-min= -lmx)
+@end smallexample
+
+The above example would add @option{-lmx} if @option{-mmacosx-version-min=10.3.9} was
+passed.
+
+@item @code{include}
+The @code{include} spec function behaves much like @code{%include}, with the advantage
+that it can be nested inside a spec and thus be conditionalized.  It takes one argument,
+the filename, and looks for it in the startfile path.  It always returns NULL.
+
+@smallexample
+%@{static-libasan|static:%:include(libsanitizer.spec)%(link_libasan)@}
+@end smallexample
+
 @item @code{pass-through-libs}
 The @code{pass-through-libs} spec function takes any number of arguments.  It
 finds any @option{-l} options and any non-options ending in @file{.a} (which it
@@ -31957,6 +32023,25 @@ Use "-Wa,OPTION" to pass "OPTION" to the assembler.
 
 It is used to separate compiler options from assembler options
 in the @option{--target-help} output.
+
+@item @code{gt}
+The @code{gt} spec function takes two or more arguments.  It returns @code{""} (the
+empty string) if the second-to-last argument is greater than the last argument, and NULL
+otherwise.  The following example inserts the @code{link_gomp} spec if the last
+@option{-ftree-parallelize-loops=} option given on the command line is greater than 1:
+
+@smallexample
+%@{%:gt(%@{ftree-parallelize-loops=*:%*@} 1):%:include(libgomp.spec)%(link_gomp)@}
+@end smallexample
+
+@item @code{debug-level-gt}
+The @code{debug-level-gt} spec function takes one argument and returns @code{""} (the
+empty string) if @code{debug_info_level} is greater than the specified number, and NULL
+otherwise.
+
+@smallexample
+%@{%:debug-level-gt(0):%@{gdwarf*:--gdwarf2@}@}
+@end smallexample
 @end table
 
 @item %@{S@}
@@ -31971,6 +32056,10 @@ and outputs the command-line option @option{-foo}.
 Like %@{@code{S}@} but mark last argument supplied within as a file to be
 deleted on failure.
 
+@item %@@@{S@}
+Like %@{@code{S}@} but puts the result into a @code{FILE} and substitutes
+@code{@@FILE} if an @code{@@file} argument has been supplied.
+
 @item %@{S*@}
 Substitutes all the switches specified to GCC whose names start
 with @code{-S}, but which also take an argument.  This is used for
@@ -32053,6 +32142,12 @@ jim.d         -bar -boggle
 -d jim.d      -bar -baz -boggle
 @end smallexample
 
+@item %@{%:@var{function}(@var{args}):X@}
+
+Call function named @var{function} with args @var{args}.  If the
+function returns non-NULL, then @code{X} is substituted, if it returns
+NULL, it isn't substituted.
+
 @item %@{S:X; T:Y; :D@}
 
 If @code{S} is given to GCC, substitutes @code{X}; else if @code{T} is
diff --git a/gcc/gcc.c b/gcc/gcc.c
index cdf4d4f2403..766bfc1f8a2 100644
--- a/gcc/gcc.c
+++ b/gcc/gcc.c
@@ -542,6 +542,12 @@ or with constant text in a single argument.
  %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.
+ %T	current argument is the name of a linker script.
+	Search for that file in the current list of directories to scan for
+	libraries.  If the file is located, insert a --script option into the
+	command line followed by the full path name found.  If the file is
+	not found then generate an error message.
+	Note: the current working directory is not searched.
  %eSTR  Print STR as an error message.  STR is terminated by a newline.
         Use this when inconsistent options are detected.
  %nSTR  Print STR as a notice.  STR is terminated by a newline.
-- 
2.30.2