dpkg-shlibdeps(1)               dpkg utilities               dpkg-shlibdeps(1)



NAME
       dpkg-shlibdeps - generate shared library substvar dependencies

SYNOPSIS
       dpkg-shlibdeps [option...] [-e]executable [option...]

DESCRIPTION
       dpkg-shlibdeps  calculates  shared library dependencies for executables
       named in its arguments. The dependencies are added to the  substitution
       variables  file  debian/substvars  as variable names shlibs:dependency-
       field where dependency-field is a  dependency  field  name.  Any  other
       variables starting with shlibs: are removed from the file.

       dpkg-shlibdeps  has  two  possible  sources  of information to generate
       dependency information. Either symbols files or shlibs files. For  each
       binary that dpkg-shlibdeps analyzes, it finds out the list of libraries
       that it's linked with.  Then, for each library, it looks up either  the
       symbols  file,  or  the  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        /var/lib/dpkg/info/package.symbols        or
       /var/lib/dpkg/info/package.shlibs.  The  package  name is identified in
       two steps: find the library file on the system  (looking  in  the  same
       directories  that  ld.so  would  use), then use dpkg -S library-file to
       lookup the package providing the library.

   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):

       debian/*/DEBIAN/symbols
              Shared  library  information  generated  by  the  current  build
              process that also invoked dpkg-shlibdeps.  They are generated by
              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.

       /etc/dpkg/symbols/package.symbols.arch

       /etc/dpkg/symbols/package.symbols
              Per-system  overriding  shared  library  dependency information.
              arch is the architecture of  the  current  system  (obtained  by
              dpkg-architecture -qDEB_HOST_ARCH).

       Output from "dpkg-query --control-path package symbols"
              Package-provided  shared library dependency information.  Unless
              overridden  by  --admindir,   those   files   are   located   in
              /var/lib/dpkg.

       While  scanning the symbols used by all binaries, dpkg-shlibdeps remem-
       bers 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 symbols  files
       are accurate).

       As   a   safe-guard   measure,   a   symbols   file   can   provide   a
       Build-Depends-Package meta-information field  and  dpkg-shlibdeps  will
       extract  the  minimal  version required by the corresponding package in
       the Build-Depends field and use this version if it's  higher  than  the
       minimal version computed by scanning symbols.

   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:

       debian/shlibs.local
              Package-local overriding shared library dependency information.

       /etc/dpkg/shlibs.override
              Per-system overriding shared library dependency information.

       debian/*/DEBIAN/shlibs
              Shared  library  information  generated  by  the  current  build
              process that also invoked 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.

       Output from "dpkg-query --control-path package shlibs"
              Package-provided shared library dependency information.   Unless
              overridden   by   --admindir,   those   files   are  located  in
              /var/lib/dpkg.

       /etc/dpkg/shlibs.default
              Per-system default shared library dependency information.

       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).

OPTIONS
       dpkg-shlibdeps interprets non-option  arguments  as  executable  names,
       just as if they'd been supplied as -eexecutable.

       -eexecutable
              Include   dependencies  appropriate  for  the  shared  libraries
              required by executable.  This option can be used multiple times.

       -ldirectory
              Add directory to the list of directories to search  for  private
              shared  libraries  (since  dpkg 1.17.0). This option can be used
              multiple times.

              Note: Use this option instead  of  setting  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.

       -ddependency-field
              Add  dependencies  to  be  added  to the control file dependency
              field dependency-field.  (The dependencies for  this  field  are
              placed in the variable shlibs:dependency-field.)

              The  -ddependency-field  option takes effect for all executables
              after  the  option,  until  the  next  -ddependency-field.   The
              default dependency-field is Depends.

              If the same dependency entry (or set of alternatives) appears in
              more  than  one  of  the  recognized  dependency   field   names
              Pre-Depends,  Depends,  Recommends,  Enhances  or  Suggests then
              dpkg-shlibdeps will automatically remove the dependency from all
              fields  except the one representing the most important dependen-
              cies.

       -pvarname-prefix
              Start substitution variables  with  varname-prefix:  instead  of
              shlibs:.  Likewise, any existing substitution variables starting
              with varname-prefix: (rather than shlibs:) are removed from  the
              the substitution variables file.

       -O[filename]
              Print  substitution  variable  settings  to  standard output (or
              filename if specified), rather than being added to the substitu-
              tion variables file (debian/substvars by default).

       -ttype 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 "deb".
              Shared library dependency information is tagged for a given type
              by  prefixing  it with the name of the type, a colon, and white-
              space.

       -Llocal-shlibs-file
              Read  overriding  shared  library  dependency  information  from
              local-shlibs-file instead of debian/shlibs.local.

       -Tsubstvars-file
              Write  substitution  variables in substvars-file; the default is
              debian/substvars.

       -v     Enable verbose mode. Numerous messages are displayed to  explain
              what dpkg-shlibdeps does.

       -xpackage
              Exclude  the  package  from  the generated dependencies. This is
              useful to avoid self-dependencies for packages which provide ELF
              binaries  (executables  or library plugins) using a library con-
              tained in the same package. This option  can  be  used  multiple
              times to exclude several packages.

       -Spackage-build-dir
              Look into package-build-dir first when trying to find a library.
              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.

       --ignore-missing-info
              Do not fail if dependency  information  can't  be  found  for  a
              shared  library.   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.

       --warnings=value
              value is a bit field defining the set of warnings  that  can  be
              emitted  by dpkg-shlibdeps.  Bit 0 (value=1) enables the warning
              "symbol sym used by 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  "binary
              should  not be linked against library".  The default value is 3:
              the first two warnings are active by default, the  last  one  is
              not. Set value to 7 if you want all warnings to be active.

       --admindir=dir
              Change  the  location of the dpkg database. The default location
              is /var/lib/dpkg.

       -?, --help
              Show the usage message and exit.

       --version
              Show the version and exit.

DIAGNOSTICS
   Warnings
       Since 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:

       symbol sym used by binary found in none of the libraries.
              The  indicated symbol has not been found in the libraries linked
              with the binary. The binary is most  likely  a  library  and  it
              needs  to  be linked with an additional library during the build
              process (option -llibrary of the linker).

       binary contains an unresolvable reference to symbol sym: it's  probably
       a plugin
              The  indicated symbol has not been found in the libraries linked
              with the binary. The binary is most likely a plugin and the sym-
              bol  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.

       package could avoid a useless  dependency  if  binary  was  not  linked
       against library (it uses none of the library's symbols)
              None of the binaries that are linked with 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).

       package  could  avoid  a useless dependency if binaries were not linked
       against library (they uses none of the library's symbols)
              Exactly the same as the above warning, but  for  multiple  bina-
              ries.

       binary  should  not  be  linked  against  library  (it uses none of the
       library's symbols)
              The 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 than the previous one
              but does it for each binary instead of doing the check  globally
              on all binaries analyzed.

   Errors
       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.X). A private  library  (like  a  plugin)
       should not have a SONAME and doesn't need to be versioned.

       couldn't  find  library  library-soname  needed by binary (its RPATH is
       'rpath')
              The binary uses a library called library-soname but  dpkg-shlib-
              deps  has  been unable to find the library.  dpkg-shlibdeps cre-
              ates a list of directories to check  as  following:  directories
              listed  in  the  RPATH  of  the  binary,  directories  listed in
              /etc/ld.so.conf, directories added by the -l option, directories
              listed in the LD_LIBRARY_PATH environment variable, and standard
              public directories (/lib, /usr/lib, /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 -S command-line option, in other pack-
              ages' build trees that contains a DEBIAN/shlibs  or  DEBIAN/sym-
              bols  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 -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 -l contains the appropriate directory if it also  is  in  a
              private directory.

       no dependency information found for library-file (used by binary).
              The library needed by binary has been found by dpkg-shlibdeps in
              library-file but dpkg-shlibdeps has  been  unable  to  find  any
              dependency  information for that library. To find out the depen-
              dency, it has tried to map the library to a Debian package  with
              the  help  of  dpkg -S library-file.  Then it checked the corre-
              sponding shlibs and symbols files in /var/lib/dpkg/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 dpkg-shlib-
              deps). Bad RPATH can also lead to the library being found  under
              a      non-canonical      name      (example:     /usr/lib/open-
              office.org/../lib/libssl.so.0.9.8   instead   of   /usr/lib/lib-
              ssl.so.0.9.8)  that's not associated to any package, dpkg-shlib-
              deps tries to work around this by trying to fallback on a canon-
              ical name (using realpath(3)) but it might not always work. It's
              always best to clean up the RPATH of the binary to  avoid  prob-
              lems.

              Calling  dpkg-shlibdeps  in  verbose mode (-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.

SEE ALSO
       deb-shlibs(5), deb-symbols(5), dpkg-gensymbols(1).



Debian Project                    2013-09-06                 dpkg-shlibdeps(1)
