<tt><url name="/doc/developers-reference/"
id="http://www.debian.org/doc/developers-reference/"></tt>.
</p>
+
+ <p>
+ Finally, a <qref id="copyrightformat">specification for
+ machine-readable copyright files</qref> is maintained as part of
+ the <package>debian-policy</package> package using the same
+ procedure as the other policy documents. Use of this format is
+ optional.
+ </p>
</sect>
<sect id="definitions">
<p>
The Debian archive maintainers provide the authoritative
list of sections. At present, they are:
- <em>admin</em>, <em>cli-mono</em>, <em>comm</em>, <em>database</em>,
- <em>devel</em>, <em>debug</em>, <em>doc</em>, <em>editors</em>,
- <em>education</em>, <em>electronics</em>, <em>embedded</em>,
- <em>fonts</em>, <em>games</em>, <em>gnome</em>, <em>graphics</em>,
- <em>gnu-r</em>, <em>gnustep</em>, <em>hamradio</em>, <em>haskell</em>,
- <em>httpd</em>, <em>interpreters</em>, <em>introspection</em>,
- <em>java</em>, <em>kde</em>, <em>kernel</em>, <em>libs</em>,
- <em>libdevel</em>, <em>lisp</em>, <em>localization</em>,
- <em>mail</em>, <em>math</em>, <em>metapackages</em>, <em>misc</em>,
- <em>net</em>, <em>news</em>, <em>ocaml</em>, <em>oldlibs</em>,
- <em>otherosfs</em>, <em>perl</em>, <em>php</em>, <em>python</em>,
- <em>ruby</em>, <em>science</em>, <em>shells</em>, <em>sound</em>,
- <em>tex</em>, <em>text</em>, <em>utils</em>, <em>vcs</em>,
- <em>video</em>, <em>web</em>, <em>x11</em>, <em>xfce</em>,
- <em>zope</em>. The additional section <em>debian-installer</em>
+admin,
+cli-mono,
+comm,
+database,
+debug,
+devel,
+doc,
+editors,
+education,
+electronics,
+embedded,
+fonts,
+games,
+gnome,
+gnu-r,
+gnustep,
+graphics,
+hamradio,
+haskell,
+httpd,
+interpreters,
+introspection,
+java,
+kde,
+kernel,
+libdevel,
+libs,
+lisp,
+localization,
+mail,
+math,
+metapackages,
+misc,
+net,
+news,
+ocaml,
+oldlibs,
+otherosfs,
+perl,
+php,
+python,
+ruby,
+science,
+shells,
+sound,
+tasks,
+tex,
+text,
+utils,
+vcs,
+video,
+web,
+x11,
+xfce,
+zope.
+ The additional section <em>debian-installer</em>
contains special packages used by the installer and is not used
for normal Debian packages.
</p>
</p>
</item>
- <tag><tt>build-arch</tt> (optional),
- <tt>build-indep</tt> (optional)
+ <tag><tt>build-arch</tt> (required),
+ <tt>build-indep</tt> (required)
</tag>
<item>
<p>
- A package may also provide both of the targets
- <tt>build-arch</tt> and <tt>build-indep</tt>.
- The <tt>build-arch</tt> target, if provided, should
+ The <tt>build-arch</tt> target must
perform all the configuration and compilation required for
producing all architecture-dependant binary packages
(those packages for which the body of the
<tt>Architecture</tt> field in <tt>debian/control</tt> is
not <tt>all</tt>). Similarly, the <tt>build-indep</tt>
- target, if provided, should perform all the configuration
+ target must perform all the configuration
and compilation required for producing all
architecture-independent binary packages (those packages
for which the body of the <tt>Architecture</tt> field
in <tt>debian/control</tt> is <tt>all</tt>).
- The <tt>build</tt> target should depend on those of the
- targets <tt>build-arch</tt> and <tt>build-indep</tt> that
- are provided in the rules file.<footnote>
- The intent of this split is so that binary-only builds
- need not install the dependencies required for
- the <tt>build-indep</tt> target. However, this is not
- yet used in practice since <tt>dpkg-buildpackage
- -B</tt>, and therefore the autobuilders,
- invoke <tt>build</tt> rather than <tt>build-arch</tt>
- due to the difficulties in determining whether the
- optional <tt>build-arch</tt> target exists.
+ The <tt>build</tt> target
+ should either depend on those targets or take the same
+ actions as invoking those targets would perform.<footnote>
+ This split allows binary-only builds to not install the
+ dependencies required for the <tt>build-indep</tt>
+ target and skip any resource-intensive build tasks that
+ are only required when building architecture-independent
+ binary packages.
</footnote>
</p>
- <p>
- If one or both of the targets <tt>build-arch</tt> and
- <tt>build-indep</tt> are not provided, then invoking
- <file>debian/rules</file> with one of the not-provided
- targets as arguments should produce a exit status code
- of 2. Usually this is provided automatically by make
- if the target is missing.
- </p>
-
<p>
The <tt>build-arch</tt> and <tt>build-indep</tt> targets
must not do anything that might require root privilege.
</p>
<p>
- Each paragraph consists of a series of data fields; each
- field consists of the field name, followed by a colon and
- then the data/value associated with that field. The field
- name is composed of printable ASCII characters (i.e.,
- characters that have values between 33 and 126, inclusive)
- except colon and must not with a begin with #. The
- field ends at the end of the line or at the end of the
- last continuation line (see below). Horizontal whitespace
- (spaces and tabs) may occur immediately before or after the
- value and is ignored there; it is conventional to put a
- single space after the colon. For example, a field might
- be:
+ Each paragraph consists of a series of data fields. Each field
+ consists of the field name followed by a colon and then the
+ data/value associated with that field. The field name is
+ composed of US-ASCII characters excluding control characters,
+ space, and colon (i.e., characters in the ranges 33-57 and
+ 59-126, inclusive). Field names must not begin with the comment
+ character, <tt>#</tt>.
+ </p>
+
+ <p>
+ The field ends at the end of the line or at the end of the last
+ continuation line (see below). Horizontal whitespace (spaces
+ and tabs) may occur immediately before or after the value and is
+ ignored there; it is conventional to put a single space after
+ the colon. For example, a field might be:
<example compact="compact">
Package: libc6
</example>
<item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
- <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
<item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
<item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
</list>
</p>
<item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
<item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="built-using"><tt>Built-Using</tt></qref></item>
</list>
</p>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="built-using"><tt>Built-Using</tt></qref></item>
</list>
</p>
</sect>
<p>
This file consists of a single paragraph, possibly surrounded by
a PGP signature. The fields of that paragraph are listed below.
- Their syntax is described above, in <ref id="pkg-controlfields">.
+ Their syntax is described above, in <ref id="controlsyntax">.
<list compact="compact">
<item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
<item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
- <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ <item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
- and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
+ and <tt>Checksums-Sha256</tt></qref> (mandatory)</item>
<item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
</list>
</p>
<item><qref id="f-Closes"><tt>Closes</tt></qref></item>
<item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
<item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
- and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
+ and <tt>Checksums-Sha256</tt></qref> (mandatory)</item>
<item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
</list>
</p>
</p>
<p>
- In the <file>.dsc</file> file, these fields should list all
+ In the <file>.dsc</file> file, these fields list all
files that make up the source package. In
- the <file>.changes</file> file, these fields should list all
+ the <file>.changes</file> file, these fields list all
files being uploaded. The list of files in these fields
must match the list of files in the <tt>Files</tt> field.
</p>
</sect1>
- <sect1 id="f-DM-Upload-Allowed">
+ <sect1>
<heading><tt>DM-Upload-Allowed</tt></heading>
<p>
- The most recent version of a package uploaded to unstable or
- experimental must include the field <tt>DM-Upload-Allowed:
- yes</tt> in the source section of its source control file for
- the Debian archive to accept uploads signed with a key in the
- Debian Maintainer keyring. See the General
- Resolution <url id="http://www.debian.org/vote/2007/vote_003"
- name="Endorse the concept of Debian Maintainers"> for more
- details.
+ Obsolete, see <qref id="f-DM-Upload-Allowed">below</qref>.
+ </p>
+ </sect1>
+
+ <sect1 id="f-VCS-fields">
+ <heading>Version Control System (VCS) fields</heading>
+
+ <p>
+ Debian source packages are increasingly developed using VCSs. The
+ purpose of the following fields is to indicate a publicly accessible
+ repository where the Debian source package is developed.
+
+ <taglist>
+ <tag><tt>Vcs-Browser</tt></tag>
+ <item>
+ <p>
+ URL of a web interface for browsing the repository.
+ </p>
+ </item>
+
+ <tag>
+ <tt>Vcs-Arch</tt>, <tt>Vcs-Bzr</tt> (Bazaar), <tt>Vcs-Cvs</tt>,
+ <tt>Vcs-Darcs</tt>, <tt>Vcs-Git</tt>, <tt>Vcs-Hg</tt>
+ (Mercurial), <tt>Vcs-Mtn</tt> (Monotone), <tt>Vcs-Svn</tt>
+ (Subversion)
+ </tag>
+ <item>
+ <p>
+ The field name identifies the VCS. The field's value uses the
+ version control system's conventional syntax for describing
+ repository locations and should be sufficient to locate the
+ repository used for packaging. Ideally, it also locates the
+ branch used for development of new versions of the Debian
+ package.
+ </p>
+ <p>
+ In the case of Git, the value consists of a URL, optionally
+ followed by the word <tt>-b</tt> and the name of a branch in
+ the indicated repository, following the syntax of the
+ <tt>git clone</tt> command. If no branch is specified, the
+ packaging should be on the default branch.
+ </p>
+ <p>
+ More than one different VCS may be specified for the same
+ package.
+ </p>
+ </item>
+ </taglist>
</p>
</sect1>
</sect>
</sect>
+ <sect id="obsolete-control-data-fields">
+ <heading>Obsolete fields</heading>
+
+ <p>
+ The following fields have been obsoleted and may be found in packages
+ conforming with previous versions of the Policy.
+ </p>
+
+ <sect1 id="f-DM-Upload-Allowed">
+ <heading><tt>DM-Upload-Allowed</tt></heading>
+
+ <p>
+ Indicates that Debian Maintainers may upload this package to
+ the Debian archive. The only valid value is <tt>yes</tt>. This
+ field was used to regulate uploads by Debian Maintainers, See the
+ General Resolution <url id="http://www.debian.org/vote/2007/vote_003"
+ name="Endorse the concept of Debian Maintainers"> for more details.
+ </p>
+ </sect1>
+
+ </sect>
+
</chapt>
<p>
The relations allowed are <tt><<</tt>, <tt><=</tt>,
- <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
- strictly earlier, earlier or equal, exactly equal, later or
- equal and strictly later, respectively. The deprecated
- forms <tt><</tt> and <tt>></tt> were used to mean
- earlier/later or equal, rather than strictly earlier/later,
- so they should not appear in new packages (though
- <prgn>dpkg</prgn> still supports them).
+ <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for strictly
+ earlier, earlier or equal, exactly equal, later or equal and
+ strictly later, respectively. The deprecated
+ forms <tt><</tt> and <tt>></tt> were confusingly used to
+ mean earlier/later or equal, rather than strictly earlier/later,
+ and must not appear in new packages (though <prgn>dpkg</prgn>
+ still supports them with a warning).
</p>
<p>
</p>
<p>
- For binary relationship fields, the architecture restriction
+ For binary relationship fields and the <tt>Built-Using</tt>
+ field, the architecture restriction
syntax is only supported in the source package control
file <file>debian/control</file>. When the corresponding binary
package control file is generated, the relationship will either
</taglist>
</p>
</sect>
+
+ <sect id="built-using">
+ <heading>Additional source packages used to build the binary
+ - <tt>Built-Using</tt>
+ </heading>
+
+ <p>
+ Some binary packages incorporate parts of other packages when built
+ but do not have to depend on those packages. Examples include
+ linking with static libraries or incorporating source code from
+ another package during the build. In this case, the source packages
+ of those other packages are a required part of the complete source
+ (the binary package is not reproducible without them).
+ </p>
+
+ <p>
+ A <tt>Built-Using</tt> field must list the corresponding source
+ package for any such binary package incorporated during the build
+ <footnote>
+ <tt>Build-Depends</tt> in the source package is not adequate since
+ it (rightfully) does not document the exact version used in the
+ build.
+ </footnote>,
+ including an "exactly equal" ("=") version relation on the version
+ that was used to build that binary package<footnote>
+ The archive software might reject packages that refer to
+ non-existent sources.
+ </footnote>.
+ </p>
+
+ <p>
+ A package using the source code from the gcc-4.6-source
+ binary package built from the gcc-4.6 source package would
+ have this field in its control file:
+ <example compact="compact">
+Built-Using: gcc-4.6 (= 4.6.0-11)
+ </example>
+ </p>
+
+ <p>
+ A package including binaries from grub2 and loadlin would
+ have this field in its control file:
+ <example compact="compact">
+Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
+ </example>
+ </p>
+ </sect>
</chapt>
be placed in a package named
<package><var>libraryname</var><var>soversion</var></package>,
where <var>soversion</var> is the version number in
- the <tt>SONAME</tt> of the shared library.
- See <ref id="shlibs"> for detailed information on how to
- determine this version. Alternatively, if it would be confusing
- to directly append <var>soversion</var>
- to <var>libraryname</var> (if, for example, <var>libraryname</var>
- itself ends in a number), you should use
+ the <tt>SONAME</tt> of the shared library. Alternatively, if it
+ would be confusing to directly append <var>soversion</var>
+ to <var>libraryname</var> (if, for
+ example, <var>libraryname</var> itself ends in a number), you
+ should use
<package><var>libraryname</var>-<var>soversion</var></package>
instead.
</p>
+ <p>
+ To determine the <var>soversion</var>, look at
+ the <tt>SONAME</tt> of the library, stored in the
+ ELF <tt>SONAME</tt> attribute. It is usually of the
+ form <tt><var>name</var>.so.<var>major-version</var></tt> (for
+ example, <tt>libz.so.1</tt>). The version part is the part
+ which comes after <tt>.so.</tt>, so in that example it
+ is <tt>1</tt>. The soname may instead be of the
+ form <tt><var>name</var>-<var>major-version</var>.so</tt>, such
+ as <tt>libdb-5.1.so</tt>, in which case the name would
+ be <tt>libdb</tt> and the version would be <tt>5.1</tt>.
+ </p>
+
<p>
If you have several shared libraries built from the same source
tree, you may lump them all together into a single shared
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 <qref id="sharedlibs-symbols"><tt>symbols</tt> system</qref>
- or the <qref id="sharedlibs-shlibdeps"><tt>shlibs</tt>
- system</qref>.
+ the <qref id="sharedlibs-depends"><tt>symbols</tt>
+ or <tt>shlibs</tt> system</qref>.
</p>
<p>
</p>
</sect>
- <sect id="sharedlibs-symbols">
- <heading>Dependencies between the library and other packages -
- the <tt>symbols</tt> system</heading>
+ <sect id="sharedlibs-depends">
+ <heading>Dependencies between the library and other
+ packages</heading>
<p>
If a package contains a binary or library which links to a
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. To allow these dependencies to be constructed, shared
- libraries must provide either a <file>symbols</file> file or
- a <file>shlibs</file> file, which provide information on the
- package dependencies required to ensure the presence of this
- library. Any package which uses a shared library must use these
- files to determine the required dependencies when it is built.
- </p>
-
- <p>
- <file>shlibs</file> files were the original mechanism for
- handling library dependencies. They are documented
- in <ref id="sharedlibs-shlibdeps">. <file>symbols</file> files,
- documented in this section, are recommended for most packages,
- since they provide dependency information for each exported
- symbol and therefore generate more accurate dependencies for
- binaries that do not use symbols from newer versions of the
- shared library. However, <file>shlibs</file> files must be used
- for udebs. Packages which provide a <file>symbols</file> file
- are not required to provide a <file>shlibs</file> file.
- </p>
-
- <p>
- When a package that contains any shared libraries or compiled
- binaries is built, it must run <prgn>dpkg-shlibdeps</prgn> on
- each shared library and compiled binary to determine the
- libraries used and hence the dependencies needed by the
- package.<footnote>
- <prgn>dpkg-shlibdeps</prgn> will use a program
- like <prgn>objdump</prgn> or <prgn>readelf</prgn> to find the
- libraries and the symbols in those libraries directly needed
- by the binaries or shared libraries in the package.
- </footnote>
- </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, the library is listed in the
- ELF <tt>NEEDED</tt> attribute, caused by adding <tt>-lbar</tt>
- to the link line when the binary is created). 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, but not the libraries it indirectly uses. The
- dependencies for those libraries will automatically pull in the
- other libraries. <prgn>dpkg-shlibdeps</prgn> 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.
- <footnote>
- 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) and depends on <tt>libdgf</tt>. If we
- used <prgn>ldd</prgn> to add dependencies for every library
- directly or indirectly linked with a binary, 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. Since dependencies are only added based on
- ELF <tt>NEEDED</tt> attribute, 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.
+ 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 <file>symbols</file> file or
+ a <file>shlibs</file> 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
+ <tt>dlopen()</tt>) should compute appropriate dependencies
+ using these files at build time as well.
+ </p>
+
+ <p>
+ The two mechanisms differ in the degree of detail that they
+ provide. A <file>symbols</file> 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.
+ </p>
+
+ <p>
+ A <file>shlibs</file> 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 <file>shlibs</file> 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 <file>symbols</file> files if none of the symbols used by the
+ package have changed. This, in turn, may make upgrades
+ needlessly complex and unnecessarily restrict use of the package
+ on systems with older versions of the shared libraries.
+ </p>
+
+ <p>
+ <file>shlibs</file> files also only support a limited range of
+ library SONAMEs, making it difficult to use <file>shlibs</file>
+ files in some unusual corner cases.<footnote>
+ A <file>shlibs</file> file represents an SONAME as a library
+ name and version number, such as <tt>libfoo VERSION</tt>,
+ instead of recording the actual SONAME. If the SONAME doesn't
+ match one of the two expected formats
+ (<tt>libfoo-VERSION.so</tt> or <tt>libfoo.so.VERSION</tt>), it
+ cannot be represented.
</footnote>
</p>
<p>
- In the following sections, we will first describe where the
- various <file>symbols</file> files are to be found, then how to
- use <prgn>dpkg-shlibdeps</prgn>, and finally
- the <file>symbols</file> file format and how to create them if
- your package contains a shared library.
+ <file>symbols</file> files are therefore recommended for most
+ shared library packages since they provide more accurate
+ dependencies. For most C libraries, the additional detail
+ required by <file>symbols</file> files is not too difficult to
+ maintain. However, maintaining exhaustive symbols information
+ for a C++ library can be quite onerous, so <file>shlibs</file>
+ files may be more appropriate for most C++ libraries. Libraries
+ with a corresponding udeb must also provide
+ a <file>shlibs</file> file, since the udeb infrastructure does
+ not use <file>symbols</file> files.
</p>
- <sect1 id="symbols-paths">
- <heading>The <file>symbols</file> files present on the
- system</heading>
-
- <p>
- <file>symbols</file> files for a shared library are normally
- provided by the shared library package, 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 <prgn>dpkg-shlibdeps</prgn>
- The first one that contains the required information is used.
- <list>
- <item>
- <p><file>debian/*/DEBIAN/symbols</file></p>
-
- <p>
- During the package build, if the package itself contains
- shared libraries with <file>symbols</file> files, they
- will be generated in these staging directories
- by <prgn>dpkg-gensymbols</prgn>. <file>symbols</file>
- files found in the build tree take precedence
- over <file>symbols</file> files from other binary
- packages.
- </p>
-
- <p>
- These files must exist
- before <prgn>dpkg-shlibdeps</prgn> 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 <prgn>dpkg-gensymbols</prgn> must be run
- before <prgn>dpkg-shlibdeps</prgn> during the package
- build.<footnote>
- An example may clarify. Suppose the source
- package <tt>foo</tt> generates two binary
- packages, <tt>libfoo2</tt> and <tt>foo-runtime</tt>.
- When building the binary packages, the contents of the
- packages are staged in the
- directories <file>debian/libfoo2</file>
- and <file>debian/foo-runtime</file> respectively.
- (<file>debian/tmp</file> could be used instead of one
- of these.) Since <tt>libfoo2</tt> provides
- the <tt>libfoo</tt> shared library, it will contain
- a <tt>symbols</tt> file, which will be installed
- in <file>debian/libfoo2/DEBIAN/symbols</file>,
- eventually to be included as a control file in that
- package. When <prgn>dpkg-shlibdeps</prgn> is run on
- the
- executable <file>debian/foo-runtime/usr/bin/foo-prog</file>,
- it will examine
- the <file>debian/libfoo2/DEBIAN/symbols</file> file to
- determine whether <tt>foo-prog</tt>'s library
- dependencies are satisfied by any of the libraries
- provided by <tt>libfoo2</tt>. Since those binaries
- were linked against the just-built shared library as
- part of the build process, the <file>symbols</file>
- file for the newly-built <tt>libfoo2</tt> must take
- precedence over a <file>symbols</file> file for any
- other <tt>libfoo2</tt> package already installed on
- the system.
- </footnote>
- </p>
- </item>
-
- <item>
- <p>
- <file>/etc/dpkg/symbols/<var>package</var>.symbols.<var>arch</var></file>
- and <file>/etc/dpkg/symbols/<var>package</var>.symbols</file>
- </p>
-
- <p>
- 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.
- </p>
- </item>
-
- <item>
- <p><file>symbols</file> control files for packages
- installed on the system</p>
-
- <p>
- The <file>symbols</file> 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 are normally
- found in <file>/var/lib/dpkg/info/*.symbols</file>, but
- packages should not rely on this and instead should
- use <tt>dpkg-query --control-path <var>package</var>
- symbols</tt> if for some reason these files need to be
- examined.
- </p>
- </item>
- </list>
- </p>
-
- <p>
- Be aware that if a <file>debian/shlibs.local</file> exists in
- the source package, it will override any <file>symbols</file>
- files. This is the only case where a <file>shlibs</file> is
- used despite <file>symbols</file> files being present. See
- <ref id="shlibs-paths"> and <ref id="sharedlibs-shlibdeps">
- for more information.
- </p>
- </sect1>
-
<sect1 id="dpkg-shlibdeps">
- <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
- <tt>symbols</tt> files</heading>
-
- <p>
- If your package contains any compiled binaries or shared
- libraries, put a call to <prgn>dpkg-shlibdeps</prgn> into
+ <heading>Generating dependencies on shared libraries</heading>
+
+ <p>
+ When a package that contains any shared libraries or compiled
+ binaries is built, it must run <prgn>dpkg-shlibdeps</prgn> on
+ each shared library and compiled binary to determine the
+ libraries used and hence the dependencies needed by the
+ package.<footnote>
+ <prgn>dpkg-shlibdeps</prgn> will use a program
+ like <prgn>objdump</prgn> or <prgn>readelf</prgn> to find
+ the libraries and the symbols in those libraries directly
+ needed by the binaries or shared libraries in the package.
+ </footnote>
+ To do this, put a call to <prgn>dpkg-shlibdeps</prgn> into
your <file>debian/rules</file> file in the source package.
List all of the compiled binaries, libraries, or loadable
modules in your package.<footnote>
- The easiest way to do this is to use a package helper
- framework such as <tt>debhelper</tt>. If you are
- using <tt>debhelper</tt>, the <prgn>dh_shlibdeps</prgn>
- program will do this work for you. It will also correctly
- handle multi-binary packages.
+ The easiest way to call <prgn>dpkg-shlibdeps</prgn>
+ correctly is to use a package helper framework such
+ as <package>debhelper</package>. If you are
+ using <package>debhelper</package>,
+ the <prgn>dh_shlibdeps</prgn> program will do this work for
+ you. It will also correctly handle multi-binary packages.
</footnote>
+ <prgn>dpkg-shlibdeps</prgn> will use the <file>symbols</file>
+ or <file>shlibs</file> 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.
+ </p>
+
+ <p>
+ If you are creating a udeb for use in the Debian Installer,
+ you will need to specify that <prgn>dpkg-shlibdeps</prgn>
+ should use the dependency line of type <tt>udeb</tt> by adding
+ the <tt>-tudeb</tt> option<footnote>
+ <prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
+ will automatically add this option if it knows it is
+ processing a udeb.
+ </footnote>. If there is no dependency line of
+ type <tt>udeb</tt> in the <file>shlibs</file>
+ file, <prgn>dpkg-shlibdeps</prgn> will fall back to the
+ regular dependency line.
</p>
<p>
- This command puts the dependency information into
- the <file>debian/substvars</file> file, which is then used
- by <prgn>dpkg-gencontrol</prgn>. You will need to place
- a <tt>${shlibs:Depends}</tt> variable in the <tt>Depends</tt>
- 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 <prgn>dpkg-shlibdeps</prgn> on
- each one which contains compiled libraries or binaries, using
+ <prgn>dpkg-shlibdeps</prgn> puts the dependency information
+ into the <file>debian/substvars</file> file by default, which
+ is then used by <prgn>dpkg-gencontrol</prgn>. You will need
+ to place a <tt>${shlibs:Depends}</tt> variable in
+ the <tt>Depends</tt> 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 <prgn>dpkg-shlibdeps</prgn> on each one which contains
+ compiled libraries or binaries. For example, you could use
the <tt>-T</tt> option to the <tt>dpkg</tt> utilities to
specify a different <file>substvars</file> file for each
binary package.<footnote>
Again, <prgn>dh_shlibdeps</prgn>
- and <prgn>dh_gencontrol</prgn> will handle all of this for
- you if you're using <tt>debhelper</tt>, including generating
- separate <file>substvars</file> files for each binary
- package and calling <prgn>dpkg-gencontrol</prgn> with the
- appropriate flags.
+ and <prgn>dh_gencontrol</prgn> will handle everything except
+ the addition of the variable to the control file for you if
+ you're using <package>debhelper</package>, including
+ generating separate <file>substvars</file> files for each
+ binary package and calling <prgn>dpkg-gencontrol</prgn> with
+ the appropriate flags.
</footnote>
</p>
For more details on <prgn>dpkg-shlibdeps</prgn>,
see <manref name="dpkg-shlibdeps" section="1">.
</p>
- </sect1>
-
- <sect1 id="symbols">
- <heading>The <file>symbols</file> File Format</heading>
-
- <p>
- The following documents the format of the <file>symbols</file>
- control file as included in binary packages. These files are
- built from template <file>symbols</file> files in the source
- package by <prgn>dpkg-gensymbols</prgn>. The template files
- support a richer syntax that
- allows <prgn>dpkg-gensymbols</prgn> to do some of the tedious
- work involved in maintaining <file>symbols</file> files, such
- as handling C++ symbols or optional symbols that may not exist
- on particular architectures. When
- writing <file>symbols</file> files for a shared library
- package, refer to <manref name="dpkg-gensymbols" section="1">
- for the richer syntax.
- </p>
-
- <p>
- A <file>symbols</file> may contain one or more entries, one
- for each shared library contained in the package corresponding
- to that <file>symbols</file>. Each entry has the following
- format:
- </p>
-
- <p>
- <example>
-<var>library-soname</var> <var>main-dependency-template</var>
-[| <var>alternative-dependency-template</var>]
-[...]
-[* <var>field-name</var>: <var>field-value</var>]
-[...]
- <var>symbol</var> <var>minimal-version</var>[ <var>id-of-dependency-template</var> ]
- </example>
- </p>
-
- <p>
- To explain this format, we'll use the the <tt>zlib1g</tt>
- package as an example, which (at the time of writing) installs
- the shared library <file>/usr/lib/libz.so.1.2.3.4</file>.
- Mandatory lines will be described first, followed by optional
- lines.
- </p>
-
- <p>
- <var>library-soname</var> must contain exactly the value of
- the ELF <tt>SONAME</tt> attribute of the shared library. In
- our example, this is <tt>libz.so.1</tt>.<footnote>
- This can be determined by using the command
- <example compact="compact">
-readelf -d /usr/lib/libz.so.1.2.3.4 | grep SONAME
- </example>
- </footnote>
- </p>
-
- <p>
- <var>main-dependency-template</var> has the same syntax as a
- dependency field in a binary package control file, except that
- the string <tt>#MINVER#</tt> is replaced by a version
- restriction like <tt>(>= <var>version</var>)</tt> 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, <var>main-dependency-template</var> will
- be <tt><var>package</var> #MINVER#</tt>,
- where <var>package</var> 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.
- </p>
-
- <p>
- In our example, the first line of
- the <tt>zlib1g</tt> <file>symbols</file> file would be:
- <example compact="compact">
-libz.so.1 zlib1g #MINVER#
- </example>
- </p>
-
- <p>
- Each public symbol exported by the shared library must have a
- corresponding symbol line, indented by one
- space. <var>symbol</var> is the exported symbol (which, for
- C++, means the mangled symbol) followed by <tt>@</tt> and the
- symbol version, or the string <tt>Base</tt> if there is no
- symbol version. <var>minimal-version</var> 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 its behavior in a way that is visible to a
- caller. <var>id-of-dependency-template</var> is an optional
- field that references
- an <var>alternative-dependency-template</var>; see below for a
- full description.
- </p>
-
- <p>
- For example, <tt>libz.so.1</tt> contains the
- symbols <tt>compress</tt>
- and <tt>compressBound</tt>. <tt>compress</tt> has no symbol
- version and last changed its behavior in upstream
- version <tt>1:1.1.4</tt>. <tt>compressBound</tt> has the
- symbol version <tt>ZLIB_1.2.0</tt>, was introduced in upstream
- version <tt>1:1.2.0</tt>, and has not changed its behavior.
- Its <file>symbols</file> file therefore contains the lines:
- <example compact="compact">
- compress@Base 1:1.1.4
- compressBound@ZLIB_1.2.0 1:1.2.0
- </example>
- Packages using only <tt>compress</tt> would then get a
- dependency of <tt>zlib1g (>= 1:1.1.4)</tt>, but packages
- using <tt>compressBound</tt> would get a dependency
- of <tt>zlib1g (>= 1:1.2.0)</tt>.
- </p>
-
- <p>
- One or more <var>alternative-dependency-template</var> 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 <var>id-of-dependency-template</var> field. The first
- alternative dependency template is numbered 1, the second 2,
- and so forth.<footnote>
- 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 <file>symbols</file> file:
- <example>
-libGL.so.1 libgl1
-| libgl1-mesa-glx #MINVER#
- publicGlSymbol@Base 6.3-1
- [...]
- implementationSpecificSymbol@Base 6.5.2-7 1
- [...]
- </example>
- Binaries or shared libraries using
- only <tt>publicGlSymbol</tt> would depend only
- on <tt>libgl1</tt> (which may be provided by multiple
- packages), but ones
- using <tt>implementationSpecificSymbol</tt> would get a
- dependency on <tt>libgl1-mesa-glx (>= 6.5.2-7)</tt>
- </footnote>
- </p>
<p>
- Finally, the entry for the library may contain one or more
- metadata fields. Currently, the only
- supported <var>field-name</var>
- is <tt>Build-Depends-Package</tt>, whose value lists
- the <qref id="sharedlibs-dev">library development
- package</qref> on which packages using this shared library
- declare a build dependency. If this field is
- present, <prgn>dpkg-shlibdeps</prgn> 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.<footnote>
- This field should normally not be necessary, since if the
- behavior of any symbol has changed, the corresponding
- symbol <var>minimal-version</var> should have been
- increased. But including it makes the <tt>symbols</tt>
- 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.
+ 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, the library is listed in the
+ ELF <tt>NEEDED</tt> attribute, caused by adding <tt>-lbar</tt>
+ to the link line when the binary is created). 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, but not the libraries it only uses
+ indirectly. The dependencies for the libraries used
+ directly will automatically pull in the indirectly-used
+ libraries. <prgn>dpkg-shlibdeps</prgn> 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.
+ <footnote>
+ A good example of where this helps is the following. We
+ could update <tt>libimlib</tt> 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 <package>libdgf4</package> instead of
+ the older <package>libdgf3</package>. If we
+ used <prgn>ldd</prgn> to add dependencies for every library
+ directly or indirectly linked with a binary, every package
+ that uses <tt>libimlib</tt> would need to be recompiled so
+ it would also depend on <package>libdgf4</package> in order
+ to retire the older <package>libdgf3</package> package.
+ Since dependencies are only added based on
+ ELF <tt>NEEDED</tt> attribute, packages
+ using <tt>libimlib</tt> can rely on <tt>libimlib</tt> itself
+ having the dependency on an appropriate version
+ of <tt>libdgf</tt> and do not need rebuilding.
</footnote>
- For our example, the <tt>zlib1g</tt> <file>symbols</file> file
- would contain:
- <example compact="compact">
-* Build-Depends-Package: zlib1g-dev
- </example>
- </p>
-
- <p>
- Also see <manref name="deb-symbols" section="5">.
</p>
</sect1>
- <sect1 id="providing-symbols">
- <heading>Providing a <file>symbols</file> file</heading>
-
- <p>
- If your package provides a shared library, you should arrange
- to include a <file>symbols</file> control file following the
- format described above in that package. You must include
- either a <file>symbols</file> control file or
- a <file>shlibs</file> control file.
- </p>
-
- <p>
- Normally, this is done by creating a <file>symbols</file> in
- the source package
- named <file>debian/<var>package</var>.symbols</file>
- or <file>debian/symbols</file>, possibly
- with <file>.<var>arch</var></file> appended if the symbols
- information varies by architecture. This file may use the
- extended syntax documented
- in <manref name="dpkg-gensymbols" section="1">. Then,
- call <prgn>dpkg-gensymbols</prgn> as part of the package build
- process. It will create <file>symbols</file> files in the
- package staging area based on the binaries and libraries in
- the package staging area and the <file>symbols</file> files in
- the source package.<footnote>
- If you are
- using <tt>debhelper</tt>, <prgn>dh_makeshlibs</prgn> will
- take care of calling either <prgn>dpkg-gensymbols</prgn>
- or generating a <file>shlibs</file> file as appropriate.
+ <sect1 id="sharedlibs-updates">
+ <heading>Shared library ABI changes</heading>
+
+ <p>
+ Maintaining a shared library package using
+ either <file>symbols</file> or <file>shlibs</file> files
+ requires being aware of the exposed ABI of the shared library
+ and any changes to it. Both <file>symbols</file>
+ and <file>shlibs</file> files record every change to the ABI
+ of the shared library; <file>symbols</file> files do so per
+ public symbol, whereas <file>shlibs</file> files record only
+ the last change for the entire library.
+ </p>
+
+ <p>
+ 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.<footnote>
+ 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 <tt>Breaks</tt> 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.
</footnote>
- </p>
-
- <p>
- Packages that provide <file>symbols</file> files must keep
- them up-to-date to ensure correct dependencies in packages
- that use the shared libraries. This means updating
- the <file>symbols</file> file whenever a new public symbol is
- added, changing the <var>minimal-version</var> field whenever
- a symbol changes behavior or signature, and changing
- the <var>library-soname</var>
- and <var>main-dependency-template</var>, and probably all of
- the <var>minimal-version</var> fields, when the library
- changes <tt>SONAME</tt>. Removing a public symbol from
- the <file>symbols</file> file because it's no longer provided
- by the library normally requires changing the <tt>SONAME</tt>
- of the library. See <ref id="sharedlibs-runtime">.
- </p>
-
- <p>
- Special care should be taken in updating
- the <var>minimal-version</var> field 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 <var>minimal-version</var> in this case may
+ 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.
+ </p>
+
+ <p>
+ ABI changes that are not backward-compatible normally require
+ changing the <tt>SONAME</tt> 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 id="sharedlibs-runtime">. The remainder of this
+ section will deal with backward-compatible changes.
+ </p>
+
+ <p>
+ Backward-compatible changes require either updating or
+ recording the <var>minimal-version</var> for that symbol
+ in <file>symbols</file> files or updating the version in
+ the <var>dependencies</var> in <file>shlibs</file> files. For
+ more information on how to do this in the two formats, see
+ <ref id="symbols"> and <ref id="shlibs">. Below are general
+ rules that apply to both files.
+ </p>
+
+ <p>
+ The easy case is when a public symbol is added. Simply add
+ the version at which the symbol was introduced
+ (for <file>symbols</file> files) or update the dependency
+ version (for <file>shlibs</file>) 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 may
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 may have occurred but isn't sure, it's
- safer to update the <var>minimal-version</var> of all possibly
- affected symbols to the current upstream version rather than
- leave them unmodified. This may result in unnecessarily
- strict dependencies, but it ensures that packages whose
- dependencies are satisfied will work properly.
+ 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.
</p>
<p>
- A common example of when a change
- to <var>minimal-version</var> is required is a function that
- takes an enum or struct argument that controls what the
- function does. For example:
+ 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:
<example>
-enum library_op { OP_FOO, OP_BAR };
-int library_do_operation(enum library_op);
+ enum library_op { OP_FOO, OP_BAR };
+ int library_do_operation(enum library_op);
</example>
If a new operation, <tt>OP_BAZ</tt>, is added,
the <var>minimal-version</var>
- of <tt>library_do_operation</tt> must be increased to the
+ of <tt>library_do_operation</tt> (for <file>symbols</file>
+ files) or the version in the dependency for the shared library
+ (for <file>shlibs</file> files) must be increased to the
version at which <tt>OP_BAZ</tt> was introduced. Otherwise, a
binary built against the new version of the library (having
detected at compile-time that the library
</p>
<p>
- The <var>minimal-version</var> field 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 <tt>~</tt> to the end of
- the <var>minimal-version</var> 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.
+ Dependency versions in either <file>symbols</file>
+ or <file>shlibs</file> 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 <tt>~</tt>
+ 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.
</p>
</sect1>
- </sect>
- <sect id="sharedlibs-shlibdeps">
- <heading>Dependencies between the library and other packages -
- the <tt>shlibs</tt> system</heading>
+ <sect1 id="sharedlibs-symbols">
+ <heading>The <tt>symbols</tt> system</heading>
- <p>
- The <tt>shlibs</tt> system is an alternative to
- the <tt>symbols</tt> system for declaring dependencies for
- shared libraries. It predated the <tt>symbols</tt> system and
- is therefore frequently seen in older packages. It is also
- required for udebs, which do not support <tt>symbols</tt>.
- </p>
+ In the following sections, we will first describe where the
+ various <file>symbols</file> files are to be found, then
+ the <file>symbols</file> file format, and finally how to
+ create <file>symbols</file> files if your package contains a
+ shared library.
+ </p>
- <p>
- <file>shlibs</file> files do not provide as detailed of
- information as <file>symbols</file> files. They only provide
- information about the library as a whole, not individual
- symbols, and therefore have to force tighter dependencies since
- they have no way of relaxing dependencies for binaries and
- libraries that only use symbols whose behavior has not changed.
- Because of this, and because of some problems with
- how <file>shlibs</file> files represent the
- library <tt>SONAME</tt>, <file>symbols</file> files are
- recommended instead for any shared library package that isn't a
- udeb.
- </p>
+ <sect2 id="symbols-paths">
+ <heading>The <file>symbols</file> files present on the
+ system</heading>
- <p>
- In the following sections, we will first describe where the
- various <file>shlibs</file> files are to be found, then how to
- use <prgn>dpkg-shlibdeps</prgn>, and finally
- the <file>shlibs</file> file format and how to create them if
- your package contains a shared library. Much of the information
- about <file>shlibs</file> files is the same as
- for <file>symbols</file> files, so only the differences will be
- mentioned.
- </p>
+ <p>
+ <file>symbols</file> 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 <prgn>dpkg-shlibdeps</prgn> The first one that contains
+ the required information is used.
+ <list>
+ <item>
+ <p><file>debian/*/DEBIAN/symbols</file></p>
+
+ <p>
+ During the package build, if the package itself
+ contains shared libraries with <file>symbols</file>
+ files, they will be generated in these staging
+ directories by <prgn>dpkg-gensymbols</prgn>
+ (see <ref id="providing-symbols">). <file>symbols</file>
+ files found in the build tree take precedence
+ over <file>symbols</file> files from other binary
+ packages.
+ </p>
+
+ <p>
+ These files must exist
+ before <prgn>dpkg-shlibdeps</prgn> 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 <prgn>dpkg-gensymbols</prgn> must be run
+ before <prgn>dpkg-shlibdeps</prgn> during the package
+ build.<footnote>
+ An example may clarify. Suppose the source
+ package <tt>foo</tt> generates two binary
+ packages, <tt>libfoo2</tt> and <tt>foo-runtime</tt>.
+ When building the binary packages, the contents of
+ the packages are staged in the
+ directories <file>debian/libfoo2</file>
+ and <file>debian/foo-runtime</file> respectively.
+ (<file>debian/tmp</file> could be used instead of
+ one of these.) Since <tt>libfoo2</tt> provides
+ the <tt>libfoo</tt> shared library, it will contain
+ a <tt>symbols</tt> file, which will be installed
+ in <file>debian/libfoo2/DEBIAN/symbols</file>,
+ eventually to be included as a control file in that
+ package. When <prgn>dpkg-shlibdeps</prgn> is run on
+ the
+ executable <file>debian/foo-runtime/usr/bin/foo-prog</file>,
+ it will examine
+ the <file>debian/libfoo2/DEBIAN/symbols</file> file
+ to determine whether <tt>foo-prog</tt>'s library
+ dependencies are satisfied by any of the libraries
+ provided by <tt>libfoo2</tt>. Since those binaries
+ were linked against the just-built shared library as
+ part of the build process, the <file>symbols</file>
+ file for the newly-built <tt>libfoo2</tt> must take
+ precedence over a <file>symbols</file> file for any
+ other <tt>libfoo2</tt> package already installed on
+ the system.
+ </footnote>
+ </p>
+ </item>
- <sect1 id="shlibs-paths">
- <heading>The <file>shlibs</file> files present on the
- system</heading>
+ <item>
+ <p>
+ <file>/etc/dpkg/symbols/<var>package</var>.symbols.<var>arch</var></file>
+ and <file>/etc/dpkg/symbols/<var>package</var>.symbols</file>
+ </p>
+
+ <p>
+ 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.
+ </p>
+ </item>
- <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.)
- <list>
- <item>
- <p><file>debian/shlibs.local</file></p>
+ <item>
+ <p><file>symbols</file> control files for packages
+ installed on the system</p>
+
+ <p>
+ The <file>symbols</file> 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 are
+ normally found
+ in <file>/var/lib/dpkg/info/*.symbols</file>, but
+ packages should not rely on this and instead should
+ use <tt>dpkg-query --control-path <var>package</var>
+ symbols</tt> if for some reason these files need to be
+ examined.
+ </p>
+ </item>
+ </list>
+ </p>
- <p>
- 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 <file>shlibs</file> file for a library cannot
- be used. This file overrides information obtained from
- any other source.
- </p>
- </item>
+ <p>
+ Be aware that if a <file>debian/shlibs.local</file> exists
+ in the source package, it will override
+ any <file>symbols</file> files. This is the only case where
+ a <file>shlibs</file> is used despite <file>symbols</file>
+ files being present. See <ref id="shlibs-paths">
+ and <ref id="sharedlibs-shlibdeps"> for more information.
+ </p>
+ </sect2>
- <item>
- <p><file>/etc/dpkg/shlibs.override</file></p>
+ <sect2 id="symbols">
+ <heading>The <file>symbols</file> File Format</heading>
- <p>
- This lists global overrides. This list is normally
- empty. It is maintained by the local system
- administrator.
- </p>
- </item>
+ <p>
+ The following documents the format of
+ the <file>symbols</file> control file as included in binary
+ packages. These files are built from
+ template <file>symbols</file> files in the source package
+ by <prgn>dpkg-gensymbols</prgn>. The template files support
+ a richer syntax that allows <prgn>dpkg-gensymbols</prgn> to
+ do some of the tedious work involved in
+ maintaining <file>symbols</file> files, such as handling C++
+ symbols or optional symbols that may not exist on particular
+ architectures. When writing <file>symbols</file> files for
+ a shared library package, refer
+ to <manref name="dpkg-gensymbols" section="1"> for the
+ richer syntax.
+ </p>
- <item>
- <p><file>DEBIAN/shlibs</file> files in the "build
- directory"</p>
+ <p>
+ A <file>symbols</file> may contain one or more entries, one
+ for each shared library contained in the package
+ corresponding to that <file>symbols</file>. Each entry has
+ the following format:
+ </p>
- <p>
- 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.
- </p>
- </item>
+ <p>
+ <example>
+ <var>library-soname</var> <var>main-dependency-template</var>
+ [| <var>alternative-dependency-template</var>]
+ [...]
+ [* <var>field-name</var>: <var>field-value</var>]
+ [...]
+ <var>symbol</var> <var>minimal-version</var>[ <var>id-of-dependency-template</var> ]
+ </example>
+ </p>
- <item>
- <p><file>shlibs</file> control files for packages
- installed on the system</p>
+ <p>
+ To explain this format, we'll use the the <tt>zlib1g</tt>
+ package as an example, which (at the time of writing)
+ installs the shared
+ library <file>/usr/lib/libz.so.1.2.3.4</file>. Mandatory
+ lines will be described first, followed by optional lines.
+ </p>
- <p>
- The <file>shlibs</file> control files for all the
- packages currently installed on the system. These are
- normally found
- in <file>/var/lib/dpkg/info/*.symbols</file>, but
- packages should not rely on this and instead should
- use <tt>dpkg-query --control-path <var>package</var>
- shlibs</tt> if for some reason these files need to be
- examined.
- </p>
- </item>
+ <p>
+ <var>library-soname</var> must contain exactly the value of
+ the ELF <tt>SONAME</tt> attribute of the shared library. In
+ our example, this is <tt>libz.so.1</tt>.<footnote>
+ This can be determined by using the command
+ <example compact="compact">
+ readelf -d /usr/lib/libz.so.1.2.3.4 | grep SONAME
+ </example>
+ </footnote>
+ </p>
- <item>
- <p><file>/etc/dpkg/shlibs.default</file></p>
+ <p>
+ <var>main-dependency-template</var> has the same syntax as a
+ dependency field in a binary package control file, except
+ that the string <tt>#MINVER#</tt> is replaced by a version
+ restriction like <tt>(>= <var>version</var>)</tt> 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, <var>main-dependency-template</var> will
+ be <tt><var>package</var> #MINVER#</tt>,
+ where <var>package</var> 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.
+ </p>
- <p>
- This file lists any shared libraries whose packages have
- failed to provide correct <file>shlibs</file> files. It
- was used when the <file>shlibs</file> setup was first
- introduced, but it is now normally empty. It is
- maintained by the <tt>dpkg</tt> maintainer.
- </p>
- </item>
- </list>
- </p>
+ <p>
+ In our example, the first line of
+ the <tt>zlib1g</tt> <file>symbols</file> file would be:
+ <example compact="compact">
+ libz.so.1 zlib1g #MINVER#
+ </example>
+ </p>
- <p>
- If a <file>symbols</file> file for a shared library package
- is available, <prgn>dpkg-shlibdeps</prgn> will always use it
- in preference to a <file>shlibs</file>, with the exception
- of <file>debian/shlibs.local</file>. The latter overrides any
- other <file>shlibs</file> or <file>symbols</file> files.
- </p>
- </sect1>
+ <p>
+ Each public symbol exported by the shared library must have
+ a corresponding symbol line, indented by one
+ space. <var>symbol</var> is the exported symbol (which, for
+ C++, means the mangled symbol) followed by <tt>@</tt> and
+ the symbol version, or the string <tt>Base</tt> if there is
+ no symbol version. <var>minimal-version</var> 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.
+ <var>id-of-dependency-template</var> is an optional
+ field that references
+ an <var>alternative-dependency-template</var>; see below for
+ a full description.
+ </p>
- <sect1>
- <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
- <file>shlibs</file> files</heading>
+ <p>
+ For example, <tt>libz.so.1</tt> contains the
+ symbols <tt>compress</tt>
+ and <tt>compressBound</tt>. <tt>compress</tt> has no symbol
+ version and last changed its behavior in upstream
+ version <tt>1:1.1.4</tt>. <tt>compressBound</tt> has the
+ symbol version <tt>ZLIB_1.2.0</tt>, was introduced in
+ upstream version <tt>1:1.2.0</tt>, and has not changed its
+ behavior. Its <file>symbols</file> file therefore contains
+ the lines:
+ <example compact="compact">
+ compress@Base 1:1.1.4
+ compressBound@ZLIB_1.2.0 1:1.2.0
+ </example>
+ Packages using only <tt>compress</tt> would then get a
+ dependency on <tt>zlib1g (>= 1:1.1.4)</tt>, but packages
+ using <tt>compressBound</tt> would get a dependency
+ on <tt>zlib1g (>= 1:1.2.0)</tt>.
+ </p>
- <p>
- Use of <prgn>dpkg-shlibdeps</prgn> with <file>shlibs</file>
- files is generally the same as with <file>symbols</file>
- files. See <ref id="dpkg-shlibdeps">.
- </p>
+ <p>
+ One or more <var>alternative-dependency-template</var> 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 <var>id-of-dependency-template</var>
+ field. The first alternative dependency template is
+ numbered 1, the second 2, and so forth.<footnote>
+ 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 <file>symbols</file> file:
+ <example>
+ libGL.so.1 libgl1
+ | libgl1-mesa-glx #MINVER#
+ publicGlSymbol@Base 6.3-1
+ [...]
+ implementationSpecificSymbol@Base 6.5.2-7 1
+ [...]
+ </example>
+ Binaries or shared libraries using
+ only <tt>publicGlSymbol</tt> would depend only
+ on <tt>libgl1</tt> (which may be provided by multiple
+ packages), but ones
+ using <tt>implementationSpecificSymbol</tt> would get a
+ dependency on <tt>libgl1-mesa-glx (>= 6.5.2-7)</tt>
+ </footnote>
+ </p>
- <p>
- If you are creating a udeb for use in the Debian Installer,
- you will need to specify that <prgn>dpkg-shlibdeps</prgn>
- should use the dependency line of type <tt>udeb</tt> by
- adding the <tt>-tudeb</tt> option<footnote>
- <prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
- will automatically add this option if it knows it is
- processing a udeb.
- </footnote>. If there is no dependency line of
- type <tt>udeb</tt> in the <file>shlibs</file>
- file, <prgn>dpkg-shlibdeps</prgn> will fall back to the
- regular dependency line.
- </p>
+ <p>
+ Finally, the entry for the library may contain one or more
+ metadata fields. Currently, the only
+ supported <var>field-name</var>
+ is <tt>Build-Depends-Package</tt>, whose value lists
+ the <qref id="sharedlibs-dev">library development
+ package</qref> on which packages using this shared library
+ declare a build dependency. If this field is
+ present, <prgn>dpkg-shlibdeps</prgn> 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.<footnote>
+ This field should normally not be necessary, since if the
+ behavior of any symbol has changed, the corresponding
+ symbol <var>minimal-version</var> should have been
+ increased. But including it makes the <tt>symbols</tt>
+ 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.
+ </footnote>
+ For our example, the <tt>zlib1g</tt> <file>symbols</file>
+ file would contain:
+ <example compact="compact">
+ * Build-Depends-Package: zlib1g-dev
+ </example>
+ </p>
+
+ <p>
+ Also see <manref name="deb-symbols" section="5">.
+ </p>
+ </sect2>
+
+ <sect2 id="providing-symbols">
+ <heading>Providing a <file>symbols</file> file</heading>
+
+ <p>
+ If your package provides a shared library, you should
+ arrange to include a <file>symbols</file> control file
+ following the format described above in that package. You
+ must include either a <file>symbols</file> control file or
+ a <file>shlibs</file> control file.
+ </p>
+
+ <p>
+ Normally, this is done by creating a <file>symbols</file> in
+ the source package
+ named <file>debian/<var>package</var>.symbols</file>
+ or <file>debian/symbols</file>, possibly
+ with <file>.<var>arch</var></file> appended if the symbols
+ information varies by architecture. This file may use the
+ extended syntax documented in <manref name="dpkg-gensymbols"
+ section="1">. Then, call <prgn>dpkg-gensymbols</prgn> as
+ part of the package build process. It will
+ create <file>symbols</file> files in the package staging
+ area based on the binaries and libraries in the package
+ staging area and the <file>symbols</file> files in the
+ source package.<footnote>
+ If you are
+ using <tt>debhelper</tt>, <prgn>dh_makeshlibs</prgn> will
+ take care of calling either <prgn>dpkg-gensymbols</prgn>
+ or generating a <file>shlibs</file> file as appropriate.
+ </footnote>
+ </p>
+
+ <p>
+ Packages that provide <file>symbols</file> files must keep
+ them up-to-date to ensure correct dependencies in packages
+ that use the shared libraries. This means updating
+ the <file>symbols</file> file whenever a new public symbol
+ is added, changing the <var>minimal-version</var> field
+ whenever a symbol changes behavior or signature in a
+ backward-compatible way (see <ref id="sharedlibs-updates">),
+ and changing the <var>library-soname</var>
+ and <var>main-dependency-template</var>, and probably all of
+ the <var>minimal-version</var> fields, when the library
+ changes <tt>SONAME</tt>. Removing a public symbol from
+ the <file>symbols</file> file because it's no longer
+ provided by the library normally requires changing
+ the <tt>SONAME</tt> of the library.
+ See <ref id="sharedlibs-runtime"> for more information
+ on <tt>SONAME</tt>s.
+ </p>
+ </sect2>
</sect1>
- <sect1 id="shlibs">
- <heading>The <file>shlibs</file> File Format</heading>
+ <sect1 id="sharedlibs-shlibdeps">
+ <heading>The <tt>shlibs</tt> system</heading>
<p>
- Each <file>shlibs</file> file has the same format. Lines
- beginning with <tt>#</tt> are considered to be comments and
- are ignored. Each line is of the form:
- <example compact="compact">
-[<var>type</var>: ]<var>library-name</var> <var>soname-version</var> <var>dependencies ...</var>
- </example>
+ The <tt>shlibs</tt> system is a simpler alternative to
+ the <tt>symbols</tt> 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 <tt>symbols</tt> system and is
+ therefore frequently seen in older packages. It is also
+ required for udebs, which do not support <tt>symbols</tt>.
</p>
<p>
- We will explain this by reference to the example of the
- <tt>zlib1g</tt> package, which (at the time of writing)
- installs the shared
- library <file>/usr/lib/libz.so.1.2.3.4</file>.
+ In the following sections, we will first describe where the
+ various <file>shlibs</file> files are to be found, then how to
+ use <prgn>dpkg-shlibdeps</prgn>, and finally
+ the <file>shlibs</file> file format and how to create them.
</p>
- <p>
- <var>type</var> is an optional element that indicates the type
- of package for which the line is valid. The only type
- currently in use is <tt>udeb</tt>. The colon and space after
- the type are required.
- </p>
+ <sect2 id="shlibs-paths">
+ <heading>The <file>shlibs</file> files present on the
+ system</heading>
- <p>
- <var>library-name</var> is the name of the shared library, in
- this case <tt>libz</tt>. (This must match the name part of
- the soname, see below.)
- </p>
+ <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.)
+ <list>
+ <item>
+ <p><file>debian/shlibs.local</file></p>
+
+ <p>
+ 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 <file>shlibs</file> file for a library
+ cannot be used. This file overrides information
+ obtained from any other source.
+ </p>
+ </item>
- <p>
- <var>soname-version</var> is the version part of the
- ELF <tt>SONAME</tt> attribute of the library.
- The <tt>SONAME</tt> is the thing that must exactly match for
- the library to be recognized by the dynamic linker, and is
- usually of the
- form <tt><var>name</var>.so.<var>major-version</var></tt>, in
- our example, <tt>libz.so.1</tt>.
- The version part is the part which comes after
- <tt>.so.</tt>, so in our case, it is <tt>1</tt>. The soname
- may instead be of the
- form <tt><var>name</var>-<var>major-version</var>.so</tt>,
- such as <tt>libdb-5.1.so</tt>, in which case the name would
- be <tt>libdb</tt> and the version would be <tt>5.1</tt>.
- </p>
+ <item>
+ <p><file>/etc/dpkg/shlibs.override</file></p>
- <p>
- <var>dependencies</var> 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 id="depsyntax"> for details.
- </p>
+ <p>
+ This lists global overrides. This list is normally
+ empty. It is maintained by the local system
+ administrator.
+ </p>
+ </item>
- <p>
- In our example, if the last change to the <tt>zlib1g</tt>
- package that could change behavior for a client of that
- library was in version <tt>1:1.2.3.3.dfsg-1</tt>, then
- the <tt>shlibs</tt> entry for this library could say:
- <example compact="compact">
-libz 1 zlib1g (>= 1:1.2.3.3.dfsg-1)
- </example>
- 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.
- </p>
+ <item>
+ <p><file>DEBIAN/shlibs</file> files in the "build
+ directory"</p>
+
+ <p>
+ 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.
+ </p>
+ </item>
- <p>
- As zlib1g also provides a udeb containing the shared library,
- there would also be a second line:
- <example compact="compact">
-udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg-1)
- </example>
- </p>
- </sect1>
+ <item>
+ <p><file>shlibs</file> control files for packages
+ installed on the system</p>
+
+ <p>
+ The <file>shlibs</file> control files for all the
+ packages currently installed on the system. These are
+ normally found
+ in <file>/var/lib/dpkg/info/*.symbols</file>, but
+ packages should not rely on this and instead should
+ use <tt>dpkg-query --control-path <var>package</var>
+ shlibs</tt> if for some reason these files need to be
+ examined.
+ </p>
+ </item>
- <sect1>
- <heading>Providing a <file>shlibs</file> file</heading>
-
- <p>
- To provide a <file>shlibs</file> file for a shared library
- binary package, create a <file>shlibs</file> file following
- the format described above and place it in
- the <file>DEBIAN</file> directory for that package during the
- build. It will then be included as a control file for that
- package<footnote>
- This is what <prgn>dh_makeshlibs</prgn> in
- the <package>debhelper</package> suite does. If your package
- also has a udeb that provides a shared
- library, <prgn>dh_makeshlibs</prgn> can automatically
- generate the <tt>udeb:</tt> lines if you specify the name of
- the udeb with the <tt>--add-udeb</tt> option.
- </footnote>.
- </p>
+ <item>
+ <p><file>/etc/dpkg/shlibs.default</file></p>
+
+ <p>
+ This file lists any shared libraries whose packages
+ have failed to provide correct <file>shlibs</file>
+ files. It was used when the <file>shlibs</file> setup
+ was first introduced, but it is now normally empty.
+ It is maintained by the <tt>dpkg</tt> maintainer.
+ </p>
+ </item>
+ </list>
+ </p>
- <p>
- Since <prgn>dpkg-shlibdeps</prgn> reads
- the <file>DEBIAN/shlibs</file> files in all of the binary
- packages being built from this source package, all of
- the <file>DEBIAN/shlibs</file> files should be installed
- before <prgn>dpkg-shlibdeps</prgn> is called on any of the
- binary packages.
- </p>
+ <p>
+ If a <file>symbols</file> file for a shared library package
+ is available, <prgn>dpkg-shlibdeps</prgn> will always use it
+ in preference to a <file>shlibs</file>, with the exception
+ of <file>debian/shlibs.local</file>. The latter overrides
+ any other <file>shlibs</file> or <file>symbols</file> files.
+ </p>
+ </sect2>
+
+ <sect2 id="shlibs">
+ <heading>The <file>shlibs</file> File Format</heading>
+
+ <p>
+ Each <file>shlibs</file> file has the same format. Lines
+ beginning with <tt>#</tt> are considered to be comments and
+ are ignored. Each line is of the form:
+ <example compact="compact">
+ [<var>type</var>: ]<var>library-name</var> <var>soname-version</var> <var>dependencies ...</var>
+ </example>
+ </p>
+
+ <p>
+ We will explain this by reference to the example of the
+ <tt>zlib1g</tt> package, which (at the time of writing)
+ installs the shared
+ library <file>/usr/lib/libz.so.1.2.3.4</file>.
+ </p>
+
+ <p>
+ <var>type</var> is an optional element that indicates the
+ type of package for which the line is valid. The only type
+ currently in use is <tt>udeb</tt>. The colon and space
+ after the type are required.
+ </p>
+
+ <p>
+ <var>library-name</var> is the name of the shared library,
+ in this case <tt>libz</tt>. (This must match the name part
+ of the soname, see below.)
+ </p>
+
+ <p>
+ <var>soname-version</var> is the version part of the
+ ELF <tt>SONAME</tt> attribute of the library, determined the
+ same way that the <var>soversion</var> component of the
+ recommended shared library package name is determined.
+ See <ref id="sharedlibs-runtime"> for the details.
+ </p>
+
+ <p>
+ <var>dependencies</var> 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 id="depsyntax"> for details on the
+ syntax, and <ref id="sharedlibs-updates"> for details on how
+ to maintain the dependency version constraint.
+ </p>
+
+ <p>
+ In our example, if the last change to the <tt>zlib1g</tt>
+ package that could change behavior for a client of that
+ library was in version <tt>1:1.2.3.3.dfsg-1</tt>, then
+ the <tt>shlibs</tt> entry for this library could say:
+ <example compact="compact">
+ libz 1 zlib1g (>= 1:1.2.3.3.dfsg)
+ </example>
+ 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.
+ </p>
+
+ <p>
+ As zlib1g also provides a udeb containing the shared
+ library, there would also be a second line:
+ <example compact="compact">
+ udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg)
+ </example>
+ </p>
+ </sect2>
+
+ <sect2>
+ <heading>Providing a <file>shlibs</file> file</heading>
+
+ <p>
+ To provide a <file>shlibs</file> file for a shared library
+ binary package, create a <file>shlibs</file> file following
+ the format described above and place it in
+ the <file>DEBIAN</file> directory for that package during
+ the build. It will then be included as a control file for
+ that package<footnote>
+ This is what <prgn>dh_makeshlibs</prgn> in
+ the <package>debhelper</package> suite does. If your
+ package also has a udeb that provides a shared
+ library, <prgn>dh_makeshlibs</prgn> can automatically
+ generate the <tt>udeb:</tt> lines if you specify the name
+ of the udeb with the <tt>--add-udeb</tt> option.
+ </footnote>.
+ </p>
+
+ <p>
+ Since <prgn>dpkg-shlibdeps</prgn> reads
+ the <file>DEBIAN/shlibs</file> files in all of the binary
+ packages being built from this source package, all of
+ the <file>DEBIAN/shlibs</file> files should be installed
+ before <prgn>dpkg-shlibdeps</prgn> is called on any of the
+ binary packages.
+ </p>
+ </sect2>
</sect1>
</sect>
</chapt>
<heading>File System Structure</heading>
<p>
- The location of all installed files and directories must
- comply with the Filesystem Hierarchy Standard (FHS),
- version 2.3, with the exceptions noted below, and except
- where doing so would violate other terms of Debian
- Policy. The following exceptions to the FHS apply:
+ The location of all files and directories must comply with the
+ Filesystem Hierarchy Standard (FHS), version 2.3, with the
+ exceptions noted below, and except where doing so would
+ violate other terms of Debian Policy. The following
+ exceptions to the FHS apply:
<enumlist>
<item>
in <file>/run</file> should be stored on a temporary
file system.
</p>
+ <p>
+ Packages must not assume the <file>/run</file>
+ directory exists or is usable without a dependency
+ on <tt>initscripts (>= 2.88dsf-13.3)</tt> until the
+ stable release of Debian supports <file>/run</file>.
+ </p>
</item>
<item>
<p>
<p>
Packages must not include files or directories
under <file>/run</file>, or under the
- older <file>/var/run</file> and <file>/var/lock<file> paths.
+ older <file>/var/run</file> and <file>/var/lock</file> paths.
The latter paths will normally be symlinks or other
redirections to <file>/run</file> for backwards compatibility.
</p>
</p>
<p>
- Packages which provide the ability to view/show/play,
- compose, edit or print MIME types should register themselves
- as such following the current MIME support policy.
+ Packages which provide programs to view/show/play, compose, edit or
+ print MIME types should register them as such by placing a file in
+ <manref name="mailcap" section="5"> format (RFC 1524) in the directory
+ <file>/usr/lib/mime/packages/</file>. The file name should be the
+ binary package's name.
</p>
<p>
The <package>mime-support</package> package provides the
- <prgn>update-mime</prgn> program which allows packages to
- register programs that can show, compose, edit or print
- MIME types.
- </p>
-
- <p>
- Packages containing such programs must register them
- with <prgn>update-mime</prgn> as documented in <manref
- name="update-mime" section="8">. They should <em>not</em> depend
- on, recommend, or suggest <prgn>mime-support</prgn>. Instead,
- they should just put something like the following in the
- <tt>postinst</tt> and <tt>postrm</tt> scripts:
-
- <example>
- if [ -x /usr/sbin/update-mime ]; then
- update-mime
- fi
- </example>
+ <prgn>update-mime</prgn> program, which integrates these
+ registrations in the <file>/etc/mailcap</file> file, using dpkg
+ triggers<footnote>
+ Creating, modifying or removing a file in
+ <file>/usr/lib/mime/packages/</file> using maintainer scripts will
+ not activate the trigger. In that case, it can be done by calling
+ <tt>dpkg-trigger --no-await /usr/lib/mime/packages</tt> from
+ the maintainer script after creating, modifying, or removing
+ the file.
+ </footnote>.
+ Packages using this facility <em>should not</em> depend on,
+ recommend, or suggest <prgn>mime-support</prgn>.
</p>
-
</sect>
<sect>
</p>
</sect>
+ <sect id="alternateinit">
+ <heading>Alternate init systems</heading>
+ <p>
+ A number of other init systems are available now in Debian that
+ can be used in place of <package>sysvinit</package>. Alternative
+ init implementations must support running SysV init scripts as
+ described at <ref id="sysvinit"> for compatibility.
+ </p>
+ <p>
+ Packages may integrate with these replacement init systems by
+ providing implementation-specific configuration information about
+ how and when to start a service or in what order to run certain
+ tasks at boot time. However, any package integrating with other
+ init systems must also be backwards-compatible with
+ <package>sysvinit</package> by providing a SysV-style init script
+ with the same name as and equivalent functionality to any
+ init-specific job, as this is the only start-up configuration
+ method guaranteed to be supported by all init implementations. An
+ exception to this rule is scripts or jobs provided by the init
+ implementation itself; such jobs may be required for an
+ implementation-specific equivalent of the <file>/etc/rcS.d/</file>
+ scripts and may not have a one-to-one correspondence with the init
+ scripts.
+ </p>
+ <sect1 id="upstart">
+ <heading>Event-based boot with upstart</heading>
+
+ <p>
+ Packages may integrate with the <prgn>upstart</prgn> event-based
+ boot system by installing job files in the
+ <file>/etc/init</file> directory. SysV init scripts for which
+ an equivalent upstart job is available must query the output of
+ the command <prgn>initctl version</prgn> for the string
+ <tt>upstart</tt> and avoid running in favor of the native
+ upstart job, using a test such as this:
+ <example compact="compact">
+if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart
+then
+ exit 1
+fi
+ </example>
+ </p>
+ <p>
+ Because packages shipping upstart jobs may be installed on
+ systems that are not using upstart, maintainer scripts must
+ still use the common <prgn>update-rc.d</prgn> and
+ <prgn>invoke-rc.d</prgn> interfaces for configuring runlevels
+ and for starting and stopping services. These maintainer
+ scripts must not call the upstart <prgn>start</prgn>,
+ <prgn>restart</prgn>, <prgn>reload</prgn>, or <prgn>stop</prgn>
+ interfaces directly. Instead, implementations of
+ <prgn>invoke-rc.d</prgn> must detect when upstart is running and
+ when an upstart job with the same name as an init script is
+ present, and perform the requested action using the upstart job
+ instead of the init script.
+ </p>
+ <p>
+ Dependency-based boot managers for SysV init scripts, such as
+ <prgn>startpar</prgn>, may avoid running a given init script
+ entirely when an equivalent upstart job is present, to avoid
+ unnecessary forking of no-op init scripts. In this case, the
+ boot manager should integrate with upstart to detect when the
+ upstart job in question is started or stopped to know when the
+ dependency has been satisfied.
+ </p>
+ </sect1>
+ </sect>
+
</chapt>
must be linked against all libraries that they use symbols from
in the same way that binaries are. This ensures the correct
functioning of the <qref id="sharedlibs-symbols">symbols</qref>
- and <qref id="sharedlibs-shlibdeps">shlibs</qref>
+ and <qref id="sharedlibs-shlibdeps">shlibs</qref>
systems and guarantees that all libraries can be safely opened
with <tt>dlopen()</tt>. Packagers may wish to use the gcc
option <tt>-Wl,-z,defs</tt> when building a shared library.
<p>
You may wish to restrict your script to SUSv3 features plus the
above set when possible so that it may use <file>/bin/sh</file>
- as its interpreter. If your script works with <prgn>dash</prgn>
- (originally called <prgn>ash</prgn>), it probably complies with
- the above requirements, but if you are in doubt, use
- <file>/bin/bash</file>.
+ as its interpreter. Checking your script
+ with <prgn>checkbashisms</prgn> from
+ the <package>devscripts</package> package or running your script
+ with an alternate shell such as <prgn>posh</prgn> may help
+ uncover violations of the above requirements. If in doubt
+ whether a script complies with these requirements,
+ use <file>/bin/bash</file>.
</p>
<p>
You should not use the copyright file as a general <file>README</file>
file. If your package has such a file it should be
installed in <file>/usr/share/doc/<var>package</var>/README</file> or
- <file>README.Debian</file> or some other appropriate place.</p>
+ <file>README.Debian</file> or some other appropriate place.
+ </p>
+
+ <p>
+ All copyright files must be encoded in UTF-8.
+ </p>
+
+ <sect1 id="copyrightformat">
+ <heading>Machine-readable copyright information</heading>
+
+ <p>
+ A specification for a standard, machine-readable format
+ for <file>debian/copyright</file> files is maintained as part
+ of the <package>debian-policy</package> package. This
+ document may be found in the <file>copyright-format</file>
+ files in the <package>debian-policy</package> package. It is
+ also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/copyright-format/1.0/"
+ id="http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/"></tt>.
+ </p>
+
+ <p>
+ Use of this format is optional.
+ </p>
+ </sect1>
</sect>
<sect>
the <prgn>PATH</prgn> if necessary, and pass its
second and subsequent arguments to the command it
calls. If no <var>root-command</var> is supplied
- then <var>dpkg-buildpackage</var> will take no
- special action to gain root privilege, so that for
- most packages it will have to be invoked as root to
- start with.</p>
+ then <var>dpkg-buildpackage</var> will use
+ the <prgn>fakeroot</prgn> command, which is sufficient
+ to build most packages without actually requiring root
+ privileges.</p>
</item>
<tag><tt>-b</tt>, <tt>-B</tt></tag>
<item>
<prgn>dpkg-genchanges</prgn>.</p>
</sect1>
+ <sect1 id="pkg-dpkg-shlibdeps">
+ <heading>
+ <prgn>dpkg-shlibdeps</prgn> - calculates shared library
+ dependencies
+ </heading>
+
+ <p>
+ See <manref name="dpkg-shlibdeps" section="1">.
+ </p>
+ </sect1>
+
<sect1 id="pkg-dpkg-distaddfile">
<heading>
<prgn>dpkg-distaddfile</prgn> - adds a file to
projects / debian / debian-policy.git / blobdiff