search..
No manual entry for -- in section 1
dpkg-shlibdeps(1)		   dpkg suite		      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
       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.

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

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

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

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

       -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 (since  dpkg  1.14.8).	Numerous  messages  are
	   displayed to explain what dpkg-shlibdeps does.

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

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

       -Ipackage-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 /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
	   -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  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 /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.

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

1.22.22				   2026-03-06		      dpkg-shlibdeps(1)