1dpkg-shlibdeps(1)                 dpkg suite                 dpkg-shlibdeps(1)
2
3
4

NAME

6       dpkg-shlibdeps - generate shared library substvar dependencies
7

SYNOPSIS

9       dpkg-shlibdeps [option...] [-e] executable [option...]
10

DESCRIPTION

12       dpkg-shlibdeps calculates shared library dependencies for executables
13       named in its arguments. The dependencies are added to the substitution
14       variables file debian/substvars as variable names shlibs:dependency-
15       field where dependency-field is a dependency field name. Any other
16       variables starting with shlibs: are removed from the file.
17
18       dpkg-shlibdeps has two possible sources of information to generate
19       dependency information. Either symbols files or shlibs files. For each
20       binary that dpkg-shlibdeps analyzes, it finds out the list of libraries
21       that it's linked with.  Then, for each library, it looks up either the
22       symbols file, or the shlibs file (if the former doesn't exist or if
23       debian/shlibs.local contains the relevant dependency). Both files are
24       supposed to be provided by the library package and should thus be
25       available as /var/lib/dpkg/info/package.symbols or
26       /var/lib/dpkg/info/package.shlibs. The package name is identified in
27       two steps: find the library file on the system (looking in the same
28       directories that ld.so would use), then use dpkg -S library-file to
29       lookup the package providing the library.
30
31   Symbols files
32       Symbols files contain finer-grained dependency information by providing
33       the minimum dependency for each symbol that the library exports. The
34       script tries to find a symbols file associated to a library package in
35       the following places (first match is used):
36
37       debian/*/DEBIAN/symbols
38           Shared library information generated by the current build process
39           that also invoked dpkg-shlibdeps.  They are generated by dpkg-
40           gensymbols(1).  They are only used if the library is found in a
41           package's build tree. The symbols file in that build tree takes
42           precedence over symbols files from other binary packages.
43
44       /etc/dpkg/symbols/package.symbols.arch
45       /etc/dpkg/symbols/package.symbols
46           Per-system overriding shared library dependency information.  arch
47           is the architecture of the current system (obtained by dpkg-
48           architecture -qDEB_HOST_ARCH).
49
50       Output from “dpkg-query --control-path package symbols”
51           Package-provided shared library dependency information.  Unless
52           overridden by --admindir, those files are located in /var/lib/dpkg.
53
54       While scanning the symbols used by all binaries, dpkg-shlibdeps
55       remembers the (biggest) minimal version needed for each library. At the
56       end of the process, it is able to write out the minimal dependency for
57       every library used (provided that the information of the symbols files
58       are accurate).
59
60       As a safe-guard measure, a symbols file can provide a Build-Depends-
61       Package meta-information field and dpkg-shlibdeps will extract the
62       minimal version required by the corresponding package in the Build-
63       Depends field and use this version if it's higher than the minimal
64       version computed by scanning symbols.
65
66   Shlibs files
67       Shlibs files associate directly a library to a dependency (without
68       looking at the symbols). It's thus often stronger than really needed
69       but very safe and easy to handle.
70
71       The dependencies for a library are looked up in several places. The
72       first file providing information for the library of interest is used:
73
74       debian/shlibs.local
75           Package-local overriding shared library dependency information.
76
77       /etc/dpkg/shlibs.override
78           Per-system overriding shared library dependency information.
79
80       debian/*/DEBIAN/shlibs
81           Shared library information generated by the current build process
82           that also invoked dpkg-shlibdeps.  They are only used if the
83           library is found in a package's build tree. The shlibs file in that
84           build tree takes precedence over shlibs files from other binary
85           packages.
86
87       Output from “dpkg-query --control-path package shlibs”
88           Package-provided shared library dependency information.  Unless
89           overridden by --admindir, those files are located in /var/lib/dpkg.
90
91       /etc/dpkg/shlibs.default
92           Per-system default shared library dependency information.
93
94       The extracted dependencies are then directly used (except if they are
95       filtered out because they have been identified as duplicate, or as
96       weaker than another dependency).
97

OPTIONS

99       dpkg-shlibdeps interprets non-option arguments as executable names,
100       just as if they'd been supplied as -eexecutable.
101
102       -eexecutable
103           Include dependencies appropriate for the shared libraries required
104           by executable.  This option can be used multiple times.
105
106       -ldirectory
107           Prepend directory to the list of directories to search for private
108           shared libraries (since dpkg 1.17.0). This option can be used
109           multiple times.
110
111           Note: Use this option instead of setting LD_LIBRARY_PATH, as that
112           environment variable is used to control the run-time linker and
113           abusing it to set the shared library paths at build-time can be
114           problematic when cross-compiling for example.
115
116       -ddependency-field
117           Add dependencies to be added to the control file dependency field
118           dependency-field.  (The dependencies for this field are placed in
119           the variable shlibs:dependency-field.)
120
121           The -ddependency-field option takes effect for all executables
122           after the option, until the next -ddependency-field.  The default
123           dependency-field is Depends.
124
125           If the same dependency entry (or set of alternatives) appears in
126           more than one of the recognized dependency field names Pre-Depends,
127           Depends, Recommends, Enhances or Suggests then dpkg-shlibdeps will
128           automatically remove the dependency from all fields except the one
129           representing the most important dependencies.
130
131       -pvarname-prefix
132           Start substitution variables with varname-prefix: instead of
133           shlibs:.  Likewise, any existing substitution variables starting
134           with varname-prefix: (rather than shlibs:) are removed from the
135           substitution variables file.
136
137       -O[filename]
138           Print substitution variable settings to standard output (or
139           filename if specified, since dpkg 1.17.2), rather than being added
140           to the substitution variables file (debian/substvars by default).
141
142       -ttype
143           Prefer shared library dependency information tagged for the given
144           package type. If no tagged information is available, falls back to
145           untagged information. The default package type is deb. Shared
146           library dependency information is tagged for a given type by
147           prefixing it with the name of the type, a colon, and whitespace.
148
149       -Llocal-shlibs-file
150           Read overriding shared library dependency information from local-
151           shlibs-file instead of debian/shlibs.local.
152
153       -Tsubstvars-file
154           Write substitution variables in substvars-file; the default is
155           debian/substvars.
156
157       -v  Enable verbose mode (since dpkg 1.14.8).  Numerous messages are
158           displayed to explain what dpkg-shlibdeps does.
159
160       -xpackage
161           Exclude the package from the generated dependencies (since dpkg
162           1.14.8).  This is useful to avoid self-dependencies for packages
163           which provide ELF binaries (executables or library plugins) using a
164           library contained in the same package. This option can be used
165           multiple times to exclude several packages.
166
167       -Spackage-build-dir
168           Look into package-build-dir first when trying to find a library
169           (since dpkg 1.14.15).  This is useful when the source package
170           builds multiple flavors of the same library and you want to ensure
171           that you get the dependency from a given binary package. You can
172           use this option multiple times: directories will be tried in the
173           same order before directories of other binary packages.
174
175       -Ipackage-build-dir
176           Ignore package-build-dir when looking for shlibs, symbols, and
177           shared library files (since dpkg 1.18.5).  You can use this option
178           multiple times.
179
180       --ignore-missing-info
181           Do not fail if dependency information can't be found for a shared
182           library (since dpkg 1.14.8).  Usage of this option is discouraged,
183           all libraries should provide dependency information (either with
184           shlibs files, or with symbols files) even if they are not yet used
185           by other packages.
186
187       --warnings=value
188           value is a bit field defining the set of warnings that can be
189           emitted by dpkg-shlibdeps (since dpkg 1.14.17).  Bit 0 (value=1)
190           enables the warning “symbol sym used by binary found in none of the
191           libraries”, bit 1 (value=2) enables the warning “package could
192           avoid a useless dependency” and bit 2 (value=4) enables the warning
193binary should not be linked against library”.  The default value
194           is 3: the first two warnings are active by default, the last one is
195           not. Set value to 7 if you want all warnings to be active.
196
197       --admindir=dir
198           Change the location of the dpkg database (since dpkg 1.14.0).  The
199           default location is /var/lib/dpkg.
200
201       -?, --help
202           Show the usage message and exit.
203
204       --version
205           Show the version and exit.
206

ENVIRONMENT

208       DPKG_COLORS
209           Sets the color mode (since dpkg 1.18.5).  The currently accepted
210           values are: auto (default), always and never.
211
212       DPKG_NLS
213           If set, it will be used to decide whether to activate Native
214           Language Support, also known as internationalization (or i18n)
215           support (since dpkg 1.19.0).  The accepted values are: 0 and 1
216           (default).
217

DIAGNOSTICS

219   Warnings
220       Since dpkg-shlibdeps analyzes the set of symbols used by each binary of
221       the generated package, it is able to emit warnings in several cases.
222       They inform you of things that can be improved in the package. In most
223       cases, those improvements concern the upstream sources directly. By
224       order of decreasing importance, here are the various warnings that you
225       can encounter:
226
227       symbol sym used by binary found in none of the libraries.
228           The indicated symbol has not been found in the libraries linked
229           with the binary. The binary is most likely a library and it needs
230           to be linked with an additional library during the build process
231           (option -llibrary of the linker).
232
233       binary contains an unresolvable reference to symbol sym: it's probably
234       a plugin
235           The indicated symbol has not been found in the libraries linked
236           with the binary. The binary is most likely a plugin and the symbol
237           is probably provided by the program that loads this plugin. In
238           theory a plugin doesn't have any SONAME but this binary does have
239           one and as such it could not be clearly identified as such. However
240           the fact that the binary is stored in a non-public directory is a
241           strong indication that's it's not a normal shared library. If the
242           binary is really a plugin, then disregard this warning. But there's
243           always the possibility that it's a real library and that programs
244           linking to it are using an RPATH so that the dynamic loader finds
245           it. In that case, the library is broken and needs to be fixed.
246
247       package could avoid a useless dependency if binary was not linked
248       against library (it uses none of the library's symbols)
249           None of the binaries that are linked with library use any of the
250           symbols provided by the library. By fixing all the binaries, you
251           would avoid the dependency associated to this library (unless the
252           same dependency is also generated by another library that is really
253           used).
254
255       package could avoid a useless dependency if binaries were not linked
256       against library (they use none of the library's symbols)
257           Exactly the same as the above warning, but for multiple binaries.
258
259       binary should not be linked against library (it uses none of the
260       library's symbols)
261           The binary is linked to a library that it doesn't need. It's not a
262           problem but some small performance improvements in binary load time
263           can be obtained by not linking this library to this binary. This
264           warning checks the same information as the previous one but does it
265           for each binary instead of doing the check globally on all binaries
266           analyzed.
267
268   Errors
269       dpkg-shlibdeps will fail if it can't find a public library used by a
270       binary or if this library has no associated dependency information
271       (either shlibs file or symbols file). A public library has a SONAME and
272       is versioned (libsomething.so.X). A private library (like a plugin)
273       should not have a SONAME and doesn't need to be versioned.
274
275       couldn't find library library-soname needed by binary (its RPATH is
276       'rpath')
277           The binary uses a library called library-soname but dpkg-shlibdeps
278           has been unable to find the library.  dpkg-shlibdeps creates a list
279           of directories to check as following: directories listed in the
280           RPATH of the binary, directories added by the -l option,
281           directories listed in the LD_LIBRARY_PATH environment variable,
282           cross multiarch directories (ex. /lib/arm64-linux-gnu,
283           /usr/lib/arm64-linux-gnu), standard public directories (/lib,
284           /usr/lib), directories listed in /etc/ld.so.conf, and obsolete
285           multilib directories (/lib32, /usr/lib32, /lib64, /usr/lib64).
286           Then it checks those directories in the package's build tree of the
287           binary being analyzed, in the packages' build trees indicated with
288           the -S command-line option, in other packages' build trees that
289           contains a DEBIAN/shlibs or DEBIAN/symbols file and finally in the
290           root directory.  If the library is not found in any of those
291           directories, then you get this error.
292
293           If the library not found is in a private directory of the same
294           package, then you want to add the directory with -l. If it's in
295           another binary package being built, you want to make sure that the
296           shlibs/symbols file of this package is already created and that -l
297           contains the appropriate directory if it also is in a private
298           directory.
299
300       no dependency information found for library-file (used by binary).
301           The library needed by binary has been found by dpkg-shlibdeps in
302           library-file but dpkg-shlibdeps has been unable to find any
303           dependency information for that library. To find out the
304           dependency, it has tried to map the library to a Debian package
305           with the help of dpkg -S library-file.  Then it checked the
306           corresponding shlibs and symbols files in /var/lib/dpkg/info/, and
307           in the various package's build trees (debian/*/DEBIAN/).
308
309           This failure can be caused by a bad or missing shlibs or symbols
310           file in the package of the library. It might also happen if the
311           library is built within the same source package and if the shlibs
312           files has not yet been created (in which case you must fix
313           debian/rules to create the shlibs before calling dpkg-shlibdeps).
314           Bad RPATH can also lead to the library being found under a non-
315           canonical name (example:
316           /usr/lib/openoffice.org/../lib/libssl.so.0.9.8 instead of
317           /usr/lib/libssl.so.0.9.8) that's not associated to any package,
318           dpkg-shlibdeps tries to work around this by trying to fallback on a
319           canonical name (using realpath(3)) but it might not always work.
320           It's always best to clean up the RPATH of the binary to avoid
321           problems.
322
323           Calling dpkg-shlibdeps in verbose mode (-v) will provide much more
324           information about where it tried to find the dependency
325           information. This might be useful if you don't understand why it's
326           giving you this error.
327

SEE ALSO

329       deb-shlibs(5), deb-symbols(5), dpkg-gensymbols(1).
330
331
332
3331.20.9                            2021-04-13                 dpkg-shlibdeps(1)
Impressum