[SCM] Debian Qt/KDE packaging tools branch, master, updated. debian/0.15.15-21-g36fe333

Sat Apr 25 04:09:15 UTC 2015

Gitweb-URL: http://git.debian.org/?p=pkg-kde/pkg-kde-tools.git;a=commitdiff;h=36fe333

The following commit has been merged in the master branch:
commit 36fe33331225256d84abecdd6df40475c338ab5d
Author: Diane Trout <diane at ghic.org>
Date:   Fri Apr 24 21:07:30 2015 -0700

    Add man pages for pkgkde-gensymbols and pkgkde-symbolshelper (Closes: #782866)
---
 debian/changelog            |   8 +++
 man1/pkgkde-gensymbols.1    | 117 ++++++++++++++++++++++++++++++++++++++++++++
 man1/pkgkde-symbolshelper.1 |  98 +++++++++++++++++++++++++++++++++++++
 3 files changed, 223 insertions(+)

diff --git a/debian/changelog b/debian/changelog
index 199f689..fe1a77c 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,11 @@
+pkg-kde-tools (0.15.16) UNRELEASED; urgency=medium
+
+  [ Diane Trout ]
+  * Add man pages for pkgkde-gensymbols and pkgkde-symbolshelper
+    (Closes: #782866)
+
+ -- Diane Trout <diane at ghic.org>  Fri, 24 Apr 2015 21:06:02 -0700
+
 pkg-kde-tools (0.15.15) unstable; urgency=medium
 
   * The fix for #744173 required to convert non-anchored regexps to anchored
diff --git a/man1/pkgkde-gensymbols.1 b/man1/pkgkde-gensymbols.1
new file mode 100644
index 0000000..cd0ea55
--- /dev/null
+++ b/man1/pkgkde-gensymbols.1
@@ -0,0 +1,117 @@
+.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
+[
B
+.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 
Ipackage-build-dir
R 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 
BFile::Glob
P(3perl) manual page for details) in 
Ilibrary-file
R
+to match multiple libraries with a single argument (otherwise you need
+multiple 
B\-e
R).
+.TP
+.BI \-I filename
+Use 
Ifilename
R as reference file to generate the symbols file
+that is integrated in the package itself.
+.TP
+.BR \-O [
Ifilename
P]
+Print the generated symbols file to standard output or to 
Ifilename
R
+if specified, rather than to
+.B debian/tmp/DEBIAN/symbols
+(or
+.IB package-build-dir /DEBIAN/symbols
+if
+.B \-P
+was used). If 
Ifilename
R 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
+
Bdeb\-symbols
P(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
+
Bdeb\-symbols
P(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 
B\-c
P option).
+.TP
+.BI \-a arch
+Assume 
Iarch
R 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).
diff --git a/man1/pkgkde-symbolshelper.1 b/man1/pkgkde-symbolshelper.1
new file mode 100644
index 0000000..ee8356e
--- /dev/null
+++ b/man1/pkgkde-symbolshelper.1
@@ -0,0 +1,98 @@
+.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
+
Bcreate
R | 
Bpatch
R | 
Bbatchpatch
R | 
Brewrite
R
+.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
+
(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
+
R
+.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
+
(CW
+dpkg-buildpackage | tee buildlog
+pkgkde-symbolshelper patch -p libfoo1 -v 1.8 < buildlog
+
R
+.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
+
(CW
+pkgkde-symbolshelper batchpatch -v 1.8 < buildlog
+
R
+.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
+
(CW
+pkgkde-getbuildlogs
+pkgkde-symbolshelper batchpatch -v 1.8 foo_unstable_logs/foo_1.8-1*.build
+
R
+.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).

-- 
Debian Qt/KDE packaging tools

