.TH PKGKDE\-SYMBOLSHELPER 1 "2015-04-18" "0.15" "Debian KDE symbols helper"
.SH NAME
.B pkgkde\-symbolshelper
\- a tool to help simplify managing C++ symbols files for the KDE project.
.SH SYNOPSIS
.B pkgkde\-symbolshelper
\fBcreate\fR | \fBpatch\fR | \fBbatchpatch\fR | \fBrewrite\fR
.P
.SH DESCRIPTION
.B pkgkde-symbolshelper
provides helps to automate the process of managing your
.BR deb\-symbols (5)
files.
.P
There are four commands, create, patch, batchpatch, and rewrite.
.P
.SH CREATING SYMBOLS FILE
To create the symbols file for a library package libfoo1 whose version
is 1.7
.nf
.RS
\f(CW
pkgkde-gensymbols -plibfoo1 -v1.7 -Osymbols.amd64 -edebian/libfoo1/usr/lib/libfoo.so.1
pkgkde-symbolshelper create -o debian/libfoo1.symbols -v 1.7 symbols.amd64
\fR
.RE
.fi
.P
The above commands should be invoked from the top level directory of
your package's source after having built the package before cleaning,
so that debian/libfoo1/usr/lib/libfoo.so.1 exists).
.P
"symbols.amd64" is the filename of the intermediate symbols file that
will be generated by pkgkde-gensymbols. This filename must be in the
format "name.architecture" or "name_architecture" where "architecture"
is the cpu architecture on which you have built this package.
.SH UPDATING A SYMBOLS FILE FOR A NEW LIBRARY VERSION
After building a new version of the library (for instance 1.8 of our
libfoo1 library from above), symbols may have been added or removed,
and in both cases one must check and update the symbols file. During
the build, a diff between the current symbols file and the one based
on the current built library will printed in the output.
.BR pkgkde-symbolshelper
can read the build log to find this diff, to save the build log one may want
to do:
.nf
.RS
\f(CW
dpkg-buildpackage | tee buildlog
pkgkde-symbolshelper patch -p libfoo1 -v 1.8 < buildlog
\fR
.RE
.fi
.PP
.SH UPDATING MULTIPLE SYMBOLS FILES AT ONCE
For source packages that provide multiple binary library packages, it is
useful to have a method to patch all the symbol files at once,
.BR pkgkde-symbolshelper
offers a way to do this using the
.BR batchpatch
command. For example:
.nf
.RS
\f(CW
pkgkde-symbolshelper batchpatch -v 1.8 < buildlog
\fR
.RE
.fi
.PP
.BR batchpatch
can also be of use when one wants to update symbol files for multiple
architectures at once. There is an additional command
.BR pkgkde\-getbuildlogs
that will download the build logs for multiple architectures from
Debian's build servers.
.nf
.RS
\f(CW
pkgkde-getbuildlogs
pkgkde-symbolshelper batchpatch -v 1.8 foo_unstable_logs/foo_1.8-1*.build
\fR
.RE
.fi
.PP
.SH NOTES
This man page was based text written by others from the pkg-kde
symbols file help page.
.SH SEE ALSO
.BR https://qt-kde-team.pages.debian.net/symbolfiles.html
.br
.BR https://people.redhat.com/drepper/symbol\-versioning
.br
.BR https://people.redhat.com/drepper/goodpractice.pdf
.br
.BR https://people.redhat.com/drepper/dsohowto.pdf
.br
.BR dpkg\-gensymbols (1),
.BR deb\-symbols (5),
.BR dpkg\-shlibdeps (1).