(debian-policy.info)Generating dependencies on shared libraries

---

Next: Shared library ABI changes Up: Dependencies between the library and other packages

---

Enter node , (file) or (file)node

8.6.1 Generating dependencies on shared libraries
-------------------------------------------------

When a package that contains any shared libraries or compiled binaries
is built, it must run ‘dpkg-shlibdeps’ on each shared library and
compiled binary to determine the libraries used and hence the
dependencies needed by the package.  (1) To do this, put a call to
‘dpkg-shlibdeps’ into your ‘debian/rules’ file in the source package.
List all of the compiled binaries, libraries, or loadable modules in
your package.  (2) ‘dpkg-shlibdeps’ will use the ‘symbols’ or ‘shlibs’
files installed by the shared libraries to generate dependency
information.  The package must then provide a substitution variable into
which the discovered dependency information can be placed.

If you are creating a udeb for use in the Debian Installer, you will
need to specify that ‘dpkg-shlibdeps’ should use the dependency line of
type ‘udeb’ by adding the ‘-tudeb’ option.  (3) If there is no
dependency line of type ‘udeb’ in the ‘shlibs’ file, ‘dpkg-shlibdeps’
will fall back to the regular dependency line.

‘dpkg-shlibdeps’ puts the dependency information into the
‘debian/substvars’ file by default, which is then used by
‘dpkg-gencontrol’.  You will need to place a ‘${shlibs:Depends}’
variable in the ‘Depends’ field in the control file of every binary
package built by this source package that contains compiled binaries,
libraries, or loadable modules.  If you have multiple binary packages,
you will need to call ‘dpkg-shlibdeps’ on each one which contains
compiled libraries or binaries.  For example, you could use the ‘-T’
option to the ‘dpkg’ utilities to specify a different ‘substvars’ file
for each binary package.  (4)

For more details on ‘dpkg-shlibdeps’, see its manual page.

We say that a binary ‘foo’ `directly' uses a library ‘libbar’ if it is
explicitly linked with that library (that is, the library is listed in
the ELF ‘NEEDED’ attribute, caused by adding ‘-lbar’ to the link line
when the binary is created).  Other libraries that are needed by
‘libbar’ are linked `indirectly' to ‘foo’, and the dynamic linker will
load them automatically when it loads ‘libbar’.  A package should depend
on the libraries it directly uses, but not the libraries it only uses
indirectly.  The dependencies for the libraries used directly will
automatically pull in the indirectly-used libraries.  ‘dpkg-shlibdeps’
will handle this logic automatically, but package maintainers need to be
aware of this distinction between directly and indirectly using a
library if they have to override its results for some reason.  (5)

   ---------- Footnotes ----------

   (1) ‘dpkg-shlibdeps’ will use a program like ‘objdump’ or ‘readelf’
to find the libraries and the symbols in those libraries directly needed
by the binaries or shared libraries in the package.

   (2) The easiest way to call ‘dpkg-shlibdeps’ correctly is to use a
package helper framework such as debhelper.  If you are using debhelper,
the ‘dh_shlibdeps’ program will do this work for you.  It will also
correctly handle multi-binary packages.

   (3) ‘dh_shlibdeps’ from the ‘debhelper’ suite will automatically add
this option if it knows it is processing a udeb.

   (4) Again, ‘dh_shlibdeps’ and ‘dh_gencontrol’ will handle everything
except the addition of the variable to the control file for you if
you’re using debhelper, including generating separate ‘substvars’ files
for each binary package and calling ‘dpkg-gencontrol’ with the
appropriate flags.

   (5) A good example of where this helps is the following: We could
update ‘libimlib’ with a new version that supports a new revision of a
graphics format called dgf (but retaining the same major version number)
and depends on a new library package libdgf4 instead of the older
libdgf3.  If we used ‘ldd’ to add dependencies for every library
directly or indirectly linked with a binary, every package that uses
‘libimlib’ would need to be recompiled so it would also depend on
libdgf4 in order to retire the older libdgf3 package.  Since
dependencies are only added based on ELF ‘NEEDED’ attribute, packages
using ‘libimlib’ can rely on ‘libimlib’ itself having the dependency on
an appropriate version of ‘libdgf’ and do not need rebuilding.