(debian-policy.info)Run-time shared libraries

---

Next: Shared library support files Up: Shared libraries

---

Enter node , (file) or (file)node

8.1 Run-time shared libraries
=============================

The run-time shared library must be placed in a package whose name
changes whenever the ‘SONAME’ of the shared library changes.  This
allows several versions of the shared library to be installed at the
same time, allowing installation of the new version of the shared
library without immediately breaking binaries that depend on the old
version.  (1)

Normally, the run-time shared library and its ‘SONAME’ symlink should be
placed in a package named libraryname`soversion', where `soversion' is
the version number in the ‘SONAME’ of the shared library.
Alternatively, if it would be confusing to directly append `soversion'
to libraryname (if, for example, libraryname itself ends in a number),
you should use libraryname-`soversion' instead.  (2)

To determine the `soversion', look at the ‘SONAME’ of the library,
stored in the ELF ‘SONAME’ attribute.  It is usually of the form
‘name.so.major-version’ (for example, ‘libz.so.1’).  The version part is
the part which comes after ‘.so.’, so in that example it is ‘1’.  The
soname may instead be of the form ‘name-major-version.so’, such as
‘libdb-5.1.so’, in which case the name would be ‘libdb’ and the version
would be ‘5.1’.

If you have several shared libraries built from the same source tree,
you may lump them all together into a single shared library package
provided that all of their ‘SONAME’s will always change together.  Be
aware that this is not normally the case, and if the ‘SONAME’s do not
change together, upgrading such a merged shared library package will be
unnecessarily difficult because of file conflicts with the old version
of the package.  When in doubt, always split shared library packages so
that each binary package installs a single shared library.

Every time the shared library ABI changes in a way that may break
binaries linked against older versions of the shared library, the
‘SONAME’ of the library and the corresponding name for the binary
package containing the runtime shared library should change.  Normally,
this means the ‘SONAME’ should change any time an interface is removed
from the shared library or the signature of an interface (the number of
parameters or the types of parameters that it takes, for example) is
changed.  This practice is vital to allowing clean upgrades from older
versions of the package and clean transitions between the old ABI and
new ABI without having to upgrade every affected package simultaneously.

The ‘SONAME’ and binary package name need not, and indeed normally
should not, change if new interfaces are added but none are removed or
changed, since this will not break binaries linked against the old
shared library.  Correct versioning of dependencies on the newer shared
library by binaries that use the new interfaces is handled via the
‘symbols’ or ‘shlibs’ system (see Note: Dependencies between the library
and other packages.).

The package should install the shared libraries under their normal
names.  For example, the libgdbm3 package should install
‘libgdbm.so.3.0.0’ as ‘/usr/lib/libgdbm.so.3.0.0’.  The files should not
be renamed or re-linked by any ‘prerm’ or ‘postrm’ scripts; ‘dpkg’ will
take care of renaming things safely without affecting running programs,
and attempts to interfere with this are likely to lead to problems.

Shared libraries should not be installed executable, since the dynamic
linker does not require this and trying to execute a shared library
usually results in a core dump.

The run-time library package should include the symbolic link for the
‘SONAME’ that ‘ldconfig’ would create for the shared libraries.  For
example, the libgdbm3 package should include a symbolic link from
‘/usr/lib/libgdbm.so.3’ to ‘libgdbm.so.3.0.0’.  This is needed so that
the dynamic linker (for example ‘ld.so’ or ‘ld-linux.so.*’) can find the
library between the time that ‘dpkg’ installs it and the time that
‘ldconfig’ is run in the ‘postinst’ script.  (3)

ldconfig

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

   (1) There are some exceptional situations in which co-installation of
two versions of a shared library is not safe, and the new shared library
package has to conflict with the previous shared library package.  This
is never desirable, since it causes significant disruption during
upgrades and potentially breaks unpackaged third-party binaries, but is
sometimes unavoidable.  These situations are sufficiently rare that they
usually warrant project-wide discussion, and are complex enough that the
rules for them cannot be codified in Debian Policy.

   (2) The following command, when run on a shared library, will output
the name to be used for the Debian package containing that shared
library:

     objdump -p /path/to/libfoo-bar.so.1.2.3 \
         | sed -n -e's/^[[:space:]]*SONAME[[:space:]]*//p' \
         | LC_ALL=C sed -r -e's/([0-9])\.so\./\1-/; s/\.so(\.|$)//; y/_/-/; s/(.*)/\L&/'

   (3) The package management system requires the library to be placed
before the symbolic link pointing to it in the ‘.deb’ file.  This is so
that when ‘dpkg’ comes to install the symlink (overwriting the previous
symlink pointing at an older version of the library), the new shared
library is already in place.  In the past, this was achieved by creating
the library in the temporary packaging directory before creating the
symlink.  Unfortunately, this was not always effective, since the
building of the tar file in the ‘.deb’ depended on the behavior of the
underlying file system.  Some file systems (such as reiserfs) reorder
the files so that the order of creation is forgotten.  Since version
1.7.0, ‘dpkg’ reorders the files itself as necessary when building a
package.  Thus it is no longer important to concern oneself with the
order of file creation.