[PATCH] ld/doc: Document interaction between unresolved-symbols

[Jan Beulich]

On 01.07.2025 18:30, Dimitri John Ledkov wrote:
> The --unresolved-symbols option is confusing, as setting it to the
> default value report-all, can actually change behaviour and cause link
> failures. This is because the implicit (unset) value of
> unresolved-symbols can set both objects and shared libraries to either
> the value of ignore-all or report-all, when -shared or -static options
> are used. Inversally, setting `--unresolved-symbols` to any value
> negates the implicit default of `-shared` or `-static`. Fun fact,
> util-linux fails to link, when using autoconf build system as libpam
> is not linked but is needed - and setting unresolved-symbols to the
> default value of report-all breaks the build.
> 
> Reading documentation and using the options was not obvious as to what
> effects it may have. Hence this patch tries to expand documentation to
> call out the potentially unexpected interactions between `-shared`,
> `-static` and `--unresolved-symbols`.
> 
> Signed-off-by: Dimitri John Ledkov <dimitri.ledkov@surgut.co.uk>
> ---
>  ld/ld.texi | 13 ++++++++-----
>  1 file changed, 8 insertions(+), 5 deletions(-)
> 
> diff --git a/ld/ld.texi b/ld/ld.texi
> index afcc3fea94f..bf87a9b2911 100644
> --- a/ld/ld.texi
> +++ b/ld/ld.texi
> @@ -2662,7 +2662,9 @@ about any other sections, or memory regions, or anything else.
>  Create a shared library.  This is currently only supported on ELF, XCOFF
>  and SunOS platforms.  On SunOS, the linker will automatically create a
>  shared library if the @option{-e} option is not used and there are
> -undefined symbols in the link.
> +undefined symbols in the link. This option also implies
> +@option{--unresolved-symbols=ignore=all}, unless a different value was
> +specified.

Aiui you mean ignore-all here?

Also there are further options controlling the two fields. I'm not sure how
useful it is to mention just one of the available ones here.

> @@ -2866,15 +2868,16 @@ model, it will set the address of the first byte of the ldata segment.
>  
>  @kindex --unresolved-symbols
>  @item --unresolved-symbols=@var{method}
> -Determine how to handle unresolved symbols.  There are four possible
> -values for @samp{method}:
> +Determine how to handle unresolved symbols.  This option also disables
> +implied default behaviour of @option{-static} and @option{-shared}.
> +There are four possible values for @samp{method}:
>  
>  @table @samp
>  @item ignore-all
> -Do not report any unresolved symbols.
> +Do not report any unresolved symbols. This is the implied default, if @option{-shared} is used.
>  
>  @item report-all
> -Report all unresolved symbols.  This is the default.
> +Report all unresolved symbols.  This is the implied default, unless @option{-shared} is used.

Please limit line length to 80 chars.

Jan