How to adjust symbols-file in a package for a shared lib

Question

I am trying to upgrade ktorrent in my PPA to the latest upstream version. It also requires an updated libktorrent package. It seems libktorrent was changed in incompatible ways and thus results in a new package libktorrent5 instead of the previously available libktorrent4.

However when I try to build the package on my PPA, I get errors about different symbols. I tried some ways to fix it, but it fails with different output each time.

Is there some guide how to correctly generate the symbols-file?

Full build and build-log are here

dh_strip debug symbol extraction: disabling for PPA build dh_strip debug symbol extraction: not doing anything since NO_PKG_MANGLE is given    dh_makeshlibs -Xusr/lib/kde4/ -a -O--parallel -O--
-O--dbg-package=libktorrent-dbg dpkg-gensymbols: warning: some new symbols appeared in the symbols file: see diff output below dpkg-gensymbols: warning: some symbols or patterns disappeared in the symbols file: see diff output below dpkg-gensymbols: warning: debian/libktorrent5/DEBIAN/symbols doesn't match completely debian/libktorrent5.symbols
--- debian/libktorrent5.symbols (libktorrent5_1.3.0-0ubuntu0~ppa4_amd64)
+++ dpkg-gensymbolsNTCQU9   2012-09-30 02:21:19.000000000 +0000 @@ -2912,13 +2912,20 @@   _ZTVN3utp9UTPServer7PrivateE@Base 1.2.0   _ZTVN3utp9UTPServerE@Base 1.2.0   _ZTVN3utp9UTPSocketE@Base 1.2.0
- _ZThn12_N2bt5UTPex5visitE14QSharedPointerINS_4PeerEE@Base 1.3.0
- _ZThn52_N3dht11FindNodeRspD0Ev@Base 1.3.0
- _ZThn52_N3dht11FindNodeRspD1Ev@Base 1.3.0
- _ZThn52_N3dht11GetPeersRspD0Ev@Base 1.3.0
- _ZThn52_N3dht11GetPeersRspD1Ev@Base 1.3.0
- _ZThn8_N2bt4Peer12chunkAllowedEj@Base 1.3.0
- _ZThn8_N2bt4Peer12handlePacketEPKhj@Base 1.3.0
+#MISSING: 1.3.0-0ubuntu0~ppa4# _ZThn12_N2bt5UTPex5visitE14QSharedPointerINS_4PeerEE@Base 1.3.0
+ _ZThn16_N2bt4Peer12chunkAllowedEj@Base 1.3.0-0ubuntu0~ppa4
+ _ZThn16_N2bt4Peer12handlePacketEPKhj@Base 1.3.0-0ubuntu0~ppa4
+ _ZThn24_N2bt5UTPex5visitE14QSharedPointerINS_4PeerEE@Base 1.3.0-0ubuntu0~ppa4
+#MISSING: 1.3.0-0ubuntu0~ppa4# _ZThn52_N3dht11FindNodeRspD0Ev@Base 1.3.0
+#MISSING: 1.3.0-0ubuntu0~ppa4# _ZThn52_N3dht11FindNodeRspD1Ev@Base 1.3.0
+#MISSING: 1.3.0-0ubuntu0~ppa4# _ZThn52_N3dht11GetPeersRspD0Ev@Base 1.3.0
+#MISSING: 1.3.0-0ubuntu0~ppa4# _ZThn52_N3dht11GetPeersRspD1Ev@Base 1.3.0
+ _ZThn80_N3dht11FindNodeRspD0Ev@Base 1.3.0-0ubuntu0~ppa4
+ _ZThn80_N3dht11FindNodeRspD1Ev@Base 1.3.0-0ubuntu0~ppa4
+ _ZThn80_N3dht11GetPeersRspD0Ev@Base 1.3.0-0ubuntu0~ppa4
+ _ZThn80_N3dht11GetPeersRspD1Ev@Base 1.3.0-0ubuntu0~ppa4
+#MISSING: 1.3.0-0ubuntu0~ppa4# _ZThn8_N2bt4Peer12chunkAllowedEj@Base 1.3.0
+#MISSING: 1.3.0-0ubuntu0~ppa4# _ZThn8_N2bt4Peer12handlePacketEPKhj@Base 1.3.0   (c++)"non-virtual thunk to bt::ChunkDownload::getStats(bt::ChunkDownloadInterface::Stats&)@Base"
1.2.0   (c++)"non-virtual thunk to bt::ChunkDownload::~ChunkDownload()@Base" 1.2.0   (c++)"non-virtual thunk to bt::DataCheckerJob::acquired()@Base" 1.2.0 dh_makeshlibs: dpkg-gensymbols -plibktorrent5 -Idebian/libktorrent5.symbols
-Pdebian/libktorrent5 -edebian/libktorrent5/usr/lib/libktorrent.so.5.0.0  returned exit code 1

Answer 1

The Debian KDE team has a guide to dealing with symbols files:

After building a new version of the library, symbols may have been added or removed, and in both cases you need to check and update the symbols file. During the build, a diff between the current symbols file and the one that should be there instead will be printed in the output. So, as a first step, you need to save the build log in a file. You can do that by piping the output of your build command through tee, for example:

dpkg-buildpackage -j4 | tee buildlog

In case you forgot to pipe the output and you want to avoid rebuilding, you can also copy-paste the part of the output that contains the diff in new file.

After saving the diff in a file, you can patch the symbols file by executing:

pkgkde-symbolshelper patch -p libfoo1 -v 1.8 < buildlog

Here we suppose that your libfoo1 package was updated to version 1.8, so "-v 1.8" in the command is the switch to specify the new version.

You'll need to install pkg-kde-tools