# dpkg-shlibdeps

## 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
           /usr/local/var/lib/dpkg/info/_package_._symbols_ or
           /usr/local/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.
    
           /usr/local/etc/dpkg/symbols/_package_.symbols._arch_
           /usr/local/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
               /usr/local/var/lib/dpkg.
    
           While scanning the symbols used by all binaries, **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 _symbols_ files are accurate).
    
           As a safe-guard measure, a symbols file can provide a
           **Build-Depends-Package** or **Build-Depends-Packages** 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.
    
           /usr/local/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
               /usr/local/var/lib/dpkg.
    
           /usr/local/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 **-e** _executable_.
    
           **-e** _executable_
               Include dependencies appropriate for the shared libraries
               required by _executable_.  This option can be used multiple
               times.
    
           **-l** _directory_
               Prepend _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.
    
           **-d** _dependency-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 **-d** _dependency-field_ option takes effect for all executables
               after the option, until the next **-d** _dependency-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
               dependencies.
    
           **--package=**_package_
               Define the package name.
    
               When specified, the package name will be used to change
               defaults based on the binary package metadata in
               _debian/control_.
    
               If the package is **Essential: yes** , then the default dependency
               field is **Pre-Depends** , otherwise **Depends**.  The default package
               type is set from the **Package-Type** field.  The package is added
               to the set of packages excluded by **-x**.
    
               Option supported since dpkg 1.22.7.
    
           **-p** _varname-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 substitution variables file.
    
           **-O**[_filename_]
               Print substitution variable settings to standard output (or
               _filename_ if specified, since dpkg 1.17.2), rather than being
               added to the substitution variables file (**debian/substvars** by
               default).
    
           **-t** _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 **deb**.  Shared library dependency information is tagged for a
               given type by prefixing it with the name of the type, a colon,
               and whitespace.
    
           **-L** _local-shlibs-file_
               Read overriding shared library dependency information from
               _local-shlibs-file_ instead of **debian/shlibs.local**.
    
           **-T** _substvars-file_
               Write substitution variables in _substvars-file_ ; the default is
               **debian/substvars**.
    
           **-v** Enable verbose mode (since dpkg 1.14.8).  Numerous messages
               are displayed to explain what **dpkg-shlibdeps** does.
    
           **-x** _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.
    
           **-S** _package-build-dir_
               Look into _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.
    
           **-I** _package-build-dir_
               Ignore _package-build-dir_ when looking for shlibs, symbols, and
               shared library files (since dpkg 1.18.5).  You can use this
               option multiple times.
    
           **--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.
    
           **--warnings=**[_value_ |_string_[,...]]
               Select the set of warnings that can be emitted by
               **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 _value_ denoting
               a bit field for these warnings.
    
               symbol-not-found (bit 0, value 1)
                   Selects the warning “symbol _sym_ used by _binary_ found in
                   none of the libraries”.
    
                   Enabled by default.
    
               avoidable-dependency (bit 1, value 2)
                   Selects the warning “package could avoid a useless
                   dependency”.
    
                   Enabled by default.
    
               useless-linkage (bit 2, value 4)
                   Select the warning “ _binary_ should not be linked against
                   _library_ ”.
    
           **--admindir=**_dir_
               Change the location of the **dpkg** database (since dpkg 1.14.0).
               The default location is _/usr/local/var/lib/dpkg_.
    
           **-?** , **--help**
               Show the usage message and exit.
    
           **--version**
               Show the version and exit.
    


## ENVIRONMENT



           **DEB_HOST_ARCH**
               Sets the host architecture.  This affects the objects and
               symbols files searched for and their default search pathnames.
    
           **DPKG_COLORS**
               Sets the color mode (since dpkg 1.18.5).  The currently
               accepted values are: **auto**(default), **always** and **never**.
    
           **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: **0** and **1**
               (default).
    


## 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 **-l** _library_ 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 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.
    
           **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 use none of the library's symbols)**
               Exactly the same as the above warning, but for multiple
               binaries.
    
           _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 as
               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-shlibdeps** has been unable to find the library.
               **dpkg-shlibdeps** creates a list of directories to check as
               following: directories listed in the RPATH of the binary,
               directories added by the **-l** option, directories listed in the
               **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 **-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 **-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
               dependency, it has tried to map the library to a Debian
               package with the help of **dpkg -S** _library-file_.  Then it
               checked the corresponding shlibs and symbols files in
               /usr/local/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-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, **dpkg-shlibdeps** tries to work around this by trying to
               fallback on a canonical name (using realpath(3)) but it might
               not always work.  It's always best to clean up the RPATH of
               the binary to avoid problems.
    
               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.
    


* * *