Section 8.1 starts with the following:

+---
| The run-time shared library must be placed in a package whose name
| changes whenever the SONAME of the shared library changes. This
| allows several versions of the shared library to be installed at the
| same time [...]
+---

This has two issues:

1. It is not needed to change package names for this. One can also use
"Provides: <something-that-changes-with-soname>" and have packages
depend on that.

2. It does not allow coinstallability without other constraints. There
are several common patterns like depending on a libfoo-bin or
libfoo-common package which then would also be required to work with
both versions. I think I've also seen libfooX-bin packages that were
not coinstallable as helper binaries were not installed into a path
that changes with soname.

There is also a footnote that states

+---
| There are some exceptional situations in which co-installation of
| two versions of a shared library is not safe, and the new shared
| library package has to conflict with the previous shared library
| package. This is never desirable, since it causes significant
| disruption during upgrades and potentially breaks unpackaged
| third-party binaries, but is sometimes unavoidable. These situations
| are sufficiently rare that they usually warrant project-wide
| discussion, and are complex enough that the rules for them cannot be
| codified in Debian Policy.
+---

which seems to contradict current practice as I don't remember a
single project-wide discussion about -common or -bin packages cuasing
this. It also doesn't seem warranted for libraries with few reverse
dependencies.

So I suggest:

1. Policy should document current practices and also allow other
methods that ensure dependencies are satisfied. Note that some
ecosystems like Perl do similar things with perlapi-X (where different
perlapi-X providers are in general not coinstallable).

2. Coinstallability should be mentioned as a concern for libraries
with many reverse dependencies, but should explictly state that this
requires the entire dependency chain to be coinstallable. Note that
"Depends: libfoo-common (>= X)" runs into the risk that newer
libfoo-common packages break older library versions and are safe only
when extraordinary care is taken; the same is true for
"libfoo-bin". (One could use libfooX-common, libfooX-bin packages
where data and helper binaries are installed into paths that change
with the SONAME such as /usr/lib/libfooX/libfoo-helper.)

3. The footnote about "exceptional situations" should be removed.

Ansgar

Policy need to ensure that users can safely build binaries using the libxxx-dev packages installed by Debian
and create programs dynamically linked with the shared library package they depend on, and still allow them
to upgrade their system from oldstable to stable without causing such shared library to be replaced by
libraries with incompatible soname and causing users compiled binaries to break.

This requires coinstability of libxxx.so.n and libxxx.so.m.
Provides does not permit this.

Cheers,
Bill.

Hi,

Then Policy would need to forbid *any* Breaks/Conflicts against libX
packages that are no longer shipped by Debian. We do not do that in
practice and I often see libX removed due to Breaks/Conflicts.

In fact, we even break ABI without changing soname, breaking self-
compilied binaries. See for example the C++ ABI transition: many
libraries changed ABI without changing SONAME. This was repeated with
the t64 transition, another large-scale ABI change without SONAME
change.

Provides is less breakage than current practice allows.

Ansgar

Yes.

Please report them as bugs. There are little reason to conflict against
such packages.  If libfoo-common is soname specific, it needs to be called
libfooN-common.

Cheers,

Hi,

We currently do *not* require perpetual coinstallability (or even
short-time coinstallability) of libraries with different SONAMEs, nor
do we currently require coinstallability of libraries with different
ABIs despite having the same SONAME.

So no, I won't report things that are non-bugs according to current
practice as bugs.

I also do not want to change current practice. If you want that, please
establish a consensus that we do want this change first. After that,
you could file bugs if you care about this problem.

(If we assume a ideal world, libraries would just not change their
SONAME ever nor would the kernel break ABI internally or with
userspace[1] either.)

Ansgar

  [1]: Yes, it does. Otherwise there would not be bugs titled "FTBFS on
newer kernels"

Ansgar <ansgar@debian.org> writes:

I don't understand this objection. The reason why the name of the package
needs to change is that for a normal upgrade transition that doesn't
require a lockstep upgrade, you have to be able to install version 1 and
version 2 (SONAMEs) of the library at the same time, and the only way that
is possible in Debian's packaging system is if either they are both
included in the same package (usually not a good idea since the different
versions come from different versions of the source package, and certainly
not the common approach) or if the package name is different.

Provides is of no help here whatsoever so far as I can see. What am I
missing?

If I understand correctly, the issue that you're raising is that in
practice this is more of a should than a must, and sometimes we do let the
shared libraries conflict and thus require each system do an
all-or-nothing upgrade of everything that depends on that shared library.

I agree that we do sometimes do this, but hopefully you also agree that
this is not desired and we *should* allow coinstallability? (Should, not
must.)

If I understand that correctly, I would be in favor of spelling that out
more explicitly if someone proposes good replacement wording.

However, just to be clear (since I wasn't completely sure what you were
proposing), embedding the SONAME of the library in the package version
*is* a must and has been for as long as I've been working on Debian, and
I'm opposed to relaxing that even if the versions of the library conflict
for some reason. That is a valuable convention that a lot of people
implicitly rely upon and we shouldn't weaken it even if it can't always
produce all the properties we desire.

Yes, that would be a good thing to state explicitly as well. I think the
constraint is that either the helpers need to work with both versions of
the library, or they need to use different paths for the different
versions, or if neither of those cases are possible, then you're in the
situation where they sadly need to conflict, but it would be best to avoid
this.

I don't recall a specific discussion off the top of my head, so maybe
there's a better way to phrase this that doesn't imply there's a
requirement to discuss it on debian-devel. But I do think that paragraph
reflects current practice in its general thrust: The normal practice is to
ensure that different shared library versions are coinstallable so that
upgrade transitions are easier, it's unfortunate when that's not possible,
and we try to avoid the disruption of having the library packages conflict
when we can.

That would be great. Wording suggestions welcome.

I generally agree with this but disagree with the "many reverse
dependencies" part. This is our standard packaging practice for all shared
libraries.

I'm opposed to removing the discussion in the footnote, but better wording
is always welcome.

But sometimes you don't want to. Especially if  the libraries are not using
symbol versioning and the libraries are likely to be loaded into the same
process.

You can do a lot of magic with shlibs/symbols files and provides

e.g. you can in your symbols/shlibs file specify
libfoo (>>VERSION), libfoo-abi-7

and have libfoo provide libfoo-abi-7.

We have done that for libraries with exported-symbols-that-shouldn't-be-used-
unless-you-are-special; see for example the qt6-base source package.

It is also used for the kdepim (personal information management:
email,contacts,calendar,...) which has a lot of shared components without a
stable abi and from an upstream POV it is considered one release that just
comes in multiple tarballs.

/Sune

Sune Stolborg Vuorela <sune@debian.org> writes:

Could you expand on that a bit more? You're saying there's a case where
the SONAME of the library has changed, but you do not want to change the
name of the Debian package because... I'm not sure why? What are you
gaining by not changing the name of the package?

To be clear, I'm not going to second-guess how you manage a complex set of
C++ libraries like Qt, which pose a lot of challenges that are rather
unlike other shared library packages. I am happy for large, complex
ecosystems to carve out some exceptions, and if that needs some Policy
language blessing that, sure. There are a *lot* of factors in play that
combine to make Qt and KDE particularly complicated, such as the
difficulty using symbol versioning with C++ frameworks.

But I feel like either you're missing my point or I'm missing yours. The
Provides structure you describe above does nothing to allow the two
libraries to be coinstalled, which is what the original bug report claimed
(I thought).

Sure, if you want the two libraries to conflict, there are other
possibilities, and I can see how the Provides would be useful to provide,
for example, library transition tracking to have something to trigger on.
But we're already in the failure case at that point of not being able to
allow coinstallability. Provides is not a replacement for renaming the
package.

Libraries that do not have a stable API and are internal to a particular
package aren't relevant to this discussion since this whole section of
Policy doesn't apply to them:

    This section deals only with public shared libraries: shared libraries
    that are placed in directories searched by the dynamic linker by
    default or which are intended to be linked against normally and
    possibly used by other, independent packages. Shared libraries that
    are internal to a particular package or that are only loaded as
    dynamic modules are not covered by this section and are not subject to
    its requirements.

Maybe the kdepim libraries fall into an awkward spot between the two?

During an upgrade even if the file libfoo.so.N is removed, programs
linked against libfoo.so.N might still be running and might still attempt to
access files in libfoo-common or libfoo-bin.
So the new libfoo-common/libfoo-bin still need to be compatible with the old
libfoo.so.N,

Given the library packages only contain a library file, they cannot have file
conflicts with other packages so coinstability should not be an issue.

So policy should continue to require coinstability.

Cheers,

Hi,

Sorry, programs *will* in general *not* *work* when their environment
is updated while they are running. For most programs this is undefined
behavior.

A requirement that running instances of Firefox/Libreoffice/* will
continue to work while their packages are upgraded (or even removed) is
not realistic. It only works by luck for trivial programs (and nobody
tests this).

Ansgar

I'm afraid that this is a well-known source of problems, and not
restarting these programs is not supported in practice, whatever our
Policy tries to do or not. It's so bad that there are
initiatives for upgrading packages only in single-user environment:
https://docs.fedoraproject.org/en-US/kde/offlineupdates/