On Apache
Under GNU General Public License
2012-05-25 20:41 @38.107.179.239 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
dpkg-gensymbols(1) dpkg utilities dpkg-gensymbols(1)
NAME
dpkg-gensymbols - generate symbols files (shared library dependency information)
SYNOPSIS
dpkg-gensymbols [options]
DESCRIPTION
dpkg-gensymbols scans a temporary build tree (debian/tmp by default) looking for libraries
and generate a symbols file describing them. This file, if non-empty, is then installed in
the DEBIAN subdirectory of the build tree so that it ends up included in the control
information of the package.
When generating those files, it uses as input some symbols files provided by the main-
tainer. It looks for the following files (and use the first that is found):
o debian/package.symbols.arch
o debian/symbols.arch
o debian/package.symbols
o debian/symbols
The main interest of those files is to provide the minimal version associated to each sym-
bol provided by the libraries. Usually it corresponds to the first version of that package
that provided the symbol, but it can be manually incremented by the maintainer if the ABI
of the symbol is extended without breaking backwards compatibility. It's the responsibil-
ity of the maintainer to keep those files up-to-date and accurate, but dpkg-gensymbols
helps him.
When the generated symbols files differ from the maintainer supplied one, dpkg-gensymbols
will print a diff between the two versions. Furthermore if the difference are too signif-
icant, it will even fail (you can customize how much difference you can tolerate, see the
-c option).
MAINTAINING SYMBOLS FILES
The symbols files are really useful only if they reflect the evolution of the package
through several releases. Thus the maintainer has to update them every time that a new
symbol is added so that its associated minimal version matches reality. To do this prop-
erly he can use the diffs contained in the build logs. In most cases, the diff applies
directly to his debian/package.symbols file. That said, further tweaks are usually needed:
it's recommended for example to drop the Debian revision from the minimal version so that
backports with a lower version number but the same upstream version still satisfy the gen-
erated dependencies. If the Debian revision can't be dropped because the symbol really
got added by the Debian specific change, then one should suffix the version with "~".
Before applying any patch to the symbols file, the maintainer should double-check that
it's sane. Public symbols are not supposed to disappear, so the patch should ideally only
add new lines.
Using includes
When the set of exported symbols differ between architectures, it's no more possible to
use a common symbols file. Using one file per architecture works, but it can also lead to
duplication of information. In those cases, you can factorize the common part in some
external file and include that file in your package.symbols.arch file by using an include
directive like this:
#include "packages.symbols.common"
The symbols files are read line by line, and include directives are processed as soon as
they are encountered. This means that the content of the included file can override any
content that appeared before the include directive and that any content after the
directive can override anything contained in the included file.
An included file can repeat the header line containing the SONAME of the library. In that
case, it overrides any header line previously read. However, in general it's best to
avoid duplicating header lines. One way to do it is the following:
#include "libsomething1.symbols.common"
arch_specific_symbol@Base 1.0
Using wildcards with versioned symbols
Well maintained libraries have versioned symbols where each version corresponds to the
upstream version where the symbol got added. If that's the case, it's possible to write a
symbols file with wildcard entries like "*@GLIBC_2.0" that would match any symbol associ-
ated to the version GLIBC_2.0. It's still possible to include specific symbols in the
file, they'll take precedence over any matching wildcard entry. An example:
libc.so.6 libc6 #MINVER#
*@GLIBC_2.0 2.0
[...]
*@GLIBC_2.7 2.7
access AT GLIBC_2.0 2.2
The symbol access AT GLIBC_2.0 will lead to a minimal dependency on libc6 version 2.2 despite
the wildcard entry *@GLIBC_2.0 which associates symbols versioned as GLIBC_2.0 with the
minimal version 2.0.
Note that using wildcards means that dpkg-gensymbols can't check for symbols that might
have disappeared and can't generate a diff between the maintainer-supplied symbols file
and the generated one in the binary package.
Good library management
A well-maintained library has the following features:
o its API is stable (public symbols are never dropped, only new public symbols are
added) and changes in incompatible ways only when the SONAME changes;
o ideally, it uses symbol versioning to achieve ABI stability despite internal changes
and API extension;
o it doesn't export private symbols.
While maintaining the symbols file, it's easy to notice appearance and disappearance of
symbols. But it's more difficult to catch incompatible API and ABI change. Thus the main-
tainer should read thoroughly the upstream changelog looking for cases where the rules of
good library management have been broken. If potential problems are discovered, the
upstream author should be notified as an upstream fix is always better than a Debian spe-
cific work-around.
OPTIONS
-Ppackage-build-dir
Scan package-build-dir instead of debian/tmp.
-ppackage
Define the package name. Required if more than one binary package is listed in
debian/control (or if there's no debian/control file).
-vversion
Define the package version. Defaults to the version extracted from
debian/changelog. Required if called outside of a source package tree.
-elibrary-file
Only analyze libraries explicitly listed instead of finding all public libraries.
You can use a regular expression in library-file to match multiple libraries with a
single argument (otherwise you need multiple -e).
-Ifilename
Use filename as reference file to generate the symbols file that is integrated in
the package itself.
-O Print the generated symbols file to standard output, rather than being stored in
the package build tree.
-Ofilename
Store the generated symbols file as filename. If filename is pre-existing, its con-
tent is 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.
-c[0-4]
Define the checks to do when comparing the generated symbols file with the 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 disables all checks. 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 DPKG_GENSYM-
BOLS_CHECK_LEVEL.
-d Enable debug mode. Numerous messages are displayed to explain what dpkg-gensymbols
does.
-h, --help
Show the usage message and exit.
--version
Show the version and exit.
SEE ALSO
http://people.redhat.com/drepper/symbol-versioning
http://people.redhat.com/drepper/goodpractice.pdf
http://people.redhat.com/drepper/dsohowto.pdf
deb-symbols(5), dpkg-shlibdeps(1).
AUTHORS
Copyright (C) 2007 Raphael Hertzog
This is free software; see the GNU General Public Licence version 2 or later for copying
conditions. There is NO WARRANTY.
Debian Project 2007-07-16 dpkg-gensymbols(1)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2012-05-25 20:41 @38.107.179.239 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)