- <p>
- Instead, either create another package for the runtime binaries
- (this package might typically be named
- <package><var>libraryname</var>-runtime</package>; note the absence
- of the <var>soversion</var> in the package name), or if the
- development package is small, include them in there.
- </p>
- </sect>
-
- <sect id="sharedlibs-static">
- <heading>Static libraries</heading>
-
- <p>
- The static library (<file><var>libraryname.a</var></file>)
- is usually provided in addition to the shared version.
- It is placed into the development package (see below).
- </p>
-
- <p>
- In some cases, it is acceptable for a library to be
- available in static form only; these cases include:
- <list>
- <item>libraries for languages whose shared library support
- is immature or unstable</item>
- <item>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)</item>
- <item>libraries which are explicitly intended to be
- available only in static form by their upstream
- author(s)</item>
- </list>
- </p>
-
- <sect id="sharedlibs-dev">
- <heading>Development files</heading>
-
- <p>
- The development files associated to a shared library need to be
- placed in a package called
- <package><var>libraryname</var><var>soversion</var>-dev</package>,
- or if you prefer only to support one development version at a
- time, <package><var>libraryname</var>-dev</package>.
- </p>
-
- <p>
- In case several development versions of a library exist, you may
- need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
- <ref id="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 installed).
- </p>
-
- <p>
- The development package should contain a symlink for the associated
- shared library without a version number. For example, the
- <package>libgdbmg1-dev</package> package should include a symlink
- from <file>/usr/lib/libgdbm.so</file> to
- <file>libgdbm.so.1.7.3</file>. This symlink is needed by the linker
- (<prgn>ld</prgn>) when compiling packages, as it will only look for
- <file>libgdbm.so</file> when compiling dynamically.
- </p>
- </sect>
-
- <sect id="sharedlibs-intradeps">
- <heading>Dependencies between the packages of the same library</heading>
-
- <p>
- Typically the development version should have an exact
- version dependency on the runtime library, to make sure that
- compilation and linking happens correctly. The
- <tt>${Source-Version}</tt> substitution variable can be
- useful for this purpose.
- </p>
- </sect>
-
- <sect id="sharedlibs-shlibdeps">
- <heading>Dependencies between the library and other packages -
- the <tt>shlibs</tt> system</heading>
-
- <p>
- 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. This requirement led to the creation of the
- <tt>shlibs</tt> system, which is very simple in its design:
- any package which <em>provides</em> a shared library also
- provides information on the package dependencies required to
- ensure the presence of this library, and any package which
- <em>uses</em> a shared library uses this information to
- determine the dependencies it requires. The files which
- contain the mapping from shared libraries to the necessary
- dependency information are called <file>shlibs</file> files.
- </p>
-
- <p>
- Thus, when a package is built which contains any shared
- libraries, it must provide a <file>shlibs</file> file for other
- packages to use, and when a package is built which contains
- any shared libraries or compiled binaries, it must run
- <prgn>dpkg-shlibdeps</prgn> on these to determine the
- libraries used and hence the dependencies needed by this
- package.<footnote>
- <p>
- In the past, the shared libraries linked to were
- determined by calling <prgn>ldd</prgn>, but now
- <prgn>objdump</prgn> is used to do this. The only
- change this makes to package building is that
- <prgn>dpkg-shlibdeps</prgn> must also be run on shared
- libraries, whereas in the past this was unnecessary.
- The rest of this footnote explains the advantage that
- this method gives.
- </p>
-
- <p>
- We say that a binary <tt>foo</tt> <em>directly</em> uses
- a library <tt>libbar</tt> if it is explicitly linked
- with that library (that is, it uses the flag
- <tt>-lbar</tt> during the linking stage). Other
- libraries that are needed by <tt>libbar</tt> are linked
- <em>indirectly</em> to <tt>foo</tt>, and the dynamic
- linker will load them automatically when it loads
- <tt>libbar</tt>. A package should depend on
- the libraries it directly uses, and the dependencies for
- those libraries should automatically pull in the other
- libraries.
- </p>
-
- <p>
- Unfortunately, the <prgn>ldd</prgn> program shows both
- the directly and indirectly used libraries, meaning that
- the dependencies determined included both direct and
- indirect dependencies. The use of <prgn>objdump</prgn>
- avoids this problem by determining only the directly
- used libraries.
- </p>
-
- <p>
- A good example of where this helps is the following. We
- could update <tt>libimlib</tt> with a new version that
- supports a new graphics format called dgf (but retaining
- the same major version number). If we used the old
- <prgn>ldd</prgn> method, every package that uses
- <tt>libimlib</tt> would need to be recompiled so it
- would also depend on <tt>libdgf</tt> or it wouldn't run
- due to missing symbols. However with the new system,
- packages using <tt>libimlib</tt> can rely on
- <tt>libimlib</tt> itself having the dependency on
- <tt>libdgf</tt> and so they would not need rebuilding.
- </p>
- </footnote>
- </p>
-
- <p>
- In the following sections, we will first describe where the
- various <tt>shlibs</tt> files are to be found, then how to
- use <prgn>dpkg-shlibdeps</prgn>, and finally the
- <tt>shlibs</tt> file format and how to create them if your
- package contains a shared library.
- </p>
-
- <sect1>
- <heading>The <tt>shlibs</tt> files present on the system</heading>
-
- <p>
- There are several places where <tt>shlibs</tt> files are
- found. The following list gives them in the order in which
- they are read by <prgn>dpkg-shlibdeps</prgn>. (The first
- one which gives the required information is used.)
- </p>