From: Nick Clifton <nickc@redhat.com>
Date: Tue, 13 Apr 2021 13:37:06 +0000 (+0100)
Subject: Document the effect of --as-needed on --rpath on Linux based systems.
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=6418520e7f0c32f940ac974a84c7dae3aa826266;p=binutils-gdb.git

Document the effect of --as-needed on --rpath on Linux based systems.

	* ld.texi (Options): Add note about the effect of --as-needed on
	the --rpath and --rpath-link options on Linux based systems.
---

diff --git a/ld/ChangeLog b/ld/ChangeLog
index e7620ce0417..663c06cf52a 100644
--- a/ld/ChangeLog
+++ b/ld/ChangeLog
@@ -1,3 +1,8 @@
+2021-04-13  Nick Clifton  <nickc@redhat.com>
+
+	* ld.texi (Options): Add note about the effect of --as-needed on
+	the --rpath and --rpath-link options on Linux based systems.
+
 2021-04-13  Alan Modra  <amodra@gmail.com>
 
 	PR 27722
diff --git a/ld/ld.texi b/ld/ld.texi
index 6d016ecc347..fe653daacd7 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -1560,6 +1560,11 @@ the library in question do not affect whether the library is seen as
 needed.  This is similar to the rules for extraction of object files
 from archives.  @option{--no-as-needed} restores the default behaviour.
 
+Note: On Linux based systems the @option{--as-needed} option also has
+an affect on the behaviour of the @option{--rpath} and
+@option{--rpath-link} options.  See the description of
+@option{--rpath-link} for more details.
+
 @kindex --add-needed
 @kindex --no-add-needed
 @item --add-needed
@@ -2323,8 +2328,19 @@ Any directories specifed by a @code{SEARCH_DIR} command in the
 linker script being used.
 @end enumerate
 
+Note however on Linux based systems there is an additional caveat:  If
+the @option{--as-needed} option is active @emph{and} a shared library
+is located which would normally satisfy the search @emph{and} this
+library does not have DT_NEEDED tag for @file{libc.so}
+@emph{and} there is a shared library later on in the set of search
+directories which also satisfies the search @emph{and}
+this second shared library does have a DT_NEEDED tag for
+@file{libc.so} @emph{then} the second library will be selected instead
+of the first.
+
 If the required shared library is not found, the linker will issue a
 warning and continue with the link.
+
 @end ifset
 
 @kindex -shared