On Tue, 17 Feb 2026 at 22:41 +0000, Jonathan Wakely wrote:
On Sun, 10 Aug 2025 at 14:33 +0000, Prathamesh Kulkarni wrote:
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 33ae98c40af..de101e75028 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -724,7 +724,7 @@ Objective-C and Objective-C++ Dialects}.
@item Linker Options
@xref{Link Options,,Options for Linking}.
-@gccoptlist{@var{object-file-name} -fuse-ld=@var{linker} -l@var{library}
+@gccoptlist{@var{object-file-name} -flink-libatomic -fuse-ld=@var{linker}
-l@var{library}
-nostartfiles -nodefaultlibs -nolibc -nostdlib -nostdlib++
-e @var{entry} --entry=@var{entry}
-pie -pthread -r -rdynamic
@@ -19329,6 +19329,12 @@ If any of these options is used, then the linker is
not run, and
object file names should not be used as arguments. @xref{Overall
Options}.
+@opindex flink-libatomic
+@item -flink-libatomic
+Enable linking of libatomic if it's supported by target, and is enabled by
+default. The negative form @option{-fno-link-libatomic} can be used to
+explicitly disable linking of libatomic.
I'm confused by what the docs for -flink-libatomic mean.
As written, it seems to say that the option enables linking of
libatomic if the condition "it's supported by target and is enabled by
default" is true.
I don't think that's what it is trying to say. Whether it enables
linking to libatomic is not conditional on whether it's enabled by
default!
Should it be something like:
@opindex flink-libatomic
@item -flink-libatomic
Enable linking to libatomic.
This is enabled by default if the target supports libatomic.
The negative form @option{-fno-link-libatomic} can be used to
explicitly disable linking of libatomic.
Although I still find that unclear. What does "enable linking to
libatomic" mean exactly? Does enabling it mean that I can link to
libatomic by using -latomic and when it's disabled, I can't? (No!)
It's not really enabling something, it's *doing* it. When this option
is used (which is the default behaviour), the driver will
automatically link to libatomic. Can we document that it *does*
something, not that it enables something?
Look at the docs for -pthread:
-pthread
Link with the POSIX threads library.
This doesn't say "Enable linking with the POSIX threads library", it
just says it does it. This is entirely unambiguous.
Do we also want to index the negative form, i.e.
@opindex fno-link-libatomic
Or should the docs actually be for the negative form, and mention that
it overrides the default? That's how we sometimes (usually?) document
flags which are enabled by default.
Finally, how does this interact with -nodefaultlibs and -nostdlib?
Would the following be more accurate and more descriptive?
@opindex fno-link-libatomic
@opindex flink-libatomic
@item -flink-libatomic
Link with libatomic. Enabled by default.
The compiler will add options to link to libatomic when it is
supported by the target, so that the atomic operations defined by
the C and C++ standards work without requiring explicit action from
users. Typically this adds @option{-latomic} to the link command
line; for the GNU linker @option{--as-needed} is also used.
The negative form @option{-fno-link-libatomic} can be used to
explicitly disable linking of libatomic. The options
@option{-nodefaultlibs} and @option{-nostdlib} will also disable
linking to libatomic.
I suppose my use of "disabling" still has exactly the problem I
complained about above. Using -fno-link-libatomic doesn't disable
linking to libatomic, nor does -nodefaultlibs. When those options are
used, users can still add -latomic themselves and that will work, so
it hasn't been *disabled*. What the -fno-link-libatomic option does is
disable the *automatic* linking to libatomic, or the *implicit*
linking to libatomic.
So I think this could still do with some more wordsmithing.
