Gecko [ fernandoquevedodop.com ]

Name	Size	Permission
_images	[ DIR ]	drwxr-xr-x
_sources	[ DIR ]	drwxr-xr-x
_static	[ DIR ]	drwxr-xr-x
ap-flowcharts.html	7.02 KB	-rw-r--r--
ap-license.html	4.8 KB	-rw-r--r--
ap-pkg-alternatives.html	6.79 KB	-rw-r--r--
ap-pkg-binarypkg.html	17.44 KB	-rw-r--r--
ap-pkg-conffiles.html	12.14 KB	-rw-r--r--
ap-pkg-controlfields.html	12.4 KB	-rw-r--r--
ap-pkg-diversions.html	11.4 KB	-rw-r--r--
ap-pkg-scope.html	7.81 KB	-rw-r--r--
ap-pkg-sourcepkg.html	33.32 KB	-rw-r--r--
ap-process.html	18.49 KB	-rw-r--r--
ch-archive.html	28.57 KB	-rw-r--r--
ch-binary.html	38.01 KB	-rw-r--r--
ch-controlfields.html	107.38 KB	-rw-r--r--
ch-customized-programs.html	53.09 KB	-rw-r--r--
ch-docs.html	33.97 KB	-rw-r--r--
ch-files.html	69.51 KB	-rw-r--r--
ch-maintainerscripts.html	40.34 KB	-rw-r--r--
ch-opersys.html	84.18 KB	-rw-r--r--
ch-relationships.html	67.18 KB	-rw-r--r--
ch-scope.html	18.54 KB	-rw-r--r--
ch-sharedlibs.html	88.6 KB	-rw-r--r--
ch-source.html	79.4 KB	-rw-r--r--
genindex.html	3.48 KB	-rw-r--r--
index.html	59.51 KB	-rw-r--r--
objects.inv	4.75 KB	-rw-r--r--
search.html	2.99 KB	-rw-r--r--
searchindex.js	58.77 KB	-rw-r--r--
upgrading-checklist.html	121.38 KB	-rw-r--r--

Code Editor : ch-sharedlibs.html

<!DOCTYPE html>

<title>8. Shared libraries &#8212; Debian Policy Manual v4.6.0.1</title>
 <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
 <link rel="stylesheet" type="text/css" href="_static/nature.css" />
 <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
 <script src="_static/jquery.js"></script>
 <script src="_static/underscore.js"></script>
 <script src="_static/doctools.js"></script>
 <link rel="index" title="Index" href="genindex.html" />
 <link rel="search" title="Search" href="search.html" />
 <link rel="next" title="9. The Operating System" href="ch-opersys.html" />
 <link rel="prev" title="7. Declaring relationships between packages" href="ch-relationships.html" /> 
 </head><body>
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li class="right" >
 <a href="ch-opersys.html" title="9. The Operating System"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="ch-relationships.html" title="7. Declaring relationships between packages"
 accesskey="P">previous</a> |</li>
 <li class="nav-item nav-item-0"><a href="index.html">Debian Policy Manual v4.6.0.1</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">8. Shared libraries</a></li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <section id="shared-libraries">
<h1>8. Shared libraries<a class="headerlink" href="#shared-libraries" title="Permalink to this headline">¶</a></h1>
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 <code class="docutils literal notranslate">libc6</code>).
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 <code class="docutils literal notranslate">SONAME</code> attribute stored in its
dynamic section. When a binary is linked against a shared library, the
<code class="docutils literal notranslate">SONAME</code> of the shared library is recorded in the binary’s <code class="docutils literal notranslate">NEEDED</code>
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 <code class="docutils literal notranslate">SONAME</code>) is therefore
normally not referenced directly. Instead, the shared library is loaded by
its <code class="docutils literal notranslate">SONAME</code>, 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. <a class="reference internal" href="#s-sharedlibs-runtime">Run-time shared libraries</a> describes how to do this. <a class="footnote-reference brackets" href="#id2" id="id1">1</a>
When linking a binary or another shared library against a shared
library, the <code class="docutils literal notranslate">SONAME</code> for that shared library is not yet known.
Instead, the shared library is found by looking for a file matching the
library name with <code class="docutils literal notranslate">.so</code> 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
<code class="docutils literal notranslate">SONAME</code> symlink is installed by the runtime shared library package,
and the bare <code class="docutils literal notranslate">.so</code> 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.
<a class="reference internal" href="ch-files.html#s-libraries">Libraries</a> should be read in conjunction with
this section and contains additional rules for the files contained in
the shared library packages.
<dl class="footnote brackets">
<dt class="label" id="id2"><a class="fn-backref" href="#id1">1</a></dt>
<dd>This is a convention of shared library versioning, but not a
requirement. Some libraries use the <code class="docutils literal notranslate">SONAME</code> 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
<code class="docutils literal notranslate">SONAME</code> 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
<a class="reference internal" href="#s-sharedlibs-runtime">Run-time shared libraries</a> for more information.
</dd>
</dl>
<section id="run-time-shared-libraries">
<h2>8.1. Run-time shared libraries<a class="headerlink" href="#run-time-shared-libraries" title="Permalink to this headline">¶</a></h2>
The run-time shared library must be placed in a package whose name changes
whenever the <code class="docutils literal notranslate">SONAME</code> 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. <a class="footnote-reference brackets" href="#id6" id="id3">2</a>
Normally, the run-time shared library and its <code class="docutils literal notranslate">SONAME</code> symlink should be
placed in a package named librarynamesoversion, where soversion is
the version number in the <code class="docutils literal notranslate">SONAME</code> 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. <a class="footnote-reference brackets" href="#id7" id="id4">3</a>
To determine the soversion, look at the <code class="docutils literal notranslate">SONAME</code> of the library,
stored in the ELF <code class="docutils literal notranslate">SONAME</code> attribute. It is usually of the form
<code class="docutils literal notranslate">name.so.major-version</code> (for example, <code class="docutils literal notranslate">libz.so.1</code>). The version part
is the part which comes after <code class="docutils literal notranslate">.so.</code>, so in that example it is <code class="docutils literal notranslate">1</code>.
The soname may instead be of the form <code class="docutils literal notranslate">name-major-version.so</code>, such as
<code class="docutils literal notranslate">libdb-5.1.so</code>, in which case the name would be <code class="docutils literal notranslate">libdb</code> and the
version would be <code class="docutils literal notranslate">5.1</code>.
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 <code class="docutils literal notranslate">SONAME</code>s will always change together. Be
aware that this is not normally the case, and if the <code class="docutils literal notranslate">SONAME</code>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
<code class="docutils literal notranslate">SONAME</code> of the library and the corresponding name for the binary
package containing the runtime shared library should change. Normally,
this means the <code class="docutils literal notranslate">SONAME</code> 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 <code class="docutils literal notranslate">SONAME</code> 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
<code class="docutils literal notranslate">symbols</code> or <code class="docutils literal notranslate">shlibs</code> system (see <a class="reference internal" href="#s-sharedlibs-depends">Dependencies between the library and other packages</a>).
The package should install the shared libraries under their normal
names. For example, the libgdbm3 package should install
<code class="docutils literal notranslate">libgdbm.so.3.0.0</code> as <code class="docutils literal notranslate">/usr/lib/libgdbm.so.3.0.0</code>. The files should
not be renamed or re-linked by any <code class="docutils literal notranslate">prerm</code> or <code class="docutils literal notranslate">postrm</code> scripts;
<code class="docutils literal notranslate">dpkg</code> 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
<code class="docutils literal notranslate">SONAME</code> that <code class="docutils literal notranslate">ldconfig</code> would create for the shared libraries. For
example, the libgdbm3 package should include a symbolic link from
<code class="docutils literal notranslate">/usr/lib/libgdbm.so.3</code> to <code class="docutils literal notranslate">libgdbm.so.3.0.0</code>. This is needed so
that the dynamic linker (for example <code class="docutils literal notranslate">ld.so</code> or <code class="docutils literal notranslate">ld-linux.so.*</code>) can
find the library between the time that <code class="docutils literal notranslate">dpkg</code> installs it and the time
that <code class="docutils literal notranslate">ldconfig</code> is run in the <code class="docutils literal notranslate">postinst</code> script. <a class="footnote-reference brackets" href="#id8" id="id5">4</a>
<dl class="footnote brackets">
<dt class="label" id="id6"><a class="fn-backref" href="#id3">2</a></dt>
<dd>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.
</dd>
<dt class="label" id="id7"><a class="fn-backref" href="#id4">3</a></dt>
<dd>The following command, when run on a shared library, will output
the name to be used for the Debian package containing that shared
library:
<div class="highlight-default notranslate"><div class="highlight"><pre>objdump -p /path/to/libfoo-bar.so.1.2.3 \
 | sed -n -e&#39;s/^[[:space:]]*SONAME[[:space:]]*//p&#39; \
 | LC_ALL=C sed -r -e&#39;s/([0-9])\.so\./\1-/; s/\.so(\.|$)//; y/_/-/; s/(.*)/\L&amp;/&#39;
</pre></div>
</div>
</dd>
<dt class="label" id="id8"><a class="fn-backref" href="#id5">4</a></dt>
<dd>The package management system requires the library to be placed
before the symbolic link pointing to it in the <code class="docutils literal notranslate">.deb</code> file. This
is so that when <code class="docutils literal notranslate">dpkg</code> 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
<code class="docutils literal notranslate">.deb</code> 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,
<code class="docutils literal notranslate">dpkg</code> 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.
</dd>
</dl>
<section id="ldconfig">
<h3>8.1.1. <code class="docutils literal notranslate">ldconfig</code><a class="headerlink" href="#ldconfig" title="Permalink to this headline">¶</a></h3>
Any package installing shared libraries in one of the default library
directories of the dynamic linker (which are currently <code class="docutils literal notranslate">/usr/lib</code> and
<code class="docutils literal notranslate">/lib</code>) or a directory that is listed in <code class="docutils literal notranslate">/etc/ld.so.conf</code> <a class="footnote-reference brackets" href="#id10" id="id9">5</a>
must use <code class="docutils literal notranslate">ldconfig</code> to update the shared library system.
Any such package must have the line <code class="docutils literal notranslate">activate-noawait ldconfig</code> in its
<code class="docutils literal notranslate">triggers</code> control file (i.e. <code class="docutils literal notranslate">DEBIAN/triggers</code>).
<dl class="footnote brackets">
<dt class="label" id="id10"><a class="fn-backref" href="#id9">5</a></dt>
<dd>These are currently <code class="docutils literal notranslate">/usr/local/lib</code> plus directories under
<code class="docutils literal notranslate">/lib</code> and <code class="docutils literal notranslate">/usr/lib</code> matching the multiarch triplet for the
system architecture.
</dd>
</dl>
</section>
</section>
<section id="shared-library-support-files">
<h2>8.2. Shared library support files<a class="headerlink" href="#shared-library-support-files" title="Permalink to this headline">¶</a></h2>
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 <code class="docutils literal notranslate">/usr/lib</code>, preferably under
<code class="docutils literal notranslate">/usr/lib/</code>package-name. If the program or file is architecture
independent, the recommendation is for it to be placed in a subdirectory
of <code class="docutils literal notranslate">/usr/share</code> instead, preferably under
<code class="docutils literal notranslate">/usr/share/</code>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. <a class="footnote-reference brackets" href="#id12" id="id11">6</a>
<dl class="footnote brackets">
<dt class="label" id="id12"><a class="fn-backref" href="#id11">6</a></dt>
<dd>For example, a <code class="docutils literal notranslate">package-name-config</code> script or pkg-config
configuration files.
</dd>
</dl>
</section>
<section id="static-libraries">
<h2>8.3. Static libraries<a class="headerlink" href="#static-libraries" title="Permalink to this headline">¶</a></h2>
The static library (<code class="docutils literal notranslate">libraryname.a</code>) 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:
<ul class="simple">
<li>libraries for languages whose shared library support is immature or
unstable</li>
<li>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)</li>
<li>libraries which are explicitly intended to be available only in static
form by their upstream author(s)</li>
</ul>
</section>
<section id="development-files">
<h2>8.4. Development files<a class="headerlink" href="#development-files" title="Permalink to this headline">¶</a></h2>
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. <a class="footnote-reference brackets" href="#id14" id="id13">7</a>
In case several development versions of a library exist, you may need to
use <code class="docutils literal notranslate">dpkg</code>’s Conflicts mechanism (see <a class="reference internal" href="ch-relationships.html#s-conflicts">Conflicting binary packages - Conflicts</a>) 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 <code class="docutils literal notranslate">/usr/lib/libgdbm.so</code> to
<code class="docutils literal notranslate">libgdbm.so.3.0.0</code>. This symlink is needed by the linker (<code class="docutils literal notranslate">ld</code>) when
compiling packages, as it will only look for <code class="docutils literal notranslate">libgdbm.so</code> when
compiling dynamically.
If the package provides Ada Library Information (<code class="docutils literal notranslate">*.ali</code>) 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 <a class="reference internal" href="ch-files.html#s-permissions-owners">Permissions and owners</a>.
<dl class="footnote brackets">
<dt class="label" id="id14"><a class="fn-backref" href="#id13">7</a></dt>
<dd>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.
</dd>
</dl>
</section>
<section id="dependencies-between-the-packages-of-the-same-library">
<h2>8.5. Dependencies between the packages of the same library<a class="headerlink" href="#dependencies-between-the-packages-of-the-same-library" title="Permalink to this headline">¶</a></h2>
Typically the development version should have an exact version dependency
on the runtime library, to make sure that compilation and linking happens
correctly. The <code class="docutils literal notranslate">${binary:Version}</code> substitution variable can be useful
for this purpose. <a class="footnote-reference brackets" href="#id16" id="id15">8</a>
<dl class="footnote brackets">
<dt class="label" id="id16"><a class="fn-backref" href="#id15">8</a></dt>
<dd>Previously, <code class="docutils literal notranslate">${Source-Version}</code> was used, but its name was
confusing and it has been deprecated since dpkg 1.13.19.
</dd>
</dl>
</section>
<section id="dependencies-between-the-library-and-other-packages">
<h2>8.6. Dependencies between the library and other packages<a class="headerlink" href="#dependencies-between-the-library-and-other-packages" title="Permalink to this headline">¶</a></h2>
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 <code class="docutils literal notranslate">symbols</code> file or a <code class="docutils literal notranslate">shlibs</code> 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 <code class="docutils literal notranslate">dlopen()</code>) 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
<code class="docutils literal notranslate">symbols</code> 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 <code class="docutils literal notranslate">shlibs</code> 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 <code class="docutils literal notranslate">shlibs</code> 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 <code class="docutils literal notranslate">symbols</code> 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.
<code class="docutils literal notranslate">shlibs</code> files also only support a limited range of library SONAMEs,
making it difficult to use <code class="docutils literal notranslate">shlibs</code> files in some unusual corner
cases. <a class="footnote-reference brackets" href="#id18" id="id17">9</a>
<code class="docutils literal notranslate">symbols</code> files are therefore recommended for most shared library
packages since they provide more accurate dependencies. For most C
libraries, the additional detail required by <code class="docutils literal notranslate">symbols</code> files is not
too difficult to maintain. However, maintaining exhaustive symbols
information for a C++ library can be quite onerous, so <code class="docutils literal notranslate">shlibs</code> files
may be more appropriate for most C++ libraries. Libraries with a
corresponding udeb must also provide a <code class="docutils literal notranslate">shlibs</code> file, since the udeb
infrastructure does not use <code class="docutils literal notranslate">symbols</code> files.
<dl class="footnote brackets">
<dt class="label" id="id18"><a class="fn-backref" href="#id17">9</a></dt>
<dd>A <code class="docutils literal notranslate">shlibs</code> file represents an SONAME as a library name and
version number, such as <code class="docutils literal notranslate">libfoo VERSION</code>, instead of recording
the actual SONAME. If the SONAME doesn’t match one of the two
expected formats (<code class="docutils literal notranslate">libfoo-VERSION.so</code> or <code class="docutils literal notranslate">libfoo.so.VERSION</code>),
it cannot be represented.
</dd>
</dl>
<section id="generating-dependencies-on-shared-libraries">
<h3>8.6.1. Generating dependencies on shared libraries<a class="headerlink" href="#generating-dependencies-on-shared-libraries" title="Permalink to this headline">¶</a></h3>
When a package that contains any shared libraries or compiled binaries is
built, it must run <code class="docutils literal notranslate">dpkg-shlibdeps</code> on each shared library and compiled
binary to determine the libraries used and hence the dependencies needed
by the package. <a class="footnote-reference brackets" href="#id24" id="id19">10</a> To do this, put a call to <code class="docutils literal notranslate">dpkg-shlibdeps</code> into
your <code class="docutils literal notranslate">debian/rules</code> file in the source package. List all of the compiled
binaries, libraries, or loadable modules in your package. <a class="footnote-reference brackets" href="#id25" id="id20">11</a>
<code class="docutils literal notranslate">dpkg-shlibdeps</code> will use the <code class="docutils literal notranslate">symbols</code> or <code class="docutils literal notranslate">shlibs</code> 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 <code class="docutils literal notranslate">dpkg-shlibdeps</code> should use the dependency line
of type <code class="docutils literal notranslate">udeb</code> by adding the <code class="docutils literal notranslate">-tudeb</code> option. <a class="footnote-reference brackets" href="#id26" id="id21">12</a> If there is no
dependency line of type <code class="docutils literal notranslate">udeb</code> in the <code class="docutils literal notranslate">shlibs</code> file,
<code class="docutils literal notranslate">dpkg-shlibdeps</code> will fall back to the regular dependency line.
<code class="docutils literal notranslate">dpkg-shlibdeps</code> puts the dependency information into the
<code class="docutils literal notranslate">debian/substvars</code> file by default, which is then used by
<code class="docutils literal notranslate">dpkg-gencontrol</code>. You will need to place a <code class="docutils literal notranslate">${shlibs:Depends}</code>
variable in the <code class="docutils literal notranslate">Depends</code> 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 <code class="docutils literal notranslate">dpkg-shlibdeps</code> on each one which contains
compiled libraries or binaries. For example, you could use the <code class="docutils literal notranslate">-T</code>
option to the <code class="docutils literal notranslate">dpkg</code> utilities to specify a different <code class="docutils literal notranslate">substvars</code>
file for each binary package. <a class="footnote-reference brackets" href="#id27" id="id22">13</a>
For more details on <code class="docutils literal notranslate">dpkg-shlibdeps</code>, see its manual page.
We say that a binary <code class="docutils literal notranslate">foo</code> directly uses a library <code class="docutils literal notranslate">libbar</code> if it
is explicitly linked with that library (that is, the library is listed
in the ELF <code class="docutils literal notranslate">NEEDED</code> attribute, caused by adding <code class="docutils literal notranslate">-lbar</code> to the link
line when the binary is created). Other libraries that are needed by
<code class="docutils literal notranslate">libbar</code> are linked indirectly to <code class="docutils literal notranslate">foo</code>, and the dynamic linker
will load them automatically when it loads <code class="docutils literal notranslate">libbar</code>. 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. <code class="docutils literal notranslate">dpkg-shlibdeps</code>
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. <a class="footnote-reference brackets" href="#id28" id="id23">14</a>
<dl class="footnote brackets">
<dt class="label" id="id24"><a class="fn-backref" href="#id19">10</a></dt>
<dd><code class="docutils literal notranslate">dpkg-shlibdeps</code> will use a program like <code class="docutils literal notranslate">objdump</code> or
<code class="docutils literal notranslate">readelf</code> to find the libraries and the symbols in those
libraries directly needed by the binaries or shared libraries in
the package.
</dd>
<dt class="label" id="id25"><a class="fn-backref" href="#id20">11</a></dt>
<dd>The easiest way to call <code class="docutils literal notranslate">dpkg-shlibdeps</code> correctly is to use a
package helper framework such as debhelper. If you are using
debhelper, the <code class="docutils literal notranslate">dh_shlibdeps</code> program will do this work for
you. It will also correctly handle multi-binary packages.
</dd>
<dt class="label" id="id26"><a class="fn-backref" href="#id21">12</a></dt>
<dd><code class="docutils literal notranslate">dh_shlibdeps</code> from the <code class="docutils literal notranslate">debhelper</code> suite will automatically
add this option if it knows it is processing a udeb.
</dd>
<dt class="label" id="id27"><a class="fn-backref" href="#id22">13</a></dt>
<dd>Again, <code class="docutils literal notranslate">dh_shlibdeps</code> and <code class="docutils literal notranslate">dh_gencontrol</code> will handle
everything except the addition of the variable to the control file
for you if you’re using debhelper, including generating separate
<code class="docutils literal notranslate">substvars</code> files for each binary package and calling
<code class="docutils literal notranslate">dpkg-gencontrol</code> with the appropriate flags.
</dd>
<dt class="label" id="id28"><a class="fn-backref" href="#id23">14</a></dt>
<dd>A good example of where this helps is the following: We could
update <code class="docutils literal notranslate">libimlib</code> 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 <code class="docutils literal notranslate">ldd</code> to add
dependencies for every library directly or indirectly linked with a
binary, every package that uses <code class="docutils literal notranslate">libimlib</code> 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 <code class="docutils literal notranslate">NEEDED</code> attribute, packages using <code class="docutils literal notranslate">libimlib</code> can rely
on <code class="docutils literal notranslate">libimlib</code> itself having the dependency on an appropriate
version of <code class="docutils literal notranslate">libdgf</code> and do not need rebuilding.
</dd>
</dl>
</section>
<section id="shared-library-abi-changes">
<h3>8.6.2. Shared library ABI changes<a class="headerlink" href="#shared-library-abi-changes" title="Permalink to this headline">¶</a></h3>
Maintaining a shared library package using either <code class="docutils literal notranslate">symbols</code> or
<code class="docutils literal notranslate">shlibs</code> files requires being aware of the exposed ABI of the shared
library and any changes to it. Both <code class="docutils literal notranslate">symbols</code> and <code class="docutils literal notranslate">shlibs</code> files
record every change to the ABI of the shared library; <code class="docutils literal notranslate">symbols</code> files
do so per public symbol, whereas <code class="docutils literal notranslate">shlibs</code> 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. <a class="footnote-reference brackets" href="#id30" id="id29">15</a> 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
<code class="docutils literal notranslate">SONAME</code> 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 <a class="reference internal" href="#s-sharedlibs-runtime">Run-time shared libraries</a>. 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 <code class="docutils literal notranslate">symbols</code> files or updating the
version in the dependencies in <code class="docutils literal notranslate">shlibs</code> files. For more information on
how to do this in the two formats, see <a class="reference internal" href="#s-symbols">The symbols File Format</a> and
<a class="reference internal" href="#s-shlibs">The shlibs File Format</a>. 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 <code class="docutils literal notranslate">symbols</code> files) or update the
dependency version (for <code class="docutils literal notranslate">shlibs</code>) 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:
<div class="highlight-default notranslate"><div class="highlight"><pre>enum library_op { OP_FOO, OP_BAR };
int library_do_operation(enum library_op);
</pre></div>
</div>
If a new operation, <code class="docutils literal notranslate">OP_BAZ</code>, is added, the minimal-version of
<code class="docutils literal notranslate">library_do_operation</code> (for <code class="docutils literal notranslate">symbols</code> files) or the version in the
dependency for the shared library (for <code class="docutils literal notranslate">shlibs</code> files) must be
increased to the version at which <code class="docutils literal notranslate">OP_BAZ</code> was introduced. Otherwise,
a binary built against the new version of the library (having detected
at compile-time that the library supports <code class="docutils literal notranslate">OP_BAZ</code>) may be installed
with a shared library that doesn’t support <code class="docutils literal notranslate">OP_BAZ</code> and will fail at
runtime when it tries to pass <code class="docutils literal notranslate">OP_BAZ</code> into this function.
Dependency versions in either <code class="docutils literal notranslate">symbols</code> or <code class="docutils literal notranslate">shlibs</code> 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 <code class="docutils literal notranslate">~</code> 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.
<dl class="footnote brackets">
<dt class="label" id="id30"><a class="fn-backref" href="#id29">15</a></dt>
<dd>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 <code class="docutils literal notranslate">Breaks</code> 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.
</dd>
</dl>
</section>
<section id="the-symbols-system">
<h3>8.6.3. The <code class="docutils literal notranslate">symbols</code> system<a class="headerlink" href="#the-symbols-system" title="Permalink to this headline">¶</a></h3>
In the following sections, we will first describe where the various
<code class="docutils literal notranslate">symbols</code> files are to be found, then the <code class="docutils literal notranslate">symbols</code> file format, and
finally how to create <code class="docutils literal notranslate">symbols</code> files if your package contains a
shared library.
<section id="the-symbols-files-present-on-the-system">
<h4>8.6.3.1. The <code class="docutils literal notranslate">symbols</code> files present on the system<a class="headerlink" href="#the-symbols-files-present-on-the-system" title="Permalink to this headline">¶</a></h4>
<code class="docutils literal notranslate">symbols</code> 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 <code class="docutils literal notranslate">dpkg-shlibdeps</code>. The first one that contains the required
information is used.
<dl>
<dt><code class="docutils literal notranslate">debian/*/DEBIAN/symbols</code></dt><dd>During the package build, if the package itself contains shared
libraries with <code class="docutils literal notranslate">symbols</code> files, they will be generated in these
staging directories by <code class="docutils literal notranslate">dpkg-gensymbols</code> (see <a class="reference external" href="#s-providing-symbols">Providing a symbols
file</a>). <code class="docutils literal notranslate">symbols</code> files found in the build
tree take precedence over <code class="docutils literal notranslate">symbols</code> files from other binary
packages.
These files must exist before <code class="docutils literal notranslate">dpkg-shlibdeps</code> 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 <code class="docutils literal notranslate">dpkg-gensymbols</code> must be run before
<code class="docutils literal notranslate">dpkg-shlibdeps</code> during the package build. <a class="footnote-reference brackets" href="#id32" id="id31">16</a>
</dd>
<dt><code class="docutils literal notranslate">/etc/dpkg/symbols/package.symbols.arch</code> and <code class="docutils literal notranslate">/etc/dpkg/symbols/package.symbols</code></dt><dd>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.
</dd>
<dt><code class="docutils literal notranslate">symbols</code> control files for packages installed on the system</dt><dd>The <code class="docutils literal notranslate">symbols</code> 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 <code class="docutils literal notranslate">dpkg-query --control-show package symbols</code>.
</dd>
</dl>
Be aware that if a <code class="docutils literal notranslate">debian/shlibs.local</code> exists in the source package,
it will override any <code class="docutils literal notranslate">symbols</code> files. This is the only case where a
<code class="docutils literal notranslate">shlibs</code> is used despite <code class="docutils literal notranslate">symbols</code> files being present. See
<a class="reference internal" href="#s-shlibs-paths">The shlibs files present on the system</a> and <a class="reference internal" href="#s-sharedlibs-shlibdeps">The shlibs system</a> for more
information.
<dl class="footnote brackets">
<dt class="label" id="id32"><a class="fn-backref" href="#id31">16</a></dt>
<dd>An example may clarify. Suppose the source package <code class="docutils literal notranslate">foo</code>
generates two binary packages, <code class="docutils literal notranslate">libfoo2</code> and
<code class="docutils literal notranslate">foo-runtime</code>. When building the binary packages, the contents of
the packages are staged in the directories <code class="docutils literal notranslate">debian/libfoo2</code> and
<code class="docutils literal notranslate">debian/foo-runtime</code> respectively. (<code class="docutils literal notranslate">debian/tmp</code> could be used
instead of one of these.) Since <code class="docutils literal notranslate">libfoo2</code> provides the
<code class="docutils literal notranslate">libfoo</code> shared library, it will contain a <code class="docutils literal notranslate">symbols</code> file,
which will be installed in <code class="docutils literal notranslate">debian/libfoo2/DEBIAN/symbols</code>,
eventually to be included as a control file in that package. When
<code class="docutils literal notranslate">dpkg-shlibdeps</code> is run on the executable
<code class="docutils literal notranslate">debian/foo-runtime/usr/bin/foo-prog</code>, it will examine the
<code class="docutils literal notranslate">debian/libfoo2/DEBIAN/symbols</code> file to determine whether
<code class="docutils literal notranslate">foo-prog</code>’s library dependencies are satisfied by any of the
libraries provided by <code class="docutils literal notranslate">libfoo2</code>. Since those binaries were linked
against the just-built shared library as part of the build process,
the <code class="docutils literal notranslate">symbols</code> file for the newly-built <code class="docutils literal notranslate">libfoo2</code> must take
precedence over a <code class="docutils literal notranslate">symbols</code> file for any other <code class="docutils literal notranslate">libfoo2</code>
package already installed on the system.
</dd>
</dl>
</section>
<section id="the-symbols-file-format">
<h4>8.6.3.2. The <code class="docutils literal notranslate">symbols</code> File Format<a class="headerlink" href="#the-symbols-file-format" title="Permalink to this headline">¶</a></h4>
The following documents the format of the <code class="docutils literal notranslate">symbols</code> control file as
included in binary packages. These files are built from template
<code class="docutils literal notranslate">symbols</code> files in the source package by <code class="docutils literal notranslate">dpkg-gensymbols</code>. The
template files support a richer syntax that allows <code class="docutils literal notranslate">dpkg-gensymbols</code> to
do some of the tedious work involved in maintaining <code class="docutils literal notranslate">symbols</code> files,
such as handling C++ symbols or optional symbols that may not exist on
particular architectures. When writing <code class="docutils literal notranslate">symbols</code> files for a shared
library package, refer to dpkg-gensymbols(1) for the richer
syntax.
A <code class="docutils literal notranslate">symbols</code> may contain one or more entries, one for each shared
library contained in the package corresponding to that <code class="docutils literal notranslate">symbols</code>. Each
entry has the following format:
<div class="highlight-default notranslate"><div class="highlight"><pre>library-soname main-dependency-template
 [| alternative-dependency-template]
 [...]
 [* field-name: field-value]
 [...]
 symbol minimal-version[ id-of-dependency-template]
</pre></div>
</div>
To explain this format, we’ll use the <code class="docutils literal notranslate">zlib1g</code> package as an example,
which (at the time of writing) installs the shared library
<code class="docutils literal notranslate">/usr/lib/libz.so.1.2.3.4</code>. Mandatory lines will be described first,
followed by optional lines.
<code class="docutils literal notranslate">library-soname</code> must contain exactly the value of the ELF <code class="docutils literal notranslate">SONAME</code>
attribute of the shared library. In our example, this is <code class="docutils literal notranslate">libz.so.1</code>.
<a class="footnote-reference brackets" href="#id36" id="id33">17</a>
<code class="docutils literal notranslate">main-dependency-template</code> has the same syntax as a dependency field
in a binary package control file, except that the string <code class="docutils literal notranslate">#MINVER#</code>
is replaced by a version restriction like <code class="docutils literal notranslate">(&gt;= version)</code> 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, <code class="docutils literal notranslate">main-dependency-template</code> will be
<code class="docutils literal notranslate">package #MINVER#</code>, 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 <code class="docutils literal notranslate">zlib1g</code> <code class="docutils literal notranslate">symbols</code> file would
be:
<div class="highlight-default notranslate"><div class="highlight"><pre>libz.so.1 zlib1g #MINVER#
</pre></div>
</div>
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
<code class="docutils literal notranslate">&#64;</code> and the symbol version, or the string <code class="docutils literal notranslate">Base</code> if there is no
symbol version. <code class="docutils literal notranslate">minimal-version</code> 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. <code class="docutils literal notranslate">id-of-dependency-template</code> is an optional
field that references an <code class="docutils literal notranslate">alternative-dependency-template</code>; see
below for a full description.
For example, <code class="docutils literal notranslate">libz.so.1</code> contains the symbols <code class="docutils literal notranslate">compress</code> and
<code class="docutils literal notranslate">compressBound</code>. <code class="docutils literal notranslate">compress</code> has no symbol version and last changed
its behavior in upstream version <code class="docutils literal notranslate">1:1.1.4</code>. <code class="docutils literal notranslate">compressBound</code> has the
symbol version <code class="docutils literal notranslate">ZLIB_1.2.0</code>, was introduced in upstream version
<code class="docutils literal notranslate">1:1.2.0</code>, and has not changed its behavior. Its <code class="docutils literal notranslate">symbols</code> file
therefore contains the lines:
<div class="highlight-default notranslate"><div class="highlight"><pre>compress@Base 1:1.1.4
compressBound@ZLIB_1.2.0 1:1.2.0
</pre></div>
</div>
Packages using only <code class="docutils literal notranslate">compress</code> would then get a dependency on
<code class="docutils literal notranslate">zlib1g (&gt;= 1:1.1.4)</code>, but packages using <code class="docutils literal notranslate">compressBound</code> would get
a dependency on <code class="docutils literal notranslate">zlib1g (&gt;= 1:1.2.0)</code>.
One or more <code class="docutils literal notranslate">alternative-dependency-template</code> 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 <code class="docutils literal notranslate">id-of-dependency-template</code>
field. The first alternative dependency template is numbered 1, the
second 2, and so forth. <a class="footnote-reference brackets" href="#id37" id="id34">18</a>
Finally, the entry for the library may contain one or more metadata
fields. Currently, the only supported field-name is
<code class="docutils literal notranslate">Build-Depends-Package</code>, whose value lists the <a class="reference external" href="#s-sharedlibs-dev">library development
package</a> on which packages using this shared library
declare a build dependency. If this field is present, <code class="docutils literal notranslate">dpkg-shlibdeps</code>
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. <a class="footnote-reference brackets" href="#id38" id="id35">19</a> For our example, the
<code class="docutils literal notranslate">zlib1g</code> <code class="docutils literal notranslate">symbols</code> file would contain:
<div class="highlight-default notranslate"><div class="highlight"><pre>* Build-Depends-Package: zlib1g-dev
</pre></div>
</div>
Also see deb-symbols(5).
<dl class="footnote brackets">
<dt class="label" id="id36"><a class="fn-backref" href="#id33">17</a></dt>
<dd>This can be determined by using the command
<div class="highlight-default notranslate"><div class="highlight"><pre>readelf -d /usr/lib/libz.so.1.2.3.4 | grep SONAME
</pre></div>
</div>
</dd>
<dt class="label" id="id37"><a class="fn-backref" href="#id34">18</a></dt>
<dd>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 <code class="docutils literal notranslate">symbols</code> file:
<div class="highlight-default notranslate"><div class="highlight"><pre>libGL.so.1 libgl1
 | libgl1-mesa-glx #MINVER#
 publicGlSymbol@Base 6.3-1 [...]
 implementationSpecificSymbol@Base 6.5.2-7 1
 [...]
</pre></div>
</div>
Binaries or shared libraries using only <code class="docutils literal notranslate">publicGlSymbol</code> would
depend only on <code class="docutils literal notranslate">libgl1</code> (which may be provided by multiple
packages), but ones using <code class="docutils literal notranslate">implementationSpecificSymbol</code> would
get a dependency on <code class="docutils literal notranslate">libgl1-mesa-glx (&gt;= 6.5.2-7)</code>.
</dd>
<dt class="label" id="id38"><a class="fn-backref" href="#id35">19</a></dt>
<dd>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 <code class="docutils literal notranslate">symbols</code>
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.
</dd>
</dl>
</section>
<section id="providing-a-symbols-file">
<h4>8.6.3.3. Providing a <code class="docutils literal notranslate">symbols</code> file<a class="headerlink" href="#providing-a-symbols-file" title="Permalink to this headline">¶</a></h4>
If your package provides a shared library, you should arrange to include
a <code class="docutils literal notranslate">symbols</code> control file following the format described above in that
package. You must include either a <code class="docutils literal notranslate">symbols</code> control file or a
<code class="docutils literal notranslate">shlibs</code> control file.
Normally, this is done by creating a <code class="docutils literal notranslate">symbols</code> in the source package
named <code class="docutils literal notranslate">debian/package.symbols</code> or <code class="docutils literal notranslate">debian/symbols</code>, possibly with
<code class="docutils literal notranslate">.arch</code> appended if the symbols information varies by architecture.
This file may use the extended syntax documented in
dpkg-gensymbols(1). Then, call <code class="docutils literal notranslate">dpkg-gensymbols</code> as part of
the package build process. It will create <code class="docutils literal notranslate">symbols</code> files in the package
staging area based on the binaries and libraries in the package staging
area and the <code class="docutils literal notranslate">symbols</code> files in the source package. <a class="footnote-reference brackets" href="#id40" id="id39">20</a>
Packages that provide <code class="docutils literal notranslate">symbols</code> files must keep them up-to-date to
ensure correct dependencies in packages that use the shared libraries.
This means updating the <code class="docutils literal notranslate">symbols</code> 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
<a class="reference internal" href="#s-sharedlibs-updates">Shared library ABI changes</a>), and changing the library-soname and
main-dependency-template, and probably all of the minimal-version fields,
when the library changes <code class="docutils literal notranslate">SONAME</code>. Removing a public symbol from the
<code class="docutils literal notranslate">symbols</code> file because it’s no longer provided by the library normally
requires changing the <code class="docutils literal notranslate">SONAME</code> of the library. See
<a class="reference internal" href="#s-sharedlibs-runtime">Run-time shared libraries</a> for more information on <code class="docutils literal notranslate">SONAME</code>s.
<dl class="footnote brackets">
<dt class="label" id="id40"><a class="fn-backref" href="#id39">20</a></dt>
<dd>If you are using <code class="docutils literal notranslate">debhelper</code>, <code class="docutils literal notranslate">dh_makeshlibs</code> will take care of
calling either <code class="docutils literal notranslate">dpkg-gensymbols</code> or generating a <code class="docutils literal notranslate">shlibs</code> file
as appropriate.
</dd>
</dl>
</section>
</section>
<section id="the-shlibs-system">
<h3>8.6.4. The <code class="docutils literal notranslate">shlibs</code> system<a class="headerlink" href="#the-shlibs-system" title="Permalink to this headline">¶</a></h3>
The <code class="docutils literal notranslate">shlibs</code> system is a simpler alternative to the <code class="docutils literal notranslate">symbols</code> 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 <code class="docutils literal notranslate">symbols</code> system and is
therefore frequently seen in older packages. It is also required for
udebs, which do not support <code class="docutils literal notranslate">symbols</code>.
In the following sections, we will first describe where the various
<code class="docutils literal notranslate">shlibs</code> files are to be found, then how to use <code class="docutils literal notranslate">dpkg-shlibdeps</code>,
and finally the <code class="docutils literal notranslate">shlibs</code> file format and how to create them.
<section id="the-shlibs-files-present-on-the-system">
<h4>8.6.4.1. The <code class="docutils literal notranslate">shlibs</code> files present on the system<a class="headerlink" href="#the-shlibs-files-present-on-the-system" title="Permalink to this headline">¶</a></h4>
There are several places where <code class="docutils literal notranslate">shlibs</code> files are found. The following
list gives them in the order in which they are read by
<code class="docutils literal notranslate">dpkg-shlibdeps</code>. (The first one which gives the required information
is used.)
<dl class="simple">
<dt><code class="docutils literal notranslate">debian/shlibs.local</code></dt><dd>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 <code class="docutils literal notranslate">shlibs</code>
file for a library cannot be used. This file overrides information
obtained from any other source.
</dd>
<dt><code class="docutils literal notranslate">/etc/dpkg/shlibs.override</code></dt><dd>This lists global overrides. This list is normally empty. It is
maintained by the local system administrator.
</dd>
<dt><code class="docutils literal notranslate">DEBIAN/shlibs</code> files in the “build directory”</dt><dd>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.
</dd>
<dt><code class="docutils literal notranslate">shlibs</code> control files for packages installed on the system</dt><dd>The <code class="docutils literal notranslate">shlibs</code> control files for all the packages currently installed
on the system. These files can be read using
<code class="docutils literal notranslate">dpkg-query --control-show package shlibs</code>.
</dd>
<dt><code class="docutils literal notranslate">/etc/dpkg/shlibs.default</code></dt><dd>This file lists any shared libraries whose packages have failed to
provide correct <code class="docutils literal notranslate">shlibs</code> files. It was used when the <code class="docutils literal notranslate">shlibs</code>
setup was first introduced, but it is now normally empty. It is
maintained by the <code class="docutils literal notranslate">dpkg</code> maintainer.
</dd>
</dl>
If a <code class="docutils literal notranslate">symbols</code> file for a shared library package is available,
<code class="docutils literal notranslate">dpkg-shlibdeps</code> will always use it in preference to a <code class="docutils literal notranslate">shlibs</code>,
with the exception of <code class="docutils literal notranslate">debian/shlibs.local</code>. The latter overrides any
other <code class="docutils literal notranslate">shlibs</code> or <code class="docutils literal notranslate">symbols</code> files.
</section>
<section id="the-shlibs-file-format">
<h4>8.6.4.2. The <code class="docutils literal notranslate">shlibs</code> File Format<a class="headerlink" href="#the-shlibs-file-format" title="Permalink to this headline">¶</a></h4>
Each <code class="docutils literal notranslate">shlibs</code> file has the same format. Lines beginning with <code class="docutils literal notranslate">#</code> are
considered to be comments and are ignored. Each line is of the form:
<div class="highlight-default notranslate"><div class="highlight"><pre>[type: ]library-name soname-version dependencies ...
</pre></div>
</div>
We will explain this by reference to the example of the <code class="docutils literal notranslate">zlib1g</code>
package, which (at the time of writing) installs the shared library
<code class="docutils literal notranslate">/usr/lib/libz.so.1.2.3.4</code>.
<code class="docutils literal notranslate">type</code> is an optional element that indicates the type of package for which
the line is valid. The only type currently in use is <code class="docutils literal notranslate">udeb</code>. The colon
and space after the type are required.
<code class="docutils literal notranslate">library-name</code> is the name of the shared library, in this case <code class="docutils literal notranslate">libz</code>.
(This must match the name part of the soname, see below.)
<code class="docutils literal notranslate">soname-version</code> is the version part of the ELF <code class="docutils literal notranslate">SONAME</code> attribute of
the library, determined the same way that the soversion component of the
recommended shared library package name is determined. See
<a class="reference internal" href="#s-sharedlibs-runtime">Run-time shared libraries</a> for the details.
<code class="docutils literal notranslate">dependencies</code> 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 <a class="reference internal" href="ch-relationships.html#s-depsyntax">Syntax of relationship fields</a> for
details on the syntax, and <a class="reference internal" href="#s-sharedlibs-updates">Shared library ABI changes</a>
for details on how to maintain the dependency version constraint.
In our example, if the last change to the <code class="docutils literal notranslate">zlib1g</code> package that could
change behavior for a client of that library was in version
<code class="docutils literal notranslate">1:1.2.3.3.dfsg-1</code>, then the <code class="docutils literal notranslate">shlibs</code> entry for this library could
say:
<div class="highlight-default notranslate"><div class="highlight"><pre>libz 1 zlib1g (&gt;= 1:1.2.3.3.dfsg)
</pre></div>
</div>
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:
<div class="highlight-default notranslate"><div class="highlight"><pre>udeb: libz 1 zlib1g-udeb (&gt;= 1:1.2.3.3.dfsg)
</pre></div>
</div>
</section>
<section id="providing-a-shlibs-file">
<h4>8.6.4.3. Providing a <code class="docutils literal notranslate">shlibs</code> file<a class="headerlink" href="#providing-a-shlibs-file" title="Permalink to this headline">¶</a></h4>
To provide a <code class="docutils literal notranslate">shlibs</code> file for a shared library binary package, create
a <code class="docutils literal notranslate">shlibs</code> file following the format described above and place it in
the <code class="docutils literal notranslate">DEBIAN</code> directory for that package during the build. It will then
be included as a control file for that package. <a class="footnote-reference brackets" href="#id42" id="id41">21</a>
Since <code class="docutils literal notranslate">dpkg-shlibdeps</code> reads the <code class="docutils literal notranslate">DEBIAN/shlibs</code> files in all of the
binary packages being built from this source package, all of the
<code class="docutils literal notranslate">DEBIAN/shlibs</code> files should be installed before <code class="docutils literal notranslate">dpkg-shlibdeps</code> is
called on any of the binary packages.
<dl class="footnote brackets">
<dt class="label" id="id42"><a class="fn-backref" href="#id41">21</a></dt>
<dd>This is what <code class="docutils literal notranslate">dh_makeshlibs</code> in the debhelper suite does. If your
package also has a udeb that provides a shared library,
<code class="docutils literal notranslate">dh_makeshlibs</code> can automatically generate the <code class="docutils literal notranslate">udeb:</code> lines if
you specify the name of the udeb with the <code class="docutils literal notranslate">--add-udeb</code> option.
</dd>
</dl>
</section>
</section>
</section>
</section>

<div class="clearer"></div>
 </div>
 </div>
 </div>
 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 <div class="sphinxsidebarwrapper">
 <h3><a href="index.html">Table of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#">8. Shared libraries</a><ul>
<li><a class="reference internal" href="#run-time-shared-libraries">8.1. Run-time shared libraries</a><ul>
<li><a class="reference internal" href="#ldconfig">8.1.1. <code class="docutils literal notranslate">ldconfig</code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#shared-library-support-files">8.2. Shared library support files</a></li>
<li><a class="reference internal" href="#static-libraries">8.3. Static libraries</a></li>
<li><a class="reference internal" href="#development-files">8.4. Development files</a></li>
<li><a class="reference internal" href="#dependencies-between-the-packages-of-the-same-library">8.5. Dependencies between the packages of the same library</a></li>
<li><a class="reference internal" href="#dependencies-between-the-library-and-other-packages">8.6. Dependencies between the library and other packages</a><ul>
<li><a class="reference internal" href="#generating-dependencies-on-shared-libraries">8.6.1. Generating dependencies on shared libraries</a></li>
<li><a class="reference internal" href="#shared-library-abi-changes">8.6.2. Shared library ABI changes</a></li>
<li><a class="reference internal" href="#the-symbols-system">8.6.3. The <code class="docutils literal notranslate">symbols</code> system</a><ul>
<li><a class="reference internal" href="#the-symbols-files-present-on-the-system">8.6.3.1. The <code class="docutils literal notranslate">symbols</code> files present on the system</a></li>
<li><a class="reference internal" href="#the-symbols-file-format">8.6.3.2. The <code class="docutils literal notranslate">symbols</code> File Format</a></li>
<li><a class="reference internal" href="#providing-a-symbols-file">8.6.3.3. Providing a <code class="docutils literal notranslate">symbols</code> file</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-shlibs-system">8.6.4. The <code class="docutils literal notranslate">shlibs</code> system</a><ul>
<li><a class="reference internal" href="#the-shlibs-files-present-on-the-system">8.6.4.1. The <code class="docutils literal notranslate">shlibs</code> files present on the system</a></li>
<li><a class="reference internal" href="#the-shlibs-file-format">8.6.4.2. The <code class="docutils literal notranslate">shlibs</code> File Format</a></li>
<li><a class="reference internal" href="#providing-a-shlibs-file">8.6.4.3. Providing a <code class="docutils literal notranslate">shlibs</code> file</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="ch-relationships.html"
 title="previous chapter">7. Declaring relationships between packages</a>
 <h4>Next topic</h4>
 <a href="ch-opersys.html"
 title="next chapter">9. The Operating System</a>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="_sources/ch-sharedlibs.rst.txt"
 rel="nofollow">Show Source</a></li>
 </ul>
 </div>
<div id="searchbox" style="display: none" role="search">
 <h3 id="searchlabel">Quick search</h3>
 <div class="searchformwrapper">
 <form class="search" action="search.html" method="get">
 <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
 <input type="submit" value="Go" />
 </form>
 </div>
</div>
<script>$('#searchbox').show(0);</script>
 </div>
 </div>
 <div class="clearer"></div>
 </div>
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="genindex.html" title="General Index"
 >index</a></li>
 <li class="right" >
 <a href="ch-opersys.html" title="9. The Operating System"
 >next</a> |</li>
 <li class="right" >
 <a href="ch-relationships.html" title="7. Declaring relationships between packages"
 >previous</a> |</li>
 <li class="nav-item nav-item-0"><a href="index.html">Debian Policy Manual v4.6.0.1</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">8. Shared libraries</a></li> 
 </ul>
 </div>
 <div class="footer" role="contentinfo">
 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.2.0.
 </div>
 </body>
</html>

${this.title}

Code Editor : ch-sharedlibs.html