Bug#571776: document symbols
Jonathan Nieder wrote:
> I'll reply with an interdiff relative to the last version of the
> patch.
Here it is.
Subject: Clarifications to symbols and shlibs policy
subject/verb agreement: s/provide/provides/
Packages with libraries or binaries linking to a shared library must
use symbols or shlibs files to compute their dependencies. Packages
that dlopen() a shared library should do so as well, but since that
is not typical practice and the tools to do that don't exist, it is
not made a policy "must" yet.
The minimal version for a symbol can be bumped after the version of
the package in which the symbol was introduced.
Add a footnote explaining why shlibs files cannot be used for
libraries with unusual sonames.
The shlibs file for a library udeb goes in the corresponding deb.
The library deb corresponding to a udeb is supposed to provide a
shlibs file, rather than consuming (using) one.
Add "for example" when talking about dpkg-shlibdeps -T. This is
just an illustration and not meant to be normative.
If a library is used both directly and indirectly, the direct
dependency still needs to be declared.
Backward-compatibility is defined in terms of what reasonable
programs and libraries need.
In the normal case, symbols files go in dpkg's admindir as package
control files.
wording fix: "dependency on" avoids some of the ambiguity in
"dependency of".
---
policy.sgml | 86 +++++++++++++++++++++++++++++++++--------------------------
1 file changed, 48 insertions(+), 38 deletions(-)
diff --git a/policy.sgml b/policy.sgml
index 1eb039f8..50ae756c 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -5838,25 +5838,30 @@ Replaces: mail-transport-agent
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, 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.
+ a <file>shlibs</file> file, which provides 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>
- These two mechanisms differ in the degree of detail that they
- provide. A <file>symbols</file> file documents every symbol
- that is part of the library ABI and, for each, the version of
- the package in which it was introduced. This permits detailed
- analysis of the symbols used by a particular package and
- construction of an accurate dependency, but it requires the
- package maintainer to track more information about the shared
- library. A <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
+ 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, which is typically the
+ version of the package in which the symbol was introduced.
+ This permits detailed analysis of the symbols used by a
+ particular package and construction of an accurate dependency,
+ but it requires the package maintainer to track more information
+ about the shared library. A <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
@@ -5869,7 +5874,11 @@ Replaces: mail-transport-agent
<p>
<file>shlibs<file> files also have a flawed representation of
library SONAMEs, making it difficult to use <file>shlibs</file>
- files in some unusual corner cases.
+ files in some unusual corner cases.<footnote>
+ libfooN.shlibs says 'libfoo N' instead of the actual SONAME,
+ so if the SONAME doesn't match one of the two expected
+ formats (libfoo-N.so or libfoo.so.N) it can't be represented.
+ </footnote>
</p>
<p>
@@ -5879,9 +5888,9 @@ Replaces: mail-transport-agent
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. udebs
- must also use <file>shlibs</file>, since the udeb infrastructure
- does not use <file>symbols</file>.
+ files may be more appropriate for most C++ libraries. Libraries
+ with a corresponding udeb must also provide <file>shlibs</file>,
+ since the udeb infrastructure does not use <file>symbols</file>.
</p>
<sect1 id="dpkg-shlibdeps">
@@ -5940,8 +5949,8 @@ Replaces: mail-transport-agent
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 the <tt>-T</tt> option
- to the <tt>dpkg</tt> utilities to specify a
+ compiled libraries or binaries, for example using 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>
@@ -5969,8 +5978,8 @@ Replaces: mail-transport-agent
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 the libraries used
+ 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
@@ -6014,14 +6023,15 @@ Replaces: mail-transport-agent
<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 binary was linked with the previous
- version of the shared library will still work correctly with
- the new version of the shared library. Adding new symbols to
- the shared library is a backward-compatible change. Removing
- symbols from the shared library is not. Changing the behavior
- of a symbol may or may not be backward-compatible depending on
- the change; for example, changing a function to accept a new
- enum constant not previously used by the library is generally
+ backward-compatible if any reasonable program or library that
+ was linked with the previous version of the shared library
+ will still work correctly with the new version of the shared
+ library. Adding new symbols to the shared library is a
+ backward-compatible change. Removing symbols from the shared
+ library is not. Changing the behavior of a symbol may or may
+ not be backward-compatible depending on the change; for
+ example, changing a function to accept a new enum constant not
+ previously used by the library is generally
backward-compatible, but changing the members of a struct that
is passed into library functions is generally not unless the
library takes special precautions to accept old versions of
@@ -6122,10 +6132,10 @@ Replaces: mail-transport-agent
<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
+ 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>
@@ -6342,9 +6352,9 @@ Replaces: mail-transport-agent
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
+ dependency on <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>.
+ on <tt>zlib1g (>= 1:1.2.0)</tt>.
</p>
<p>
--
1.7.10.4
Reply to: