unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

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



NAME
       dpkg-shlibdeps - generate shared library substvar dependencies

SYNOPSIS
       dpkg-shlibdeps [options] executable|-eexecutable [options]

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 dependencyfield is a dependency field name. Any other vari-
       ables starting 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). 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).

       admindir/info/package.symbols
              Package-provided shared library dependency information.   Unless
              overridden, admindir is /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 min-
       imal version required by the corresponding package in the Build-Depends
       field and use this version if it's higher than the minimal version com-
       puted 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 informations 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.

       admindir/info/package.shlibs
              Package-provided shared library dependency information.   Unless
              overridden, admindir is /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.

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

              The  -ddependencyfield  option  takes effect for all executables
              after the option, until the next -ddependencyfield.  The default
              dependencyfield is Depends.

              If the same dependency entry (or set of alternatives) appears in
              more  than  one  of  the  recognised  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.

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

       -O     Print  substitution variable settings to standard output, rather
              than being added to the substitution variables file (debian/sub-
              stvars 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.

       -Llocalshlibsfile
              Read  overriding  shared  library  dependency  information  from
              localshlibsfile instead of debian/shlibs.local.

       -Tsubstvarsfile
              Write  substitution  variables  in substvarsfile; 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.

       -Spkgbuilddir
              Look  into pkgbuilddir 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 direc-
              tories 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 "dependency on library could be
              avoided"  and  bit  2  (value=4)  enables  the  warning  "binary
              shouldn't  be linked with 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.

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

       --version
              Show the version and exit.

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

       dependency on library could be avoided if binaries were  not  uselessly
       linked against it (they use none of its 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).

       binary shouldn't be linked with library (it uses none of its 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 listed in the LD_LIBRARY_PATH envi-
              ronment  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's build trees indicated
              with the -S command-line option, in other packages's 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 to  LD_LIBRARY_PATH.
              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 LD_LIBRARY_PATH contains the appropriate direc-
              tory 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/gcc/i486-linux-
              gnu/4.2.3/../../../../lib/libssl.so.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).

AUTHORS
       Copyright (C) 1995-1996 Ian Jackson
       Copyright (C) 2000 Wichert Akkerman
       Copyright (C) 2006 Frank Lichtenheld
       Copyright (C) 2007-2008 Raphal Hertzog

       This  is free software; see the GNU General Public Licence version 2 or
       later for copying conditions. There is NO WARRANTY.



Debian Project                    2008-03-25                 dpkg-shlibdeps(1)