man/dpkg-shlibdeps.pod

   1 # dpkg manual page - dpkg-deb(1)
   2 #
   3 # Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
   4 # Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
   5 # Copyright © 2006 Frank Lichtenheld <djpig@debian.org>
   6 # Copyright © 2007-2011 Raphaël Hertzog <hertzog@debian.org>
   7 # Copyright © 2011-2013, 2015 Guillem Jover <guillem@debian.org>
   8 #
   9 # This is free software; you can redistribute it and/or modify
  10 # it under the terms of the GNU General Public License as published by
  11 # the Free Software Foundation; either version 2 of the License, or
  12 # (at your option) any later version.
  13 #
  14 # This is distributed in the hope that it will be useful,
  15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 # GNU General Public License for more details.
  18 #
  19 # You should have received a copy of the GNU General Public License
  20 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  21
  22 =encoding utf8
  23
  24 =head1 NAME
  25
  26 dpkg-shlibdeps - generate shared library substvar dependencies
  27
  28 =head1 SYNOPSIS
  29
  30 B<dpkg-shlibdeps>
  31 [I<option>...] [B<-e>] I<executable> [I<option>...]
  32
  33 =head1 DESCRIPTION
  34
  35 B<dpkg-shlibdeps>
  36 calculates shared library dependencies for executables named in its
  37 arguments. The dependencies are added to the substitution
  38 variables file
  39 B<debian/substvars>
  40 as variable names
  41 B<shlibs:>I<dependency-field>
  42 where
  43 I<dependency-field>
  44 is a dependency field name. Any other variables starting with
  45 B<shlibs:>
  46 are removed from the file.
  47
  48 B<dpkg-shlibdeps>
  49 has two possible sources of information to generate dependency
  50 information. Either
  51 I<symbols>
  52 files or
  53 I<shlibs>
  54 files. For each binary that
  55 B<dpkg-shlibdeps>
  56 analyzes, it finds out the list of libraries that it's linked with.
  57 Then, for each library, it looks up either the
  58 I<symbols>
  59 file, or the
  60 I<shlibs>
  61 file (if the former doesn't exist or if debian/shlibs.local contains
  62 the relevant dependency). Both files are supposed to be provided
  63 by the library package and should thus be available as
  64 %ADMINDIR%/info/I<package>.I<symbols>
  65 or %ADMINDIR%/info/I<package>.I<shlibs>. The package name is
  66 identified in two steps: find the library file on the system (looking in
  67 the same directories that B<ld.so> would use), then use
  68 B<dpkg -S> I<library-file>
  69 to lookup the package providing the library.
  70
  71 =head2 Symbols files
  72
  73 Symbols files contain finer-grained dependency information by providing
  74 the minimum dependency for each symbol that the library exports. The
  75 script tries to find a symbols file associated to a library package
  76 in the following places (first match is used):
  77
  78 =over
  79
  80 =item debian/*/DEBIAN/symbols
  81
  82 Shared library information generated by the current build process that also invoked
  83 B<dpkg-shlibdeps>.
  84 They are generated by
  85 B<dpkg-gensymbols>(1).
  86 They are only used if the library is found in a package's build tree. The
  87 symbols file in that build tree takes precedence over symbols files from
  88 other binary packages.
  89
  90 =item %PKGCONFDIR%/symbols/I<package>.symbols.I<arch>
  91
  92 =item %PKGCONFDIR%/symbols/I<package>.symbols
  93
  94 Per-system overriding shared library dependency information.
  95 I<arch> is the architecture of the current system (obtained by
  96 B<dpkg-architecture -qDEB_HOST_ARCH>).
  97
  98 =item Output from “B<dpkg-query --control-path> I<package> symbols”
  99
 100 Package-provided shared library dependency information.
 101 Unless overridden by B<--admindir>, those files are located in
 102 %ADMINDIR%.
 103
 104 =back
 105
 106 While scanning the symbols used by all binaries,
 107 B<dpkg-shlibdeps>
 108 remembers the (biggest) minimal version needed for each library. At the end
 109 of the process, it is able to write out the minimal dependency for every
 110 library used (provided that the information of the I<symbols> files are
 111 accurate).
 112
 113 As a safe-guard measure, a symbols file can provide a
 114 B<Build-Depends-Package> meta-information field and
 115 B<dpkg-shlibdeps>
 116 will extract the minimal version required by the corresponding package in
 117 the B<Build-Depends> field and use this version if it's higher than the
 118 minimal version computed by scanning symbols.
 119
 120 =head2 Shlibs files
 121
 122 Shlibs files associate directly a library to a dependency (without looking
 123 at the symbols). It's thus often stronger than really needed but very safe
 124 and easy to handle.
 125
 126 The dependencies for a library are looked up in several places. The first
 127 file providing information for the library of interest is used:
 128
 129 =over
 130
 131 =item debian/shlibs.local
 132
 133 Package-local overriding shared library dependency information.
 134
 135 =item %PKGCONFDIR%/shlibs.override
 136
 137 Per-system overriding shared library dependency information.
 138
 139 =item debian/*/DEBIAN/shlibs
 140
 141 Shared library information generated by the current build process that also invoked
 142 B<dpkg-shlibdeps>.
 143 They are only used if the library is found in a package's build tree. The
 144 shlibs file in that build tree takes precedence over shlibs files from
 145 other binary packages.
 146
 147 =item Output from “B<dpkg-query --control-path> I<package> shlibs”
 148
 149 Package-provided shared library dependency information.
 150 Unless overridden by B<--admindir>, those files are located in
 151 %ADMINDIR%.
 152
 153 =item %PKGCONFDIR%/shlibs.default
 154
 155 Per-system default shared library dependency information.
 156
 157 =back
 158
 159 The extracted dependencies are then directly used (except if they are
 160 filtered out because they have been identified as duplicate, or as weaker
 161 than another dependency).
 162
 163 =head1 OPTIONS
 164
 165 B<dpkg-shlibdeps>
 166 interprets non-option arguments as executable names, just as if they'd
 167 been supplied as
 168 B<-e>I<executable>.
 169
 170 =over
 171
 172 =item B<-e>I<executable>
 173
 174 Include dependencies appropriate for the shared libraries required by
 175 I<executable>.
 176 This option can be used multiple times.
 177
 178 =item B<-l>I<directory>
 179
 180 Prepend
 181 I<directory>
 182 to the list of directories to search for private shared libraries
 183 (since dpkg 1.17.0). This option can be used multiple times.
 184
 185 B<Note>: Use this option instead of setting B<LD_LIBRARY_PATH>,
 186 as that environment variable is used to control the run-time linker
 187 and abusing it to set the shared library paths at build-time can be
 188 problematic when cross-compiling for example.
 189
 190 =item B<-d>I<dependency-field>
 191
 192 Add dependencies to be added to the control file dependency field
 193 I<dependency-field>.
 194 (The dependencies for this field are placed in the variable
 195 B<shlibs:>I<dependency-field>.)
 196
 197 The
 198 B<-d>I<dependency-field>
 199 option takes effect for all executables after the option, until the
 200 next
 201 B<-d>I<dependency-field>.
 202 The default
 203 I<dependency-field>
 204 is
 205 B<Depends>.
 206
 207 If the same dependency entry (or set of alternatives) appears in more
 208 than one of the recognized dependency field names
 209 B<Pre-Depends>, B<Depends>, B<Recommends>, B<Enhances> or B<Suggests>
 210 then
 211 B<dpkg-shlibdeps>
 212 will automatically remove the dependency from all fields except the
 213 one representing the most important dependencies.
 214
 215 =item B<-p>I<varname-prefix>
 216
 217 Start substitution variables with
 218 I<varname-prefix>B<:>
 219 instead of
 220 B<shlibs:>.
 221 Likewise, any existing substitution variables starting with
 222 I<varname-prefix>B<:>
 223 (rather than
 224 B<shlibs:>)
 225 are removed from the substitution variables file.
 226
 227 =item B<-O>[I<filename>]
 228
 229 Print substitution variable settings to standard output (or I<filename>
 230 if specified, since dpkg 1.17.2), rather than being added to the
 231 substitution variables file
 232 (B<debian/substvars>
 233 by default).
 234
 235 =item B<-t>I<type>
 236
 237 Prefer shared library dependency information tagged for the given
 238 package type. If no tagged information is available, falls back to untagged
 239 information. The default package type is B<deb>. Shared library dependency
 240 information is tagged for a given type by prefixing it with the name of the
 241 type, a colon, and whitespace.
 242
 243 =item B<-L>I<local-shlibs-file>
 244
 245 Read overriding shared library dependency information from
 246 I<local-shlibs-file>
 247 instead of
 248 B<debian/shlibs.local>.
 249
 250 =item B<-T>I<substvars-file>
 251
 252 Write substitution variables in
 253 I<substvars-file>;
 254 the default is
 255 B<debian/substvars>.
 256
 257 =item B<-v>
 258
 259 Enable verbose mode (since dpkg 1.14.8).
 260 Numerous messages are displayed to explain what
 261 B<dpkg-shlibdeps>
 262 does.
 263
 264 =item B<-x>I<package>
 265
 266 Exclude the package from the generated dependencies (since dpkg 1.14.8).
 267 This is useful to
 268 avoid self-dependencies for packages which provide ELF binaries
 269 (executables or library plugins) using a library contained in the same
 270 package. This option can be used multiple times to exclude several
 271 packages.
 272
 273 =item B<-S>I<package-build-dir>
 274
 275 Look into I<package-build-dir> first when trying to find a library
 276 (since dpkg 1.14.15).
 277 This is
 278 useful when the source package builds multiple flavors of the same library
 279 and you want to ensure that you get the dependency from a given binary
 280 package. You can use this option multiple times: directories will be
 281 tried in the same order before directories of other binary packages.
 282
 283 =item B<-I>I<package-build-dir>
 284
 285 Ignore I<package-build-dir> when looking for shlibs, symbols, and shared
 286 library files (since dpkg 1.18.5).
 287 You can use this option multiple times.
 288
 289 =item B<--ignore-missing-info>
 290
 291 Do not fail if dependency information can't be found for a shared library
 292 (since dpkg 1.14.8).
 293 Usage of this option is discouraged, all libraries should provide
 294 dependency information (either with shlibs files, or with symbols files)
 295 even if they are not yet used by other packages.
 296
 297 =item B<--warnings=>I<value>
 298
 299 I<value> is a bit field defining the set of warnings that
 300 can be emitted by B<dpkg-shlibdeps> (since dpkg 1.14.17).
 301 Bit 0 (value=1) enables the warning “symbol I<sym> used by I<binary>
 302 found in none of the libraries”, bit 1 (value=2) enables the warning
 303 “package could avoid a useless dependency” and bit 2 (value=4) enables
 304 the warning “I<binary> should not be linked against I<library>”.
 305 The default I<value> is 3: the first two warnings are active by
 306 default, the last one is not. Set I<value> to 7 if you want all
 307 warnings to be active.
 308
 309 =item B<--admindir=>I<dir>
 310
 311 Change the location of the B<dpkg> database (since dpkg 1.14.0).
 312 The default location is I<%ADMINDIR%>.
 313
 314 =item B<-?>, B<--help>
 315
 316 Show the usage message and exit.
 317
 318 =item B<--version>
 319
 320 Show the version and exit.
 321
 322 =back
 323
 324 =head1 ENVIRONMENT
 325
 326 =over
 327
 328 =item B<DPKG_COLORS>
 329
 330 Sets the color mode (since dpkg 1.18.5).
 331 The currently accepted values are: B<auto> (default), B<always> and
 332 B<never>.
 333
 334 =item B<DPKG_NLS>
 335
 336 If set, it will be used to decide whether to activate Native Language Support,
 337 also known as internationalization (or i18n) support (since dpkg 1.19.0).
 338 The accepted values are: B<0> and B<1> (default).
 339
 340 =back
 341
 342 =head1 DIAGNOSTICS
 343
 344 =head2 Warnings
 345
 346 Since
 347 B<dpkg-shlibdeps>
 348 analyzes the set of symbols used by each binary of the generated package,
 349 it is able to emit warnings in several cases. They inform you of things
 350 that can be improved in the package. In most cases, those improvements
 351 concern the upstream sources directly. By order of decreasing importance,
 352 here are the various warnings that you can encounter:
 353
 354 =over
 355
 356 =item B<symbol> I<sym> B<used by> I<binary> B<found in none of the libraries.>
 357
 358 The indicated symbol has not been found in the libraries linked with the
 359 binary. The I<binary> is most likely a library and it needs to be linked
 360 with an additional library during the build process (option
 361 B<-l>I<library> of the linker).
 362
 363 =item I<binary> B<contains an unresolvable reference to symbol> I<sym>B<: it's probably a plugin>
 364
 365 The indicated symbol has not been found in the libraries linked with the
 366 binary. The I<binary> is most likely a plugin and the symbol is
 367 probably provided by the program that loads this plugin. In theory a
 368 plugin doesn't have any SONAME but this binary does have one and as such
 369 it could not be clearly identified as such. However the fact that the
 370 binary is stored in a non-public directory is a strong indication
 371 that's it's not a normal shared library. If the binary is really a
 372 plugin, then disregard this warning. But there's always the possibility
 373 that it's a real library and that programs linking to it are using an
 374 RPATH so that the dynamic loader finds it. In that case, the library is
 375 broken and needs to be fixed.
 376
 377 =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)>
 378
 379 None of the I<binaries> that are linked with I<library> use any of the
 380 symbols provided by the library. By fixing all the binaries, you would avoid
 381 the dependency associated to this library (unless the same dependency is
 382 also generated by another library that is really used).
 383
 384 =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)>
 385
 386 Exactly the same as the above warning, but for multiple binaries.
 387
 388 =item I<binary> B<should not be linked against> I<library> B<(it uses none of the library's symbols)>
 389
 390 The I<binary> is linked to a library that it doesn't need. It's not a
 391 problem but some small performance improvements in binary load time can be
 392 obtained by not linking this library to this binary. This warning checks
 393 the same information as the previous one but does it for each binary
 394 instead of doing the check globally on all binaries analyzed.
 395
 396 =back
 397
 398 =head2 Errors
 399
 400 B<dpkg-shlibdeps>
 401 will fail if it can't find a public library used by a binary or if this
 402 library has no associated dependency information (either shlibs file or
 403 symbols file). A public library has a SONAME and is versioned
 404 (libsomething.so.I<X>). A private library (like a plugin) should not
 405 have a SONAME and doesn't need to be versioned.
 406
 407 =over
 408
 409 =item B<couldn't find library> I<library-soname> B<needed by> I<binary> B<(its RPATH is '>I<rpath>B<')>
 410
 411 The I<binary> uses a library called I<library-soname> but
 412 B<dpkg-shlibdeps>
 413 has been unable to find the library.
 414 B<dpkg-shlibdeps>
 415 creates a list of directories to check as following: directories listed in
 416 the RPATH of the binary, directories added by the B<-l> option, directories
 417 listed in the B<LD_LIBRARY_PATH> environment variable, cross multiarch
 418 directories (ex. /lib/arm64-linux-gnu, /usr/lib/arm64-linux-gnu), standard
 419 public directories (/lib, /usr/lib), directories listed in /etc/ld.so.conf,
 420 and obsolete multilib directories (/lib32, /usr/lib32, /lib64, /usr/lib64).
 421 Then it checks those directories in the package's build tree
 422 of the binary being analyzed, in the packages' build trees indicated with
 423 the B<-S> command-line option, in other packages' build trees that contains
 424 a DEBIAN/shlibs or DEBIAN/symbols file and finally in the root directory.
 425 If the library is not found in any of those directories, then you get this
 426 error.
 427
 428 If the library not found is in a private directory of the same package,
 429 then you want to add the directory with B<-l>. If it's in another
 430 binary package being built, you want to make sure that the shlibs/symbols
 431 file of this package is already created and that B<-l>
 432 contains the appropriate directory if it also is in a private directory.
 433
 434 =item B<no dependency information found for> I<library-file> B<(used by> I<binary>B<).>
 435
 436 The library needed by I<binary> has been found by
 437 B<dpkg-shlibdeps>
 438 in I<library-file> but
 439 B<dpkg-shlibdeps>
 440 has been unable to find any dependency information for that library. To
 441 find out the dependency, it has tried to map the library to a Debian
 442 package with the help of
 443 B<dpkg -S> I<library-file>.
 444 Then it checked the corresponding shlibs and symbols files in
 445 %ADMINDIR%/info/, and in the various package's build trees
 446 (debian/*/DEBIAN/).
 447
 448 This failure can be caused by a bad or missing shlibs or symbols file
 449 in the package of the library. It might also happen if the library is
 450 built within the same source package and if the shlibs files has not yet
 451 been created (in which case you must fix debian/rules to create
 452 the shlibs before calling B<dpkg-shlibdeps>). Bad RPATH can also
 453 lead to the library being found under a non-canonical name (example:
 454 /usr/lib/openoffice.org/../lib/libssl.so.0.9.8 instead of
 455 /usr/lib/libssl.so.0.9.8) that's not associated to any package,
 456 B<dpkg-shlibdeps>
 457 tries to work around this by trying to fallback on a canonical name (using
 458 B<realpath>(3))
 459 but it might not always work. It's always best to clean up the RPATH
 460 of the binary to avoid problems.
 461
 462 Calling
 463 B<dpkg-shlibdeps>
 464 in verbose mode (B<-v>) will provide much more information about where it
 465 tried to find the dependency information. This might be useful if you
 466 don't understand why it's giving you this error.
 467
 468 =back
 469
 470 =head1 SEE ALSO
 471
 472 B<deb-substvars>(5),
 473 B<deb-shlibs>(5),
 474 B<deb-symbols>(5),
 475 B<dpkg-gensymbols>(1).