Bug#1095039: debian-policy: Development files: Allow using linker scripts instead of symlinks

Hi!

On Sat, 2026-02-07 at 17:02:20 -0800, Russ Allbery wrote:
> Here is a proposed change incorporating this change and Guillem's
> feedback. Does this look good to everyone? (I moved one footnote because
> we now try to keep footnotes immediately after the paragraph they refer to
> and the added footnote would otherwise be out of order.)

Great, thanks!

> >From 19414e709a7dd38f35e621474c94a0931c2f6835 Mon Sep 17 00:00:00 2001
> From: Russ Allbery <[email protected]>
> Date: Sat, 7 Feb 2026 16:58:35 -0800
> Subject: [PATCH] Allow *.so files to be linker scripts
> 
> In some cases, *.so files installed by binary development packages
> for libraries are linker scripts instead of symlinks. Document that,
> and document the constraints imposed by ldconfig on linker scripts.
> Based on wording from Aurelien Jarno and feedback from Guillem Jover.
> 
> Closes: #1095039
> ---
>  policy/ch-sharedlibs.rst | 32 +++++++++++++++++++++-----------
>  1 file changed, 21 insertions(+), 11 deletions(-)
> 
> diff --git a/policy/ch-sharedlibs.rst b/policy/ch-sharedlibs.rst
> index 69b79d3..cdd2e37 100644
> --- a/policy/ch-sharedlibs.rst
> +++ b/policy/ch-sharedlibs.rst
> @@ -247,29 +247,39 @@ at a time, librarynameapiversion-dev. Installing the development package
>  must result in installation of all the development files necessary for
>  compiling programs against that shared library.  [#]_
>  
> +.. [#] This wording allows the development files to be split into several
> +       packages, such as a separate architecture-independent
> +       libraryname-headers, provided that the development package depends
> +       on all the required additional packages.
> +
>  In case several development versions of a library exist, you may need to
>  use ``dpkg``'s Conflicts mechanism (see :ref:`s-conflicts`) to ensure that
>  the user only installs one development version at a time (as different
>  development versions are likely to have the same header files in them,
>  which would cause a filename clash if both were unpacked).
>  
> -The development package should contain a symlink for the associated
> -shared library without a version number. For example, the libgdbm-dev
> -package should include a symlink from ``/usr/lib/libgdbm.so`` to
> -``libgdbm.so.3.0.0``. This symlink is needed by the linker (``ld``) when
> -compiling packages, as it will only look for ``libgdbm.so`` when
> -compiling dynamically.
> +The development package should contain either a symlink or a linker script
> +[#]_ for the associated shared library without a version number. For
> +example, the ``libgdbm-dev`` package should include a symlink from
> +:file:`/usr/lib/libgdbm.so` to :file:`libgdbm.so.3.0.0`, or a linker
> +script that achieves the same effect. This symlink or linker script is
> +needed by the linker (:command:`ld`) when compiling packages, as it will
> +only look for :file:`libgdbm.so` when compiling dynamically.
> +
> +.. [#] Linker scripts are used when more flexible linking strategies are
> +       desired, such as conditionally linking with an additional library
> +       or falling back to a static library for some symbols.
> +
> +If the package installs a linker script, be aware that :command:`ldconfig`
> +requires the linker script be shorter than 32 bytes, or contain either the

(As a non-native speaker, I'm not sure whether "script be shorter" is
missing a "to" in front of the "be"?)

> +``GROUP`` directive or the string ``GNU ld script`` in a comment in the
> +first 512 bytes.
>  
>  If the package provides Ada Library Information (``*.ali``) files for use
>  with GNAT, these files must be installed read-only (mode 0444) so that
>  GNAT will not attempt to recompile them. This overrides the normal file
>  mode requirements given in :ref:`s-permissions-owners`.
>  
> -.. [#] This wording allows the development files to be split into several
> -       packages, such as a separate architecture-independent
> -       libraryname-headers, provided that the development package depends
> -       on all the required additional packages.
> -
>  .. _s-sharedlibs-intradeps:
>  
>  Dependencies between the packages of the same library

Seconded, with or without the s/desired/required/ change suggested
elsethread and the perhaps missing "to".

Thanks,
Guillem