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

Normally, the run-time shared library and its SONAME symlink should be placed in a package named librarynamesoversion, 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. 3

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 SONAMEs will always change together. Be aware that this is not normally the case, and if the SONAMEs 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 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. 4

2

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.

3

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&/'

4

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.

8.1.1. ldconfig

Any package installing shared libraries in one of the default library directories of the dynamic linker (which are currently /usr/lib and /lib) or a directory that is listed in /etc/ld.so.conf 5 must use ldconfig to update the shared library system.

Any such package must have the line activate-noawait ldconfig in its triggers control file (i.e. DEBIAN/triggers).

5

These are currently /usr/local/lib plus directories under /lib and /usr/lib matching the multiarch triplet for the system architecture.