Keeping binary compatibility

[Lubos Lunak]

 Hello,

 as you probably know, the theory is that KDE libraries keep backwards binary 
compatibility. As you might or might not know, that is the theory.

 I've found a tool called abi-compliance-checker 
(http://ispras.linux-foundation.org/index.php/ABI_compliance_checker) and it 
has a page with checks for various libraries including ours 
(http://linuxtesting.org/upstream-tracker/versions/kde-libs.html), which is 
not as green as it should be.

 I've also compared openSUSE packages for 4.4.4 and 4.5.1 and there are 
problems too (http://ktown.kde.org/~seli/abi/ for what I checked). Let me 
point out just one, http://reviewboard.kde.org/r/2608/ , which I think shows 
that this occassionally happening is inevitable.

 Moreover, there seem to be cases where we simply don't seem to have rules (or 
at least I couldn't find them). Do we have rules that say more than "kdelibs 
is BC stable, we don't care about the rest"? What's the status with e.g. 
kdeedu libs? I'm asking because, consider e.g. these errors from an attempt 
to uninstall kdebase/workspace package here:

libkscreensaver.so.5()(64bit) is needed by (installed)
    kdeartwork4-screensaver-4.4.4-2.1.1.x86_64
libkworkspace.so.4()(64bit) is needed by (installed) ktorrent-3.3.4-4.1.x86_64
libkworkspace.so.4()(64bit) is needed by (installed) kor-0.3-2.2s.x86_64
libsolidcontrol.so.4()(64bit) is needed by (installed)
    ktorrent-3.3.4-4.1.x86_64                                     
libsolidcontrol.so.4()(64bit) is needed by (installed)
    kbluetooth-0.4.2-3.1.x86_64
libsolidcontrol.so.4()(64bit) is needed by (installed)
    NetworkManager-kde4-libs-0.9.svn1057339-4.1.x86_64
libtaskmanager.so.4()(64bit) is needed by (installed)
    ktorrent-3.3.4-4.1.x86_64

 Now, an explanation is probably needed for those who live only in the SVN 
world or with distros where breakages are solved by rebuilding everything. If 
you develop e.g. on openSUSE and you notice a library you might like to use, 
then you perhaps install its -devel package, maybe go as far as reading its 
documentation (which doesn't say anything interesting in the case of 
kdebase4-workspace-devel or libkeedu4-devel), or maybe you just read its .h 
files and then make your app use the library.

 Then you release a tarball, some packager builds it, adds also the -devel 
package to the build requirements, the app builds and the packaging system 
records a dependency on the library, as seen above. That is, on the library 
soname (lib<name>.so.+<one number>). That's how it's done. I read somewhere 
that when using "unstable" KDE libs the requirement should be on the exact 
version, but that's not how it's done. Can you see above ktorrent requiring 
kdebase4-workspace = 4.4.4? No, and it's unlikely a system like that would 
get as far as the packager knowing and doing so (not only because not 
knowing, but also because it's stupid - why should anybody be forced to 
upgrade ktorrent from a 3rd party repo whenever there's another patchlevel SC 
release).

 Looking at how KDE provides various libraries leads to a number of WTH 
questions, like:
- WTH is the ABI stability documented, besides kdelibs?
- WTH is there e.g. libiris_ksirk.so (i.e. a development .so symlink), where 
are the .h files?
- WTH does e.g. libtaskmanager seem to have soname versioning following SC 
version, like stable kdelibs libraries do, but it's not actually stable?
- WTH does e.g. ksysguard install libraries .so and .h files for something 
that looks a lot like its internal libraries?

 Therefore I propose the following:
- private libraries do not (obviously ...?) install their .h files and do use 
NAMELINK_SKIP option in install (see e.g. 
http://websvn.kde.org/trunk/KDE/kdebase/workspace/khotkeys/libkhotkeysprivate/CMakeLists.txt?r1=862343&r2=895764)
- ABI stability for each public library is documented, I would suggest a 
README.<library> file in sources and in the main doxygen page
- ABI of each stable library (obviously) does not change
- whenever ABI of an unstable library changes, its soname is increased (which 
means that each library will need in its CMakeLists.txt something like this 
http://websvn.kde.org/trunk/KDE/kdelibs/plasma/CMakeLists.txt?r1=879765&r2=879766& , 
handled manually, instead of generic macros)
- the release team howto gets a new entry 'each new version is ABI tested 
before release'  (I do not have tests for 4.5.2 yet as I'm waiting for the 
packages to rebuild, and as said above I also don't quite know what to check, 
but in general I have a quite easy way of checking the whole KDE SC on each 
release)

-- 
 Lubos Lunak
 openSUSE Boosters team, KDE developer
 l.lunak at suse.cz , l.lunak at kde.org