Bug#989344: ogre-1.12: diff for NMU version 1.12.10+dfsg2-1.1

[Simon McVittie]

(This is all for post-bullseye: the NMU seems like a good minimal change
to resolve this for bullseye.)

On Sun, 13 Jun 2021 at 22:18:42 +0200, Jochen Sprickerhof wrote:
> * Olek Wojnar <olek at debian.org> [2021-06-13 15:15]:
> > As Simon's sponsor, I'd like to point out that his packaging was rather
> > reasonable for a typical library. It is *extremely unusual* for a package
> > to lose backwards-compatibility across _bugfix versions_!

It's unusual, but not unheard of, unfortunately - some API designs make it
really hard to keep backwards compatibility, because a lot of internal
decisions get exposed as API/ABI. This is particularly likely to happen
if the way the upstream developer expects their library to be used and the
way we expect libraries to be used don't match, which is somewhat common
in games particularly: game developers often expect to bundle or statically
link a matching version of their game engine with each game, and are
surprised by distributions wanting to install a single copy system-wide and
use it for multiple games.

> I agree that library that change the Soname with every release don't sound
> like the best idea.

If upstream break the ABI then they are absolutely correct to bump
the SONAME. If upstream do not break the ABI, then ideally they should not
bump the SONAME; but needing transitions more often is a less painful
failure mode than having programs crash, so if the majority of their
upstream releases do break ABI, then I can understand why they would want
to bump the SONAME every time.

If upstream change the SONAME with every release, then the way we package
the library in Debian needs to reflect that. The shared-library parts
of Policy (section 8) are there for good reasons, and I would recommend
checking that you understand those sections if you're maintaining or
sponsoring a shared library package. Others on the debian-devel-games
mailing list can help if you are unsure.

> Normally lintian should warn you if library and package
> name don't match, but that's disabled for ogre-1.12. Maybe it makes sense to
> add some documentation to d/Readme.source or tests in d/rules so you don't
> forget next time.

I see the Ogre package overrides the package-name-doesnt-match-sonames
lintian tag because it is really a bundle of multiple shared libraries
libOgreMain.so.1.12.10, libOgreOverlay.so.1.12.10 and so on, which were
presumably considered to be too small to package separately.

The GNOME team has historically packaged a few libraries like this (GTK,
Pango, GLib, gdk-pixbuf) based on the idea that there was no point in
splitting them, and it has caused annoying library transitions for at
least Pango and gdk-pixbuf when we found that in fact, there *was*
a need to split them. Based on that experience, if the ftp team do
not tell you not to, I would usually recommend packaging each shared
library as a separate binary package, with the name mechanically
generated from the SONAME as recommended in Policy, and not needing to
override package-name-doesnt-match-sonames.

After bullseye is released, next time upstream bumps the SONAME
(presumably 1.12.12?), I think it would be good to seriously consider
packaging the libraries as libogremain1.12.12, libogreoverlay1.12.12
and so on.

If that isn't an option (for example if the ftp team reject that version
from NEW saying that the binary packages are too numerous / too small),
then I would recommend having some automatic checks in the packaging
that will make sure the package fails to build if the SONAME is not what
we expect, for example by running an implementation of this pseudocode
after dh_install:

    ABI_VERSION=1.12.12
    LIBRARIES=Bites Main MeshLodGenerator Overlay ...

    foreach library in LIBRARIES:
        assert that debian/libogre$(ABI_VERSION)/usr/lib/$(DEB_HOST_MULTIARCH)/libOgre${library}.so.$(ABI_VERSION) exists
        get the SONAME from debian/libogre$(ABI_VERSION)/usr/lib/$(DEB_HOST_MULTIARCH)/libOgre${library}.so.$(ABI_VERSION)
            (perhaps use eu-readelf -d or objdump -p)
        assert that the SONAME is as expected

Better to catch this sort of thing *before* upload, after all!

Looking at the file list of libogre1.12, I also notice that it contains
non-library files like /usr/share/OGRE/Media/packs/SdkTrays.zip. Policy
§8.2 says /usr/share/OGRE should be in a separate package, perhaps
libogre-data or libogre-common, with appropriate versioned Depends and
Breaks to make sure the libraries and data match closely enough:

    8.2. Shared library support files
    If your package contains files whose names do not change with each
    change in the library shared object version, you must not put them
    in the shared library package.

Again, that seems like something that would be good to fix post-bullseye.
The upstream SONAME bump will need to go through NEW *anyway*, so it's a
good time to add a libogre-data package.

(If the non-library resource files were in /usr/share/OGRE-1.12.12 then
it would be OK for them to stay with the library.)

    smcv