Bug#1136641: debian-policy: do not require shared libraries to change package name with soname changes

[Andrey Rakhmatullin]

On Fri, May 15, 2026 at 01:00:13PM +0200, Bill Allombert wrote:

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.


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/


--
WBR, wRAR


signature.asc
Description: PGP signature

Bug#1136641: debian-policy: do not require shared libraries to change package name with soname changes

[Ansgar 🙀]

Hi,

On Fri, 2026-05-15 at 13:00 +0200, Bill Allombert wrote:
> On Thu, May 14, 2026 at 10:46:59AM +0200, Ansgar wrote:
> > 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.)
> 
> 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, 

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

Bug#1136641: debian-policy: do not require shared libraries to change package name with soname changes

[Bill Allombert]

On Thu, May 14, 2026 at 10:46:59AM +0200, Ansgar wrote:
> 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.)

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,
-- 
Bill. 

Imagine a large red swirl here. 

Bug#1136641: debian-policy: do not require shared libraries to change package name with soname changes

[Russ Allbery]

Sune Stolborg Vuorela  writes:
> Russ Allbery wrote:

>> 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.

> 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.

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?

> 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.

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.

> 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.

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?

-- 
Russ Allbery (r...@debian.org)  

Bug#1136641: debian-policy: do not require shared libraries to change package name with soname changes

[Sune Stolborg Vuorela]

On Thursday, May 14, 2026 5:33:00 PM Central European Summer Time Russ Allbery 
wrote:
> > 1. It is not needed to change package names for this. One can also use
> > "Provides: " and have packages
> > depend on that.
> 
> 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.

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.

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

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
-- 
I didn’t stop pretending when I became an adult, it’s just that when I was a 
kid I was pretending that I fit into the rules and structures of this world. 
And now that I’m an adult, I pretend that those rules and structures exist.
   - zefrank

signature.asc
Description: This is a digitally signed message part.

Bug#1136641: debian-policy: do not require shared libraries to change package name with soname changes

[Russ Allbery]

Ansgar  writes:

> 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: " and have packages
> depend on that.

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?

> 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.

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.

> 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.

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.

> 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.

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.

> 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).

That would be great. Wording suggestions welcome.

> 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
> w

Bug#1136641: debian-policy: do not require shared libraries to change package name with soname changes

[Ansgar 🙀]

Hi,

On Thu, 2026-05-14 at 13:45 +0200, Bill Allombert wrote:
> On Thu, May 14, 2026 at 12:09:31PM +0200, Ansgar 🙀 wrote:
> 
> > We do not do that in practice and I often see libX removed due to
> > Breaks/Conflicts.
> 
> 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.

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"

Bug#1136641: debian-policy: do not require shared libraries to change package name with soname changes

[Bill Allombert]

On Thu, May 14, 2026 at 12:09:31PM +0200, Ansgar 🙀 wrote:
> Hi,
> 
> On Thu, 2026-05-14 at 11:47 +0200, Bill Allombert wrote:
> > On Thu, May 14, 2026 at 10:46:59AM +0200, Ansgar wrote:
> > > 1. It is not needed to change package names for this. One can also use
> > > "Provides: " and have packages
> > > depend on that.
> > 
> > Provides: would not work.
> > 
> > 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.
> 
> Then Policy would need to forbid *any* Breaks/Conflicts against libX
> packages that are no longer shipped by Debian. 

Yes.

> We do not do that in practice and I often see libX removed due to
> Breaks/Conflicts.

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,
-- 
Bill. 

Imagine a large red swirl here. 

Bug#1136641: debian-policy: do not require shared libraries to change package name with soname changes

[Ansgar 🙀]

Hi,

On Thu, 2026-05-14 at 11:47 +0200, Bill Allombert wrote:
> On Thu, May 14, 2026 at 10:46:59AM +0200, Ansgar wrote:
> > 1. It is not needed to change package names for this. One can also use
> > "Provides: " and have packages
> > depend on that.
> 
> Provides: would not work.
> 
> 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.

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

Bug#1136641: debian-policy: do not require shared libraries to change package name with soname changes

[Bill Allombert]

On Thu, May 14, 2026 at 10:46:59AM +0200, Ansgar wrote:
> Package: debian-policy
> Severity: normal
> 
> 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: " and have packages
> depend on that.

Provides: would not work.

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.

Bug#1136641: debian-policy: do not require shared libraries to change package name with soname changes

[Ansgar]

Package: debian-policy
Severity: normal

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: " 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