548 lines
17 KiB
Text
548 lines
17 KiB
Text
# 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> or B<Build-Depends-Packages> 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<--package=>I<package>
|
|
|
|
Define the package name.
|
|
|
|
When specified,
|
|
the package name will be used to change defaults based on the
|
|
binary package metadata in F<debian/control>.
|
|
|
|
If the package is B<Essential: yes>,
|
|
then the default dependency field is B<Pre-Depends>, otherwise B<Depends>.
|
|
The default package type is set from the B<Package-Type> field.
|
|
The package is added to the set of packages excluded by B<-x>.
|
|
|
|
Option supported since dpkg 1.22.7.
|
|
|
|
=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<string>[,...]]
|
|
|
|
Select the set of warnings that can be emitted by B<dpkg-shlibdeps>
|
|
(since dpkg 1.14.17).
|
|
|
|
The warnings can be selected from a comma-separated list of symbolic
|
|
names (since dpkg 1.22.12),
|
|
or from a I<value> denoting a bit field for these warnings.
|
|
|
|
=over
|
|
|
|
=item symbol-not-found (bit 0, value 1)
|
|
|
|
Selects the warning “symbol I<sym> used by I<binary> found in none of the
|
|
libraries”.
|
|
|
|
Enabled by default.
|
|
|
|
=item avoidable-dependency (bit 1, value 2)
|
|
|
|
Selects the warning “package could avoid a useless dependency”.
|
|
|
|
Enabled by default.
|
|
|
|
=item useless-linkage (bit 2, value 4)
|
|
|
|
Select the warning “I<binary> should not be linked against I<library>”.
|
|
|
|
=back
|
|
|
|
=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<DEB_HOST_ARCH>
|
|
|
|
Sets the host architecture.
|
|
This affects the objects and symbols files searched for and
|
|
their default search pathnames.
|
|
|
|
=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)>.
|