348 lines
9.9 KiB
Text
348 lines
9.9 KiB
Text
# dpkg manual page - dpkg-gensymbols(1)
|
||
#
|
||
# Copyright © 2007-2011 Raphaël Hertzog <hertzog@debian.org>
|
||
# Copyright © 2009-2010 Modestas Vainius <modestas@vainius.eu>
|
||
# Copyright © 2012-2015 Guillem Jover <guillem@debian.org>
|
||
#
|
||
# This is free software; you can redistribute it and/or modify
|
||
# it under the terms of the GNU General Public License as published by
|
||
# the Free Software Foundation; either version 2 of the License, or
|
||
# (at your option) any later version.
|
||
#
|
||
# This is distributed in the hope that it will be useful,
|
||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
# GNU General Public License for more details.
|
||
#
|
||
# You should have received a copy of the GNU General Public License
|
||
# along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||
|
||
=encoding utf8
|
||
|
||
=head1 NAME
|
||
|
||
dpkg-gensymbols - generate symbols files (shared library dependency information)
|
||
|
||
=head1 SYNOPSIS
|
||
|
||
B<dpkg-gensymbols>
|
||
[I<option>...]
|
||
|
||
=head1 DESCRIPTION
|
||
|
||
B<dpkg-gensymbols>
|
||
scans a temporary build tree (debian/tmp by default) looking for libraries
|
||
and generates a I<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 maintainer.
|
||
It looks for the following files (and uses the
|
||
first that is found):
|
||
|
||
=over
|
||
|
||
=item *
|
||
|
||
debian/I<package>.symbols.I<arch>
|
||
|
||
=item *
|
||
|
||
debian/symbols.I<arch>
|
||
|
||
=item *
|
||
|
||
debian/I<package>.symbols
|
||
|
||
=item *
|
||
|
||
debian/symbols
|
||
|
||
=back
|
||
|
||
The main interest of those files is to provide the minimal version
|
||
associated to each symbol 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
|
||
responsibility of the maintainer to keep those files up-to-date and
|
||
accurate, but B<dpkg-gensymbols> helps with that.
|
||
|
||
When the generated symbols files differ from the maintainer supplied
|
||
one, B<dpkg-gensymbols> will print a diff between the two versions.
|
||
Furthermore if the difference is too significant, it will even fail (you
|
||
can customize how much difference you can tolerate, see the B<-c>
|
||
option).
|
||
|
||
This program was introduced in dpkg 1.14.8.
|
||
|
||
=head1 MAINTAINING SYMBOLS FILES
|
||
|
||
The base interchange format of the symbols file is described in
|
||
L<deb-symbols(5)>, which is used by the symbols files included in
|
||
binary packages.
|
||
These are generated from template symbols files
|
||
with a format based on the former, described in L<deb-src-symbols(5)>
|
||
and included in source packages.
|
||
|
||
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.
|
||
|
||
The diffs contained in the build logs can be used as a starting point,
|
||
but the maintainer, additionally, has to make sure that the behaviour
|
||
of those symbols has not changed in a way that would make anything
|
||
using those symbols and linking against the new version, stop working
|
||
with the old version.
|
||
|
||
In most cases, the diff applies directly to the
|
||
debian/I<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 generated 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 ‘B<~>’.
|
||
|
||
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.
|
||
|
||
Note that you can put comments in symbols files.
|
||
|
||
Do not forget to check if old symbol versions need to be increased.
|
||
There is no way B<dpkg-gensymbols> can warn about this.
|
||
Blindly
|
||
applying the diff or assuming there is nothing to change if there is
|
||
no diff, without checking for such changes, can lead to packages with
|
||
loose dependencies that claim they can work with older packages they
|
||
cannot work with.
|
||
This will introduce hard to find bugs with (partial)
|
||
upgrades.
|
||
|
||
=head2 Good library management
|
||
|
||
A well-maintained library has the following features:
|
||
|
||
=over
|
||
|
||
=item *
|
||
|
||
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;
|
||
|
||
=item *
|
||
|
||
ideally, it uses symbol versioning to achieve ABI stability despite
|
||
internal changes and API extension;
|
||
|
||
=item *
|
||
|
||
it doesn't export private symbols (such symbols can be tagged optional as
|
||
workaround).
|
||
|
||
=back
|
||
|
||
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 maintainer 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 specific work-around.
|
||
|
||
=head1 OPTIONS
|
||
|
||
=over
|
||
|
||
=item B<-P>I<package-build-dir>
|
||
|
||
Scan I<package-build-dir> instead of debian/tmp.
|
||
|
||
=item B<-p>I<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).
|
||
|
||
=item B<-v>I<version>
|
||
|
||
Define the package version.
|
||
Defaults to the version extracted from debian/changelog.
|
||
Required if called outside of a source package tree.
|
||
|
||
=item B<-e>I<library-file>
|
||
|
||
Only analyze libraries explicitly listed instead of finding all public
|
||
libraries.
|
||
You can use shell patterns used for pathname expansions (see
|
||
the L<File::Glob> manual page for details) in I<library-file>
|
||
to match multiple libraries with a single argument (otherwise you need
|
||
multiple B<-e>).
|
||
|
||
=item B<-l>I<directory>
|
||
|
||
Prepend
|
||
I<directory>
|
||
to the list of directories to search for private shared libraries
|
||
(since dpkg 1.19.1).
|
||
This option can be used multiple times.
|
||
|
||
B<Note>: Use this option instead of setting B<LD_LIBRARY_PATH>,
|
||
as that environment variable is used to control the run-time linker
|
||
and abusing it to set the shared library paths at build-time can be
|
||
problematic when cross-compiling for example.
|
||
|
||
=item B<-I>I<filename>
|
||
|
||
Use I<filename> as reference file to generate the symbols file
|
||
that is integrated in the package itself.
|
||
|
||
=item B<-O>[I<filename>]
|
||
|
||
Print the generated symbols file to standard output or to I<filename>
|
||
if specified, rather than to
|
||
B<debian/tmp/DEBIAN/symbols>
|
||
(or
|
||
I<package-build-dir>B</DEBIAN/symbols>
|
||
if
|
||
B<-P>
|
||
was used).
|
||
If I<filename> 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.
|
||
|
||
=item B<-t>
|
||
|
||
Write the symbol file in template mode rather than the format compatible with
|
||
L<deb-symbols(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
|
||
L<deb-symbols(5)> file (according to the tag processing rules) while all
|
||
symbols are always written to the symbol file template.
|
||
|
||
=item B<-c>I<[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.
|
||
|
||
=over
|
||
|
||
=item Level 0
|
||
|
||
Never fails.
|
||
|
||
=item Level 1
|
||
|
||
Fails if some symbols have disappeared.
|
||
|
||
=item Level 2
|
||
|
||
Fails if some new symbols have been introduced.
|
||
|
||
=item Level 3
|
||
|
||
Fails if some libraries have disappeared.
|
||
|
||
=item Level 4
|
||
|
||
Fails if some libraries have been introduced.
|
||
|
||
=back
|
||
|
||
This value can be overridden by the environment variable
|
||
B<DPKG_GENSYMBOLS_CHECK_LEVEL>.
|
||
|
||
=item B<-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> option).
|
||
|
||
=item B<-a>I<arch>
|
||
|
||
Assume I<arch> 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.
|
||
|
||
=item B<-d>
|
||
|
||
Enable debug mode.
|
||
Numerous messages are displayed to explain what
|
||
B<dpkg-gensymbols>
|
||
does.
|
||
|
||
=item B<-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.
|
||
|
||
=item B<-?>, B<--help>
|
||
|
||
Show the usage message and exit.
|
||
|
||
=item B<--version>
|
||
|
||
Show the version and exit.
|
||
|
||
=back
|
||
|
||
=head1 ENVIRONMENT
|
||
|
||
=over
|
||
|
||
=item B<DEB_HOST_ARCH>
|
||
|
||
Sets the host architecture if the B<--arch> option has not be specified.
|
||
|
||
=item B<DPKG_GENSYMBOLS_CHECK_LEVEL>
|
||
|
||
Overrides the command check level, even if the B<-c> command-line
|
||
argument was given (note that this goes against the common convention
|
||
of command-line arguments having precedence over environment variables).
|
||
|
||
=item B<DPKG_COLORS>
|
||
|
||
Sets the color mode (since dpkg 1.18.5).
|
||
The currently accepted values are: B<auto> (default), B<always> and
|
||
B<never>.
|
||
|
||
=item B<DPKG_NLS>
|
||
|
||
If set, it will be used to decide whether to activate Native Language Support,
|
||
also known as internationalization (or i18n) support (since dpkg 1.19.0).
|
||
The accepted values are: B<0> and B<1> (default).
|
||
|
||
=back
|
||
|
||
=head1 SEE ALSO
|
||
|
||
L<https://people.redhat.com/drepper/symbol-versioning>,
|
||
L<https://people.redhat.com/drepper/goodpractice.pdf>,
|
||
L<https://people.redhat.com/drepper/dsohowto.pdf>,
|
||
L<deb-src-symbol(5)>,
|
||
L<deb-symbols(5)>,
|
||
L<dpkg-shlibdeps(1)>.
|