LD/doc: Clarify `-rpath' option's semantics WRT link-time dependencies

Message ID alpine.DEB.2.20.1906052131390.26643@tpp.hgst.com
State New
Headers show
Series
  • LD/doc: Clarify `-rpath' option's semantics WRT link-time dependencies
Related show

Commit Message

Maciej W. Rozycki June 5, 2019, 9:15 p.m.
From: Maciej W. Rozycki <macro@wdc.com>


Mention in the description of the `-rpath' LD option the restrictions 
the option has with respect to searching link-time dependencies of 
shared objects referred in the link.  Previously these restrictions were 
only documented along with the `-rpath-link' option, which may not be 
the place one would consider when looking for the semantics of `-rpath'.

Copy the relevant part of the `-rpath-link' option description then, 
splitting the now overlong paragraph into three, for legibility.

	ld/
	* ld.texi (Options): Also document `-rpath' option restrictions 
	in the description of the option itself.
---
Hi,

 It took me a better part of the day to figure out what was going on with 
`-rpath' being ignored for the purpose of searching link-time dependencies 
with a cross-linker that was configured with no sysroot defined.  As it 
eventually turned out from code inspection it is a feature I have never 
come across before, however documented with the `-rpath-link' option only, 
which is not necessarily the place one would look at for the semantics of 
`-rpath'.

 NB my WDC copyright assignment paperwork for FSF is still in progress, 
however I have not contributed to binutils on behalf of WDC yet and I 
believe the change is small enough to be acceptable right away.

 Verified with `make info pdf' and then visually.  OK to apply then?

  Maciej
---
 ld/ld.texi |   17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

binutils-ld-doc-rpath-cross.diff

Comments

Nick Clifton June 7, 2019, 4:02 p.m. | #1
Hi Maciej,

> 	ld/

> 	* ld.texi (Options): Also document `-rpath' option restrictions 

> 	in the description of the option itself.


Approved - please apply - and welcome back! :-)

Cheers
  Nick
Maciej W. Rozycki June 7, 2019, 6:28 p.m. | #2
Hi Nick,

> > 	ld/

> > 	* ld.texi (Options): Also document `-rpath' option restrictions 

> > 	in the description of the option itself.

> 

> Approved - please apply - and welcome back! :-)


 I'm glad to be onboard.  Applied now, thank you for your review.

  Maciej

Patch

Index: binutils-gdb/ld/ld.texi
===================================================================
--- binutils-gdb.orig/ld/ld.texi
+++ binutils-gdb/ld/ld.texi
@@ -1958,12 +1958,17 @@  line.  It overrides @samp{-s} and @samp{
 Add a directory to the runtime library search path.  This is used when
 linking an ELF executable with shared objects.  All @option{-rpath}
 arguments are concatenated and passed to the runtime linker, which uses
-them to locate shared objects at runtime.  The @option{-rpath} option is
-also used when locating shared objects which are needed by shared
-objects explicitly included in the link; see the description of the
-@option{-rpath-link} option.  If @option{-rpath} is not used when linking an
-ELF executable, the contents of the environment variable
-@code{LD_RUN_PATH} will be used if it is defined.
+them to locate shared objects at runtime.
+
+The @option{-rpath} option is also used when locating shared objects which
+are needed by shared objects explicitly included in the link; see the
+description of the @option{-rpath-link} option.  Searching @option{-rpath}
+in this way is only supported by native linkers and cross linkers which
+have been configured with the @option{--with-sysroot} option.
+
+If @option{-rpath} is not used when linking an ELF executable, the
+contents of the environment variable @code{LD_RUN_PATH} will be used if it
+is defined.
 
 The @option{-rpath} option may also be used on SunOS.  By default, on
 SunOS, the linker will form a runtime search path out of all the