Shared libraries
================

Packages containing shared libraries must be constructed with a little
care to make sure that the shared library is always available. This is
especially important for packages whose shared libraries are vitally
important, such as the C library (currently ``libc6``).

This section deals only with public shared libraries: shared libraries
that are placed in directories searched by the dynamic linker by default
or which are intended to be linked against normally and possibly used by
other, independent packages. Shared libraries that are internal to a
particular package or that are only loaded as dynamic modules are not
covered by this section and are not subject to its requirements.

A shared library is identified by the ``SONAME`` attribute stored in its
dynamic section. When a binary is linked against a shared library, the
``SONAME`` of the shared library is recorded in the binary's ``NEEDED``
section so that the dynamic linker knows that library must be loaded at
runtime. The shared library file's full name (which usually contains
additional version information not needed in the ``SONAME``) is therefore
normally not referenced directly. Instead, the shared library is loaded by
its ``SONAME``, which exists on the file system as a symlink pointing to
the full name of the shared library. This symlink must be provided by the
package.  :ref:`s-sharedlibs-runtime` describes how to do this.  [#]_

When linking a binary or another shared library against a shared
library, the ``SONAME`` for that shared library is not yet known.
Instead, the shared library is found by looking for a file matching the
library name with ``.so`` appended. This file exists on the file system
as a symlink pointing to the shared library.

Shared libraries are normally split into several binary packages. The
``SONAME`` symlink is installed by the runtime shared library package,
and the bare ``.so`` symlink is installed in the development package
since it's only used when linking binaries or shared libraries. However,
there are some exceptions for unusual shared libraries or for shared
libraries that are also loaded as dynamic modules by other programs.

This section is primarily concerned with how the separation of shared
libraries into multiple packages should be done and how dependencies on
and between shared library binary packages are managed in Debian.
:ref:`s-libraries` should be read in conjunction with
this section and contains additional rules for the files contained in
the shared library packages.

.. [#] This is a convention of shared library versioning, but not a
       requirement. Some libraries use the ``SONAME`` as the full library
       file name instead and therefore do not need a symlink. Most,
       however, encode additional information about backwards-compatible
       revisions as a minor version number in the file name. The
       ``SONAME`` itself only changes when binaries linked with the
       earlier version of the shared library may no longer work, but the
       filename may change with each release of the library. See
       :ref:`s-sharedlibs-runtime` for more information.

.. _s-sharedlibs-runtime:

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. [#]_

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. [#]_

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 could 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 :ref:`s-sharedlibs-depends`).

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.  [#]_

.. [#] 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.

.. [#] 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&/'

.. [#] 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.

.. _s-ldconfig:

``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`` [#]_
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``).

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

.. _s-sharedlibs-support-files:

Shared library support files
----------------------------

If your package contains files whose names do not change with each
change in the library shared object version, you must not put them in
the shared library package. Otherwise, several versions of the shared
library cannot be installed at the same time without filename clashes,
making upgrades and transitions unnecessarily difficult.

It is recommended that supporting files and run-time support programs
that do not need to be invoked manually by users, but are nevertheless
required for the package to function, be placed (if they are binary) in
a subdirectory of ``/usr/lib``, preferably under
``/usr/lib/``\ package-name. If the program or file is architecture
independent, the recommendation is for it to be placed in a subdirectory
of ``/usr/share`` instead, preferably under
``/usr/share/``\ package-name. Following the package-name naming
convention ensures that the file names change when the shared object
version changes.

Run-time support programs that use the shared library but are not
required for the library to function or files used by the shared library
that can be used by any version of the shared library package should
instead be put in a separate package. This package might typically be
named libraryname-tools; note the absence of the soversion in the
package name.

Files and support programs only useful when compiling software against
the library should be included in the development package for the
library.  [#]_

.. [#] For example, a ``package-name-config`` script or pkg-config
       configuration files.

.. _s-sharedlibs-static:

Static libraries
----------------

The static library (``libraryname.a``) is usually provided in addition
to the shared version. It is placed into the development package (see
below).

In some cases, it is acceptable for a library to be available in static
form only; these cases include:

- libraries for languages whose shared library support is immature or
  unstable

- libraries whose interfaces are in flux or under development (commonly
  the case when the library's major version number is zero, or where the
  ABI breaks across patchlevels)

- libraries which are explicitly intended to be available only in static
  form by their upstream author(s)

.. _s-sharedlibs-dev:

Development files
-----------------

If there are development files associated with a shared library, the
source package needs to generate a binary development package named
libraryname-dev, or if you need to support multiple development versions
at a time, librarynameapiversion-dev. Installing the development package
must result in installation of all the development files necessary for
compiling programs against that shared library.  [#]_

In case several development versions of a library exist, you may need to
use ``dpkg``'s Conflicts mechanism (see :ref:`s-conflicts`) to ensure that
the user only installs one development version at a time (as different
development versions are likely to have the same header files in them,
which would cause a filename clash if both were unpacked).

The development package should contain a symlink for the associated
shared library without a version number. For example, the libgdbm-dev
package should include a symlink from ``/usr/lib/libgdbm.so`` to
``libgdbm.so.3.0.0``. This symlink is needed by the linker (``ld``) when
compiling packages, as it will only look for ``libgdbm.so`` when
compiling dynamically.

If the package provides Ada Library Information (``*.ali``) files for use
with GNAT, these files must be installed read-only (mode 0444) so that
GNAT will not attempt to recompile them. This overrides the normal file
mode requirements given in :ref:`s-permissions-owners`.

.. [#] This wording allows the development files to be split into several
       packages, such as a separate architecture-independent
       libraryname-headers, provided that the development package depends
       on all the required additional packages.

.. _s-sharedlibs-intradeps:

Dependencies between the packages of the same library
-----------------------------------------------------

Typically the development version should have an exact version dependency
on the runtime library, to make sure that compilation and linking happens
correctly. The ``${binary:Version}`` substitution variable can be useful
for this purpose.  [#]_

.. [#] Previously, ``${Source-Version}`` was used, but its name was
       confusing and it has been deprecated since dpkg 1.13.19.

.. _s-sharedlibs-depends:

Dependencies between the library and other packages
---------------------------------------------------

If a package contains a binary or library which links to a shared
library, we must ensure that, when the package is installed on the
system, all of the libraries needed are also installed. These
dependencies must be added to the binary package when it is built, since
they may change based on which version of a shared library the binary or
library was linked with even if there are no changes to the source of
the binary (for example, symbol versions change, macros become functions
or vice versa, or the binary package may determine at compile-time
whether new library interfaces are available and can be called). To
allow these dependencies to be constructed, shared libraries must
provide either a ``symbols`` file or a ``shlibs`` file. These provide
information on the package dependencies required to ensure the presence
of interfaces provided by this library. Any package with binaries or
libraries linking to a shared library must use these files to determine
the required dependencies when it is built. Other packages which use a
shared library (for example using ``dlopen()``) should compute
appropriate dependencies using these files at build time as well.

The two mechanisms differ in the degree of detail that they provide. A
``symbols`` file documents, for each symbol exported by a library, the
minimal version of the package any binary using this symbol will need.
This is typically the version of the package in which the symbol was
introduced. This information permits detailed analysis of the symbols
used by a particular package and construction of an accurate dependency,
but it requires the package maintainer to track more information about
the shared library.

A ``shlibs`` file, in contrast, only documents the last time the library
ABI changed in any way. It only provides information about the library
as a whole, not individual symbols. When a package is built using a
shared library with only a ``shlibs`` file, the generated dependency
will require a version of the shared library equal to or newer than the
version of the last ABI change. This generates unnecessarily restrictive
dependencies compared to ``symbols`` files if none of the symbols used
by the package have changed. This, in turn, could make upgrades needlessly
complex and unnecessarily restrict use of the package on systems with
older versions of the shared libraries.

``shlibs`` files also only support a limited range of library SONAMEs,
making it difficult to use ``shlibs`` files in some unusual corner
cases.  [#]_

``symbols`` files are therefore recommended for most shared library
packages since they provide more accurate dependencies. For most C
libraries, the additional detail required by ``symbols`` files is not
too difficult to maintain. However, maintaining exhaustive symbols
information for a C++ library can be quite onerous, so ``shlibs`` files
may be more appropriate for most C++ libraries. Libraries with a
corresponding udeb must also provide a ``shlibs`` file, since the udeb
infrastructure does not use ``symbols`` files.

.. [#] A ``shlibs`` file represents an SONAME as a library name and
       version number, such as ``libfoo VERSION``, instead of recording
       the actual SONAME. If the SONAME doesn't match one of the two
       expected formats (``libfoo-VERSION.so`` or ``libfoo.so.VERSION``),
       it cannot be represented.

.. _s-dpkg-shlibdeps:

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. [#]_ 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. [#]_
``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.  [#]_ 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.  [#]_

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.  [#]_

.. [#] ``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.

.. [#] 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.

.. [#] ``dh_shlibdeps`` from the ``debhelper`` suite will automatically
       add this option if it knows it is processing a udeb.

.. [#] 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.

.. [#] 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.

.. _s-sharedlibs-updates:

Shared library ABI changes
~~~~~~~~~~~~~~~~~~~~~~~~~~

Maintaining a shared library package using either ``symbols`` or
``shlibs`` files requires being aware of the exposed ABI of the shared
library and any changes to it. Both ``symbols`` and ``shlibs`` files
record every change to the ABI of the shared library; ``symbols`` files
do so per public symbol, whereas ``shlibs`` files record only the last
change for the entire library.

There are two types of ABI changes: ones that are backward-compatible
and ones that are not. An ABI change is backward-compatible if any
reasonable program or library that was linked with the previous version
of the shared library will still work correctly with the new version of
the shared library.  [#]_ Adding new symbols to the shared library is a
backward-compatible change. Removing symbols from the shared library is
not. Changing the behavior of a symbol may or may not be
backward-compatible depending on the change; for example, changing a
function to accept a new enum constant not previously used by the
library is generally backward-compatible, but changing the members of a
struct that is passed into library functions is generally not unless the
library takes special precautions to accept old versions of the data
structure.

ABI changes that are not backward-compatible normally require changing the
``SONAME`` of the library and therefore the shared library package name,
which forces rebuilding all packages using that shared library to update
their dependencies and allow them to use the new version of the shared
library. For more information, see :ref:`s-sharedlibs-runtime`. The
remainder of this section will deal with backward-compatible changes.

Backward-compatible changes require either updating or recording the
minimal-version for that symbol in ``symbols`` files or updating the
version in the dependencies in ``shlibs`` files. For more information on
how to do this in the two formats, see :ref:`s-symbols` and
:ref:`s-shlibs`. Below are general rules that apply to both files.

The easy case is when a public symbol is added. Simply add the version
at which the symbol was introduced (for ``symbols`` files) or update the
dependency version (for ``shlibs``) files. But special care should be
taken to update dependency versions when the behavior of a public symbol
changes. This is easy to neglect, since there is no automated method of
determining such changes, but failing to update versions in this case
could result in binary packages with too-weak dependencies that will fail
at runtime, possibly in ways that can cause security vulnerabilities. If
the package maintainer believes that a symbol behavior change could have
occurred but isn't sure, it's safer to update the version rather than
leave it unmodified. This may result in unnecessarily strict
dependencies, but it ensures that packages whose dependencies are
satisfied will work properly.

A common example of when a change to the dependency version is required
is a function that takes an enum or struct argument that controls what
the function does. For example::

    enum library_op { OP_FOO, OP_BAR };
    int library_do_operation(enum library_op);

If a new operation, ``OP_BAZ``, is added, the minimal-version of
``library_do_operation`` (for ``symbols`` files) or the version in the
dependency for the shared library (for ``shlibs`` files) must be
increased to the version at which ``OP_BAZ`` was introduced. Otherwise,
a binary built against the new version of the library (having detected
at compile-time that the library supports ``OP_BAZ``) may be installed
with a shared library that doesn't support ``OP_BAZ`` and will fail at
runtime when it tries to pass ``OP_BAZ`` into this function.

Dependency versions in either ``symbols`` or ``shlibs`` files normally
should not contain the Debian revision of the package, since the library
behavior is normally fixed for a particular upstream version and any
Debian packaging of that upstream version will have the same behavior.
In the rare case that the library behavior was changed in a particular
Debian revision, appending ``~`` to the end of the version that includes
the Debian revision is recommended, since this allows backports of the
shared library package using the normal backport versioning convention
to satisfy the dependency.

.. [#] An example of an "unreasonable" program is one that uses library
       interfaces that are documented as internal and unsupported. If the
       only programs or libraries affected by a change are "unreasonable"
       ones, other techniques, such as declaring ``Breaks`` relationships
       with affected packages or treating their usage of the library as
       bugs in those packages, may be appropriate instead of changing the
       SONAME.  However, the default approach is to change the SONAME for
       any change to the ABI that could break a program.

.. _s-sharedlibs-symbols:

The ``symbols`` system
~~~~~~~~~~~~~~~~~~~~~~

In the following sections, we will first describe where the various
``symbols`` files are to be found, then the ``symbols`` file format, and
finally how to create ``symbols`` files if your package contains a
shared library.

.. _s-symbols-paths:

The ``symbols`` files present on the system
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``symbols`` files for a shared library are normally provided by the
shared library package as a control file, but there are several override
paths that are checked first in case that information is wrong or
missing. The following list gives them in the order in which they are
read by ``dpkg-shlibdeps``. The first one that contains the required
information is used.

``debian/*/DEBIAN/symbols``
    During the package build, if the package itself contains shared
    libraries with ``symbols`` files, they will be generated in these
    staging directories by ``dpkg-gensymbols`` (see `Providing a symbols
    file <#s-providing-symbols>`__). ``symbols`` files found in the build
    tree take precedence over ``symbols`` files from other binary
    packages.

    These files must exist before ``dpkg-shlibdeps`` is run or the
    dependencies of binaries and libraries from a source package on
    other libraries from that same source package will not be correct.
    In practice, this means that ``dpkg-gensymbols`` must be run before
    ``dpkg-shlibdeps`` during the package build.  [#]_

``/etc/dpkg/symbols/package.symbols.arch`` and ``/etc/dpkg/symbols/package.symbols``
    Per-system overrides of shared library dependencies. These files
    normally do not exist. They are maintained by the local system
    administrator and must not be created by any Debian package.

``symbols`` control files for packages installed on the system
    The ``symbols`` control files for all the packages currently
    installed on the system are searched last. This will be the most
    common source of shared library dependency information. These files
    can be read with ``dpkg-query --control-show package symbols``.

Be aware that if a ``debian/shlibs.local`` exists in the source package,
it will override any ``symbols`` files. This is the only case where a
``shlibs`` is used despite ``symbols`` files being present. See
:ref:`s-shlibs-paths` and :ref:`s-sharedlibs-shlibdeps` for more
information.

.. [#] An example may clarify. Suppose the source package ``foo``
       generates two binary packages, ``libfoo2`` and
       ``foo-runtime``. When building the binary packages, the contents of
       the packages are staged in the directories ``debian/libfoo2`` and
       ``debian/foo-runtime`` respectively. (``debian/tmp`` could be used
       instead of one of these.)  Since ``libfoo2`` provides the
       ``libfoo`` shared library, it will contain a ``symbols`` file,
       which will be installed in ``debian/libfoo2/DEBIAN/symbols``,
       eventually to be included as a control file in that package. When
       ``dpkg-shlibdeps`` is run on the executable
       ``debian/foo-runtime/usr/bin/foo-prog``, it will examine the
       ``debian/libfoo2/DEBIAN/symbols`` file to determine whether
       ``foo-prog``'s library dependencies are satisfied by any of the
       libraries provided by ``libfoo2``. Since those binaries were linked
       against the just-built shared library as part of the build process,
       the ``symbols`` file for the newly-built ``libfoo2`` must take
       precedence over a ``symbols`` file for any other ``libfoo2``
       package already installed on the system.

.. _s-symbols:

The ``symbols`` File Format
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following documents the format of the ``symbols`` control file as
included in binary packages. These files are built from template
``symbols`` files in the source package by ``dpkg-gensymbols``. The
template files support a richer syntax that allows ``dpkg-gensymbols`` to
do some of the tedious work involved in maintaining ``symbols`` files,
such as handling C++ symbols or optional symbols that may not exist on
particular architectures. When writing ``symbols`` files for a shared
library package, refer to :manpage:`dpkg-gensymbols(1)` for the richer
syntax.

A ``symbols`` may contain one or more entries, one for each shared
library contained in the package corresponding to that ``symbols``. Each
entry has the following format::

    library-soname main-dependency-template
     [| alternative-dependency-template]
     [...]
     [* field-name: field-value]
     [...]
     symbol minimal-version[ id-of-dependency-template]

To explain this format, we'll use the ``zlib1g`` package as an example,
which (at the time of writing) installs the shared library
``/usr/lib/libz.so.1.2.3.4``. Mandatory lines will be described first,
followed by optional lines.

``library-soname`` must contain exactly the value of the ELF ``SONAME``
attribute of the shared library. In our example, this is ``libz.so.1``.
[#]_

``main-dependency-template`` has the same syntax as a dependency field
in a binary package control file, except that the string ``#MINVER#``
is replaced by a version restriction like ``(>= version)`` or by
nothing if an unversioned dependency is deemed sufficient. The version
restriction will be based on which symbols from the shared library are
referenced and the version at which they were introduced (see
below). In nearly all cases, ``main-dependency-template`` will be
``package #MINVER#``, where package is the name of the binary package
containing the shared library. This adds a simple, possibly-versioned
dependency on the shared library package. In some rare cases, such as
when multiple packages provide the same shared library ABI, the
dependency template may need to be more complex.

In our example, the first line of the ``zlib1g`` ``symbols`` file would
be::

    libz.so.1 zlib1g #MINVER#

Each public symbol exported by the shared library must have a
corresponding symbol line, indented by one space. symbol is the
exported symbol (which, for C++, means the mangled symbol) followed by
``@`` and the symbol version, or the string ``Base`` if there is no
symbol version. ``minimal-version`` is the most recent version of the
shared library that changed the behavior of that symbol, whether by
adding it, changing its function signature (the parameters, their
types, or the return type), or changing its behavior in a way that is
visible to a caller. ``id-of-dependency-template`` is an optional
field that references an ``alternative-dependency-template``; see
below for a full description.

For example, ``libz.so.1`` contains the symbols ``compress`` and
``compressBound``. ``compress`` has no symbol version and last changed
its behavior in upstream version ``1:1.1.4``. ``compressBound`` has the
symbol version ``ZLIB_1.2.0``, was introduced in upstream version
``1:1.2.0``, and has not changed its behavior. Its ``symbols`` file
therefore contains the lines::

    compress@Base 1:1.1.4
    compressBound@ZLIB_1.2.0 1:1.2.0

Packages using only ``compress`` would then get a dependency on
``zlib1g (>= 1:1.1.4)``, but packages using ``compressBound`` would get
a dependency on ``zlib1g (>= 1:1.2.0)``.

One or more ``alternative-dependency-template`` lines may be
provided. These are used in cases where some symbols in the shared
library should use one dependency template while others should use a
different template.  The alternative dependency templates are used
only if a symbol line contains the ``id-of-dependency-template``
field. The first alternative dependency template is numbered 1, the
second 2, and so forth.  [#]_

Finally, the entry for the library may contain one or more metadata
fields. Currently, the only supported field-name is
``Build-Depends-Package``, whose value lists the `library development
package <#s-sharedlibs-dev>`_ on which packages using this shared library
declare a build dependency. If this field is present, ``dpkg-shlibdeps``
uses it to ensure that the resulting binary package dependency on the
shared library is at least as strict as the source package dependency on
the shared library development package.  [#]_ For our example, the
``zlib1g`` ``symbols`` file would contain::

    * Build-Depends-Package: zlib1g-dev

Also see :manpage:`deb-symbols(5)`.

.. [#] This can be determined by using the command

       ::

           readelf -d /usr/lib/libz.so.1.2.3.4 | grep SONAME

.. [#] An example of where this may be needed is with a library that
       implements the libGL interface. All GL implementations provide the
       same set of base interfaces, and then may provide some additional
       interfaces only used by programs that require that specific GL
       implementation. So, for example, libgl1-mesa-glx may use the
       following ``symbols`` file::

           libGL.so.1 libgl1
            | libgl1-mesa-glx #MINVER#
            publicGlSymbol@Base 6.3-1 [...]
            implementationSpecificSymbol@Base 6.5.2-7 1
            [...]

       Binaries or shared libraries using only ``publicGlSymbol`` would
       depend only on ``libgl1`` (which may be provided by multiple
       packages), but ones using ``implementationSpecificSymbol`` would
       get a dependency on ``libgl1-mesa-glx (>= 6.5.2-7)``.

.. [#] This field should normally not be necessary, since if the behavior
       of any symbol has changed, the corresponding symbol minimal-version
       should have been increased. But including it makes the ``symbols``
       system more robust by tightening the dependency in cases where the
       package using the shared library specifically requires at least a
       particular version of the shared library development package for
       some reason.

.. _s-providing-symbols:

Providing a ``symbols`` file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If your package provides a shared library, you should arrange to include
a ``symbols`` control file following the format described above in that
package. You must include either a ``symbols`` control file or a
``shlibs`` control file.

Normally, this is done by creating a ``symbols`` in the source package
named ``debian/package.symbols`` or ``debian/symbols``, possibly with
``.arch`` appended if the symbols information varies by architecture.
This file may use the extended syntax documented in
:manpage:`dpkg-gensymbols(1)`.  Then, call ``dpkg-gensymbols`` as part of
the package build process. It will create ``symbols`` files in the package
staging area based on the binaries and libraries in the package staging
area and the ``symbols`` files in the source package. [#]_

Packages that provide ``symbols`` files must keep them up-to-date to
ensure correct dependencies in packages that use the shared libraries.
This means updating the ``symbols`` file whenever a new public symbol is
added, changing the minimal-version field whenever a symbol changes
behavior or signature in a backward-compatible way (see
:ref:`s-sharedlibs-updates`), and changing the library-soname and
main-dependency-template, and probably all of the minimal-version fields,
when the library changes ``SONAME``. Removing a public symbol from the
``symbols`` file because it's no longer provided by the library normally
requires changing the ``SONAME`` of the library.  See
:ref:`s-sharedlibs-runtime` for more information on ``SONAME``\ s.

.. [#] If you are using ``debhelper``, ``dh_makeshlibs`` will take care of
       calling either ``dpkg-gensymbols`` or generating a ``shlibs`` file
       as appropriate.

.. _s-sharedlibs-shlibdeps:

The ``shlibs`` system
~~~~~~~~~~~~~~~~~~~~~

The ``shlibs`` system is a simpler alternative to the ``symbols`` system
for declaring dependencies for shared libraries. It may be more
appropriate for C++ libraries and other cases where tracking individual
symbols is too difficult. It predated the ``symbols`` system and is
therefore frequently seen in older packages. It is also required for
udebs, which do not support ``symbols``.

In the following sections, we will first describe where the various
``shlibs`` files are to be found, then how to use ``dpkg-shlibdeps``,
and finally the ``shlibs`` file format and how to create them.

.. _s-shlibs-paths:

The ``shlibs`` files present on the system
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are several places where ``shlibs`` files are found. The following
list gives them in the order in which they are read by
``dpkg-shlibdeps``. (The first one which gives the required information
is used.)

``debian/shlibs.local``
    This lists overrides for this package. This file should normally not
    be used, but may be needed temporarily in unusual situations to work
    around bugs in other packages, or in unusual cases where the
    normally declared dependency information in the installed ``shlibs``
    file for a library cannot be used. This file overrides information
    obtained from any other source.

``/etc/dpkg/shlibs.override``
    This lists global overrides. This list is normally empty. It is
    maintained by the local system administrator.

``DEBIAN/shlibs`` files in the "build directory"
    These files are generated as part of the package build process and
    staged for inclusion as control files in the binary packages being
    built. They provide details of any shared libraries included in the
    same package.

``shlibs`` control files for packages installed on the system
    The ``shlibs`` control files for all the packages currently installed
    on the system. These files can be read using
    ``dpkg-query --control-show package shlibs``.

``/etc/dpkg/shlibs.default``
    This file lists any shared libraries whose packages have failed to
    provide correct ``shlibs`` files. It was used when the ``shlibs``
    setup was first introduced, but it is now normally empty. It is
    maintained by the ``dpkg`` maintainer.

If a ``symbols`` file for a shared library package is available,
``dpkg-shlibdeps`` will always use it in preference to a ``shlibs``,
with the exception of ``debian/shlibs.local``. The latter overrides any
other ``shlibs`` or ``symbols`` files.

.. _s-shlibs:

The ``shlibs`` File Format
^^^^^^^^^^^^^^^^^^^^^^^^^^

Each ``shlibs`` file has the same format. Lines beginning with ``#`` are
considered to be comments and are ignored. Each line is of the form::

    [type: ]library-name soname-version dependencies ...

We will explain this by reference to the example of the ``zlib1g``
package, which (at the time of writing) installs the shared library
``/usr/lib/libz.so.1.2.3.4``.

``type`` is an optional element that indicates the type of package for which
the line is valid. The only type currently in use is ``udeb``. The colon
and space after the type are required.

``library-name`` is the name of the shared library, in this case ``libz``.
(This must match the name part of the soname, see below.)

``soname-version`` is the version part of the ELF ``SONAME`` attribute of
the library, determined the same way that the soversion component of the
recommended shared library package name is determined. See
:ref:`s-sharedlibs-runtime` for the details.

``dependencies`` has the same syntax as a dependency field in a binary
package control file. It should give details of which packages are
required to satisfy a binary built against the version of the library
contained in the package. See :ref:`s-depsyntax` for
details on the syntax, and :ref:`s-sharedlibs-updates`
for details on how to maintain the dependency version constraint.

In our example, if the last change to the ``zlib1g`` package that could
change behavior for a client of that library was in version
``1:1.2.3.3.dfsg-1``, then the ``shlibs`` entry for this library could
say::

    libz 1 zlib1g (>= 1:1.2.3.3.dfsg)

This version restriction must be new enough that any binary built
against the current version of the library will work with any version of
the shared library that satisfies that dependency.

As zlib1g also provides a udeb containing the shared library, there
would also be a second line::

    udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg)

.. _s8.6.4.3:

Providing a ``shlibs`` file
^^^^^^^^^^^^^^^^^^^^^^^^^^^

To provide a ``shlibs`` file for a shared library binary package, create
a ``shlibs`` file following the format described above and place it in
the ``DEBIAN`` directory for that package during the build. It will then
be included as a control file for that package.  [#]_

Since ``dpkg-shlibdeps`` reads the ``DEBIAN/shlibs`` files in all of the
binary packages being built from this source package, all of the
``DEBIAN/shlibs`` files should be installed before ``dpkg-shlibdeps`` is
called on any of the binary packages.

.. [#] This is what ``dh_makeshlibs`` in the debhelper suite does. If your
       package also has a udeb that provides a shared library,
       ``dh_makeshlibs`` can automatically generate the ``udeb:`` lines if
       you specify the name of the udeb with the ``--add-udeb`` option.