ld: Improve documentation of -rpath-link search paths
Checks
Context |
Check |
Description |
linaro-tcwg-bot/tcwg_binutils_build--master-arm |
success
|
Testing passed
|
linaro-tcwg-bot/tcwg_binutils_build--master-aarch64 |
success
|
Testing passed
|
linaro-tcwg-bot/tcwg_binutils_check--master-arm |
success
|
Testing passed
|
linaro-tcwg-bot/tcwg_binutils_check--master-aarch64 |
success
|
Testing passed
|
Commit Message
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(-)
Comments
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
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!
@@ -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