[PATCH] ld: Improve documentation of -rpath-link search paths

[PATCH] ld: Improve documentation of -rpath-link search paths

[Jonathan Wakely]

This change tries to clarify that the list of search paths given under
the -rpath-link option are only used when looking for additional
libraries to satisfy DT_NEEDED dependencies, not for libraries named
with -l options. It seems to be a common misunderstanding that this list
implies that LD_LIBRARY_PATH can be used instead of naming directories
with -L options.
---
 ld/ld.texi | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/ld/ld.texi b/ld/ld.texi
index 6f234752278..57a7e2ae2ea 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -2427,7 +2427,8 @@ of the input files.
 When the linker encounters such a dependency when doing a non-shared,
 non-relocatable link, it will automatically try to locate the required
 shared library and include it in the link, if it is not included
-explicitly.  In such a case, the @option{-rpath-link} option
+explicitly.  In such a case, several directories are searched as
+described below.  The @option{-rpath-link} option
 specifies the first set of directories to search.  The
 @option{-rpath-link} option may specify a sequence of directory names
 either by specifying a list of names separated by colons, or by
@@ -2445,11 +2446,12 @@ supported.
 
 This option should be used with caution as it overrides the search path
 that may have been hard compiled into a shared library. In such a case it
-is possible to use unintentionally a different search path than the
-runtime linker would do.
+is possible to unintentionally use a different search path than the
+runtime linker would have used.
 
-The linker uses the following search paths to locate required shared
-libraries:
+When additional shared libraries are required, the linker uses the
+following search paths to locate them.  These paths are not used to find
+libraries that are included in the link explicitly using @option{-l}.
 
 @enumerate
 @item
-- 
2.44.0

Re: [PATCH] ld: Improve documentation of -rpath-link search paths

[Nick Clifton]

Hi Jonathan,

> This change tries to clarify that the list of search paths given under
> the -rpath-link option are only used when looking for additional
> libraries to satisfy DT_NEEDED dependencies, not for libraries named
> with -l options.

Thanks for this patch.  I have gone ahead and applied a variant of your
patch because there was one point which I thought might be slightly
confusing to the reader:

> -The linker uses the following search paths to locate required shared
> -libraries:
> +When additional shared libraries are required, the linker uses the
> +following search paths to locate them.  These paths are not used to find
> +libraries that are included in the link explicitly using @option{-l}.

The issue here is that the -L option is mentioned in the list that follows
for potential locations of shared libraries.  It is conditional upon running
under SunOS, but still, it could confuse readers.  So instead I went with:

      When additional shared libraries are required, the linker will
      search directories in the order listed below in order to find them.
      Note however that this only applies to additional libraries needed
      to satisfy already included shared libraries.  It does does _not_
      apply to libraries that are included via the '-l' command line
      option.  Searches for '-l' libraries are only conducted in
      directories specified by the '-L' option (*Note -L::).

I also added the cross reference just in case the reader is unfamiliar with
the -L option.

Cheers
   Nick

Re: [PATCH] ld: Improve documentation of -rpath-link search paths

[Jonathan Wakely]

On Mon, 18 Mar 2024 at 16:51, Nick Clifton <nickc@redhat.com> wrote:
>
> Hi Jonathan,
>
> > This change tries to clarify that the list of search paths given under
> > the -rpath-link option are only used when looking for additional
> > libraries to satisfy DT_NEEDED dependencies, not for libraries named
> > with -l options.
>
> Thanks for this patch.  I have gone ahead and applied a variant of your
> patch because there was one point which I thought might be slightly
> confusing to the reader:
>
> > -The linker uses the following search paths to locate required shared
> > -libraries:
> > +When additional shared libraries are required, the linker uses the
> > +following search paths to locate them.  These paths are not used to find
> > +libraries that are included in the link explicitly using @option{-l}.
>
> The issue here is that the -L option is mentioned in the list that follows
> for potential locations of shared libraries.  It is conditional upon running
> under SunOS, but still, it could confuse readers.  So instead I went with:
>
>       When additional shared libraries are required, the linker will
>       search directories in the order listed below in order to find them.
>       Note however that this only applies to additional libraries needed
>       to satisfy already included shared libraries.  It does does _not_

"does does"

>       apply to libraries that are included via the '-l' command line
>       option.  Searches for '-l' libraries are only conducted in
>       directories specified by the '-L' option (*Note -L::).
>
> I also added the cross reference just in case the reader is unfamiliar with
> the -L option.

Nice, thanks!