diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
commit | b86570f63e533abcbcb97c2572e0e5732a96307b (patch) | |
tree | cabc83be691530ae685c45a8bc7620ccc0e1ebdf /man/dpkg-gensymbols.pod | |
parent | Initial commit. (diff) | |
download | dpkg-upstream.tar.xz dpkg-upstream.zip |
Adding upstream version 1.20.13.upstream/1.20.13upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | man/dpkg-gensymbols.pod | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/man/dpkg-gensymbols.pod b/man/dpkg-gensymbols.pod new file mode 100644 index 0000000..1f37774 --- /dev/null +++ b/man/dpkg-gensymbols.pod @@ -0,0 +1,297 @@ +# 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). + +=head1 MAINTAINING SYMBOLS FILES + +The base interchange format of the symbols file is described in +B<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 B<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 B<File::Glob>(3perl) 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 +B<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 +B<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. 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 +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<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>, +B<deb-src-symbol>(5), +B<deb-symbols>(5), +B<dpkg-shlibdeps>(1). |