Adding upstream version 1.22.4.upstream/1.22.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 510 insertions, 0 deletions

diff --git a/man/dpkg-shlibdeps.pod b/man/dpkg-shlibdeps.pod
new file mode 100644
index 0000000..0988775
--- /dev/null
+++ b/man/dpkg-shlibdeps.pod
@@ -0,0 +1,510 @@
+# dpkg manual page - dpkg-deb(1)
+#
+# Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
+# Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
+# Copyright © 2006 Frank Lichtenheld <djpig@debian.org>
+# Copyright © 2007-2011 Raphaël Hertzog <hertzog@debian.org>
+# Copyright © 2011-2013, 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-shlibdeps - generate shared library substvar dependencies
+
+=head1 SYNOPSIS
+
+B<dpkg-shlibdeps>
+[I<option>...] [B<-e>] I<executable> [I<option>...]
+
+=head1 DESCRIPTION
+
+B<dpkg-shlibdeps>
+calculates shared library dependencies for executables named in its
+arguments.
+The dependencies are added to the substitution
+variables file
+B<debian/substvars>
+as variable names
+B<shlibs:>I<dependency-field>
+where
+I<dependency-field>
+is a dependency field name.
+Any other variables starting with
+B<shlibs:>
+are removed from the file.
+
+B<dpkg-shlibdeps>
+has two possible sources of information to generate dependency
+information.
+Either
+I<symbols>
+files or
+I<shlibs>
+files.
+For each binary that
+B<dpkg-shlibdeps>
+analyzes, it finds out the list of libraries that it's linked with.
+Then, for each library, it looks up either the
+I<symbols>
+file, or the
+I<shlibs>
+file (if the former doesn't exist or if debian/shlibs.local contains
+the relevant dependency).
+Both files are supposed to be provided
+by the library package and should thus be available as
+%ADMINDIR%/info/I<package>.I<symbols>
+or %ADMINDIR%/info/I<package>.I<shlibs>.
+The package name is
+identified in two steps: find the library file on the system (looking in
+the same directories that B<ld.so> would use), then use
+B<dpkg -S> I<library-file>
+to lookup the package providing the library.
+
+=head2 Symbols files
+
+Symbols files contain finer-grained dependency information by providing
+the minimum dependency for each symbol that the library exports.
+The
+script tries to find a symbols file associated to a library package
+in the following places (first match is used):
+
+=over
+
+=item debian/*/DEBIAN/symbols
+
+Shared library information generated by the current build process that also invoked
+B<dpkg-shlibdeps>.
+They are generated by
+L<dpkg-gensymbols(1)>.
+They are only used if the library is found in a package's build tree.
+The
+symbols file in that build tree takes precedence over symbols files from
+other binary packages.
+
+=item %PKGCONFDIR%/symbols/I<package>.symbols.I<arch>
+
+=item %PKGCONFDIR%/symbols/I<package>.symbols
+
+Per-system overriding shared library dependency information.
+I<arch> is the architecture of the current system (obtained by
+B<dpkg-architecture -qDEB_HOST_ARCH>).
+
+=item Output from “B<dpkg-query --control-path> I<package> symbols”
+
+Package-provided shared library dependency information.
+Unless overridden by B<--admindir>, those files are located in
+%ADMINDIR%.
+
+=back
+
+While scanning the symbols used by all binaries,
+B<dpkg-shlibdeps>
+remembers the (biggest) minimal version needed for each library.
+At the end
+of the process, it is able to write out the minimal dependency for every
+library used (provided that the information of the I<symbols> files are
+accurate).
+
+As a safe-guard measure, a symbols file can provide a
+B<Build-Depends-Package> meta-information field and
+B<dpkg-shlibdeps>
+will extract the minimal version required by the corresponding package in
+the B<Build-Depends> field and use this version if it's higher than the
+minimal version computed by scanning symbols.
+
+=head2 Shlibs files
+
+Shlibs files associate directly a library to a dependency (without looking
+at the symbols).
+It's thus often stronger than really needed but very safe
+and easy to handle.
+
+The dependencies for a library are looked up in several places.
+The first
+file providing information for the library of interest is used:
+
+=over
+
+=item debian/shlibs.local
+
+Package-local overriding shared library dependency information.
+
+=item %PKGCONFDIR%/shlibs.override
+
+Per-system overriding shared library dependency information.
+
+=item debian/*/DEBIAN/shlibs
+
+Shared library information generated by the current build process that also invoked
+B<dpkg-shlibdeps>.
+They are only used if the library is found in a package's build tree.
+The
+shlibs file in that build tree takes precedence over shlibs files from
+other binary packages.
+
+=item Output from “B<dpkg-query --control-path> I<package> shlibs”
+
+Package-provided shared library dependency information.
+Unless overridden by B<--admindir>, those files are located in
+%ADMINDIR%.
+
+=item %PKGCONFDIR%/shlibs.default
+
+Per-system default shared library dependency information.
+
+=back
+
+The extracted dependencies are then directly used (except if they are
+filtered out because they have been identified as duplicate, or as weaker
+than another dependency).
+
+=head1 OPTIONS
+
+B<dpkg-shlibdeps>
+interprets non-option arguments as executable names, just as if they'd
+been supplied as
+B<-e>I<executable>.
+
+=over
+
+=item B<-e>I<executable>
+
+Include dependencies appropriate for the shared libraries required by
+I<executable>.
+This option can be used multiple times.
+
+=item B<-l>I<directory>
+
+Prepend
+I<directory>
+to the list of directories to search for private shared libraries
+(since dpkg 1.17.0).
+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<-d>I<dependency-field>
+
+Add dependencies to be added to the control file dependency field
+I<dependency-field>.
+(The dependencies for this field are placed in the variable
+B<shlibs:>I<dependency-field>.)
+
+The
+B<-d>I<dependency-field>
+option takes effect for all executables after the option, until the
+next
+B<-d>I<dependency-field>.
+The default
+I<dependency-field>
+is
+B<Depends>.
+
+If the same dependency entry (or set of alternatives) appears in more
+than one of the recognized dependency field names
+B<Pre-Depends>, B<Depends>, B<Recommends>, B<Enhances> or B<Suggests>
+then
+B<dpkg-shlibdeps>
+will automatically remove the dependency from all fields except the
+one representing the most important dependencies.
+
+=item B<-p>I<varname-prefix>
+
+Start substitution variables with
+I<varname-prefix>B<:>
+instead of
+B<shlibs:>.
+Likewise, any existing substitution variables starting with
+I<varname-prefix>B<:>
+(rather than
+B<shlibs:>)
+are removed from the substitution variables file.
+
+=item B<-O>[I<filename>]
+
+Print substitution variable settings to standard output (or I<filename>
+if specified, since dpkg 1.17.2), rather than being added to the
+substitution variables file
+(B<debian/substvars>
+by default).
+
+=item B<-t>I<type>
+
+Prefer shared library dependency information tagged for the given
+package type.
+If no tagged information is available, falls back to untagged information.
+The default package type is B<deb>.
+Shared library dependency
+information is tagged for a given type by prefixing it with the name of the
+type, a colon, and whitespace.
+
+=item B<-L>I<local-shlibs-file>
+
+Read overriding shared library dependency information from
+I<local-shlibs-file>
+instead of
+B<debian/shlibs.local>.
+
+=item B<-T>I<substvars-file>
+
+Write substitution variables in
+I<substvars-file>;
+the default is
+B<debian/substvars>.
+
+=item B<-v>
+
+Enable verbose mode (since dpkg 1.14.8).
+Numerous messages are displayed to explain what
+B<dpkg-shlibdeps>
+does.
+
+=item B<-x>I<package>
+
+Exclude the package from the generated dependencies (since dpkg 1.14.8).
+This is useful to
+avoid self-dependencies for packages which provide ELF binaries
+(executables or library plugins) using a library contained in the same
+package.
+This option can be used multiple times to exclude several
+packages.
+
+=item B<-S>I<package-build-dir>
+
+Look into I<package-build-dir> first when trying to find a library
+(since dpkg 1.14.15).
+This is
+useful when the source package builds multiple flavors of the same library
+and you want to ensure that you get the dependency from a given binary
+package.
+You can use this option multiple times: directories will be
+tried in the same order before directories of other binary packages.
+
+=item B<-I>I<package-build-dir>
+
+Ignore I<package-build-dir> when looking for shlibs, symbols, and shared
+library files (since dpkg 1.18.5).
+You can use this option multiple times.
+
+=item B<--ignore-missing-info>
+
+Do not fail if dependency information can't be found for a shared library
+(since dpkg 1.14.8).
+Usage of this option is discouraged, all libraries should provide
+dependency information (either with shlibs files, or with symbols files)
+even if they are not yet used by other packages.
+
+=item B<--warnings=>I<value>
+
+I<value> is a bit field defining the set of warnings that
+can be emitted by B<dpkg-shlibdeps> (since dpkg 1.14.17).
+Bit 0 (value=1) enables the warning “symbol I<sym> used by I<binary>
+found in none of the libraries”, bit 1 (value=2) enables the warning
+“package could avoid a useless dependency” and bit 2 (value=4) enables
+the warning “I<binary> should not be linked against I<library>”.
+The default I<value> is 3: the first two warnings are active by
+default, the last one is not.
+Set I<value> to 7 if you want all
+warnings to be active.
+
+=item B<--admindir=>I<dir>
+
+Change the location of the B<dpkg> database (since dpkg 1.14.0).
+The default location is I<%ADMINDIR%>.
+
+=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_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 DIAGNOSTICS
+
+=head2 Warnings
+
+Since
+B<dpkg-shlibdeps>
+analyzes the set of symbols used by each binary of the generated package,
+it is able to emit warnings in several cases.
+They inform you of things that can be improved in the package.
+In most cases, those improvements concern the upstream sources directly.
+By order of decreasing importance,
+here are the various warnings that you can encounter:
+
+=over
+
+=item B<symbol> I<sym> B<used by> I<binary> B<found in none of the libraries.>
+
+The indicated symbol has not been found in the libraries linked with the
+binary.
+The I<binary> is most likely a library and it needs to be linked
+with an additional library during the build process (option
+B<-l>I<library> of the linker).
+
+=item I<binary> B<contains an unresolvable reference to symbol> I<sym>B<: it's probably a plugin>
+
+The indicated symbol has not been found in the libraries linked with the
+binary.
+The I<binary> is most likely a plugin and the symbol is probably provided
+by the program that loads this plugin.
+In theory a
+plugin doesn't have any SONAME but this binary does have one and as such
+it could not be clearly identified as such.
+However the fact that the
+binary is stored in a non-public directory is a strong indication
+that's it's not a normal shared library.
+If the binary is really a plugin, then disregard this warning.
+But there's always the possibility
+that it's a real library and that programs linking to it are using an
+RPATH so that the dynamic loader finds it.
+In that case, the library is
+broken and needs to be fixed.
+
+=item B<package could avoid a useless dependency if> I<binary> B<was not linked against> I<library> B<(it uses none of the library's symbols)>
+
+None of the I<binaries> that are linked with I<library> use any of the
+symbols provided by the library.
+By fixing all the binaries, you would avoid
+the dependency associated to this library (unless the same dependency is
+also generated by another library that is really used).
+
+=item B<package could avoid a useless dependency if> I<binaries> B<were not linked against> I<library> B<(they use none of the library's symbols)>
+
+Exactly the same as the above warning, but for multiple binaries.
+
+=item I<binary> B<should not be linked against> I<library> B<(it uses none of the library's symbols)>
+
+The I<binary> is linked to a library that it doesn't need.
+It's not a
+problem but some small performance improvements in binary load time can be
+obtained by not linking this library to this binary.
+This warning checks
+the same information as the previous one but does it for each binary
+instead of doing the check globally on all binaries analyzed.
+
+=back
+
+=head2 Errors
+
+B<dpkg-shlibdeps>
+will fail if it can't find a public library used by a binary or if this
+library has no associated dependency information (either shlibs file or
+symbols file).
+A public library has a SONAME and is versioned (libsomething.so.I<X>).
+A private library (like a plugin) should not
+have a SONAME and doesn't need to be versioned.
+
+=over
+
+=item B<couldn't find library> I<library-soname> B<needed by> I<binary> B<(its RPATH is '>I<rpath>B<')>
+
+The I<binary> uses a library called I<library-soname> but
+B<dpkg-shlibdeps>
+has been unable to find the library.
+B<dpkg-shlibdeps>
+creates a list of directories to check as following: directories listed in
+the RPATH of the binary, directories added by the B<-l> option, directories
+listed in the B<LD_LIBRARY_PATH> environment variable, cross multiarch
+directories (ex. /lib/arm64-linux-gnu, /usr/lib/arm64-linux-gnu), standard
+public directories (/lib, /usr/lib), directories listed in /etc/ld.so.conf,
+and obsolete multilib directories (/lib32, /usr/lib32, /lib64, /usr/lib64).
+Then it checks those directories in the package's build tree
+of the binary being analyzed, in the packages' build trees indicated with
+the B<-S> command-line option, in other packages' build trees that contains
+a DEBIAN/shlibs or DEBIAN/symbols file and finally in the root directory.
+If the library is not found in any of those directories, then you get this
+error.
+
+If the library not found is in a private directory of the same package,
+then you want to add the directory with B<-l>.
+If it's in another
+binary package being built, you want to make sure that the shlibs/symbols
+file of this package is already created and that B<-l>
+contains the appropriate directory if it also is in a private directory.
+
+=item B<no dependency information found for> I<library-file> B<(used by> I<binary>B<).>
+
+The library needed by I<binary> has been found by
+B<dpkg-shlibdeps>
+in I<library-file> but
+B<dpkg-shlibdeps>
+has been unable to find any dependency information for that library.
+To
+find out the dependency, it has tried to map the library to a Debian
+package with the help of
+B<dpkg -S> I<library-file>.
+Then it checked the corresponding shlibs and symbols files in
+%ADMINDIR%/info/, and in the various package's build trees
+(debian/*/DEBIAN/).
+
+This failure can be caused by a bad or missing shlibs or symbols file
+in the package of the library.
+It might also happen if the library is
+built within the same source package and if the shlibs files has not yet
+been created (in which case you must fix debian/rules to create
+the shlibs before calling B<dpkg-shlibdeps>).
+Bad RPATH can also
+lead to the library being found under a non-canonical name (example:
+/usr/lib/openoffice.org/../lib/libssl.so.0.9.8 instead of
+/usr/lib/libssl.so.0.9.8) that's not associated to any package,
+B<dpkg-shlibdeps>
+tries to work around this by trying to fallback on a canonical name (using
+L<realpath(3)>)
+but it might not always work.
+It's always best to clean up the RPATH
+of the binary to avoid problems.
+
+Calling
+B<dpkg-shlibdeps>
+in verbose mode (B<-v>) will provide much more information about where it
+tried to find the dependency information.
+This might be useful if you
+don't understand why it's giving you this error.
+
+=back
+
+=head1 SEE ALSO
+
+L<deb-substvars(5)>,
+L<deb-shlibs(5)>,
+L<deb-symbols(5)>,
+L<dpkg-gensymbols(1)>.