[PATCH] doc: gcc.c: Update documentation for spec files
Armin Brauns
armin.brauns@gmail.com
Sun Sep 6 15:23:59 GMT 2020
There were some differences between the actual code in do_spec_1, its
source comment, and the documentation in doc/invoke.texi. These should
now be resolved.
gcc/ChangeLog:
* 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 5d29a7fa23c..b1d509b3c52 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -31219,6 +31219,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
@@ -31237,16 +31240,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}),
@@ -31271,6 +31264,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.
@@ -31287,6 +31283,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.
@@ -31346,6 +31348,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
@@ -31393,6 +31401,14 @@ crt0%O%s %:if-exists(crti%O%s) \
%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
@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
@@ -31411,6 +31427,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
@@ -31436,6 +31502,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@}
@@ -31450,6 +31535,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
@@ -31532,6 +31621,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 531f4e02dbd..72490847274 100644
--- a/gcc/gcc.c
+++ b/gcc/gcc.c
@@ -540,6 +540,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.28.0
More information about the Gcc-patches
mailing list