Bug#782866: pkg-kde-tools: man pages for pkg-kde-tools
Package: pkg-kde-tools
Version: 0.15.16
Severity: wishlist
Tags: patch
Dear Maintainer,
It would be convienent to have some of the documentation available at http
://pkg-kde.alioth.debian.org/symbolfiles.html available as man pages.
-- System Information:
Debian Release: 8.0
APT prefers stable-updates
APT policy: (500, 'stable-updates'), (500, 'unstable'), (500, 'testing'), (500, 'stable'), (1, 'experimental')
Architecture: amd64 (x86_64)
Foreign Architectures: i386
Kernel: Linux 3.16.0-4-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
Versions of packages pkg-kde-tools depends on:
ii libdpkg-perl 1.17.25
ii perl 5.20.2-3
Versions of packages pkg-kde-tools recommends:
ii dpkg-dev 1.17.25
ii libwww-perl 6.08-1
Versions of packages pkg-kde-tools suggests:
ii cdbs 0.4.130
ii debhelper 9.20150101
-- no debconf information
.TH PKGKDE\-GENSYMBOLS 1 "2015-04-18" "0.15" "Debian KDE dpkg-gensymbols wrapper"
.SH NAME
.B pkgkde\-gensymbols
\- a helper tool for Debian pkg-kde symbols files.
.SH SYNOPSIS
.B pkgkde\-gensymbols
[\fB
.P
.SH DESCRIPTION
.B pkgkde-gensymbols
is a wrapper around dpkg-gensymbols that provides additional support
for tracking C++ symbols such as template instantiated symbols.
See
.BR dpkg\-gensymbols (1)
for more information about maintaining symbols files.
.P
.SH OPTIONS
.TP
.BI \-P package-build-dir
Scan \fIpackage-build-dir\fR instead of debian/tmp.
.TP
.BI \-p package
Define the package name. Required if more than one binary package is listed in
debian/control (or if there's no debian/control file).
.TP
.BI \-v version
Define the package version. Defaults to the version extracted from
debian/changelog. Required if called outside of a source package tree.
.TP
.BI \-e library-file
Only analyze libraries explicitly listed instead of finding all public
libraries. You can use shell patterns used for pathname expansions (see
the \fBFile::Glob\fP(3perl) manual page for details) in \fIlibrary-file\fR
to match multiple libraries with a single argument (otherwise you need
multiple \fB\-e\fR).
.TP
.BI \-I filename
Use \fIfilename\fR as reference file to generate the symbols file
that is integrated in the package itself.
.TP
.BR \-O [\fIfilename\fP]
Print the generated symbols file to standard output or to \fIfilename\fR
if specified, rather than to
.B debian/tmp/DEBIAN/symbols
(or
.IB package-build-dir /DEBIAN/symbols
if
.B \-P
was used). If \fIfilename\fR is pre-existing, its contents are used as
basis for the generated symbols file.
You can use this feature to update a symbols file so that it matches a
newer upstream version of your library.
.TP
.BI \-t
Write the symbol file in template mode rather than the format compatible with
\fBdeb\-symbols\fP(5). The main difference is that in the template mode symbol
names and tags are written in their original form contrary to the
post-processed symbol names with tags stripped in the compatibility mode.
Moreover, some symbols might be omitted when writing a standard
\fBdeb\-symbols\fP(5) file (according to the tag processing rules) while all
symbols are always written to the symbol file template.
.TP
.BI \-c [0-4]
Define the checks to do when comparing the generated symbols file with the
template file used as starting point. By default the level is 1. Increasing
levels do more checks and include all checks of lower levels. Level 0 never
fails. Level 1 fails if some symbols have disappeared. Level 2 fails if some
new symbols have been introduced. Level 3 fails if some libraries have
disappeared. Level 4 fails if some libraries have been introduced.
This value can be overridden by the environment variable
.BR DPKG_GENSYMBOLS_CHECK_LEVEL .
.TP
.BI \-q
Keep quiet and never generate a diff between generated symbols file and the
template file used as starting point or show any warnings about new/lost
libraries or new/lost symbols. This option only disables informational output
but not the checks themselves (see \fB\-c\fP option).
.TP
.BI \-a arch
Assume \fIarch\fR as host architecture when processing symbol files. Use this
option to generate a symbol file or diff for any architecture provided its
binaries are already available.
.TP
.BI \-d
Enable debug mode. Numerous messages are displayed to explain what
.B dpkg\-gensymbols
does.
.TP
.BI \-V
Enable verbose mode. The generated symbols file contains deprecated
symbols as comments. Furthermore in template mode, pattern symbols
are followed by comments listing real symbols that have matched the
pattern.
.TP
.BR \-? ", " \-\-help
Show the usage message and exit.
.TP
.BR \-\-version
Show the version and exit.
.SH NOTES
This man page was based on the pkg-kde symbols file help page and
the
.BR dpkg-gensymbols (1)
man page.
.SH SEE ALSO
.BR http://pkg-kde.alioth.debian.org/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).
.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
.ni
.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 http://pkg-kde.alioth.debian.org/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).
Reply to: