Bug#571776: document symbols
Russ Allbery wrote:
> I'm therefore including here the complete
> SGML source of that section not in diff format, followed by the diff of
> everything *outside* of that section. I think this will be easier to
> review.
Thanks! I would have preferred a diff since it shows the text that is
being replaced, too, but let's go with this for a first pass.
[...]
> <p>
> If a package contains a binary or library which links to a
> shared library, we must ensure that, when the package is
> installed on the system, all of the libraries needed are also
> installed.
This text is carried over from before and contains a requirement I
never noticed before. Suppose my package contains two binaries:
maintool and side-tool. The latter is not very important and links
to libbiglibrary. I might be tempted to make the dependency by my
package on libbiglibrary a Recommends instead of a Depends. The above
says I must not.
Intentional? It seems like good policy, anyway.
> These dependencies must be added to the binary
> package when it is built, since they may change
This means packages must not hard-code library dependencies. It
also seems like good policy, but I suspect it would render packages
such as chromium that use dlopen() and hard-code the corresponding
library name in dependencies RC-buggy.
What about libraries like glib (assuming one only uses old symbols)
that are never supposed to change soname?
[...]
> 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.
Subject/verb agreement: s/provide/provides/
Clarity: s/this library/interfaces provided by this library/
> <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.
Maybe, since minimal-version is not always the version in which the
symbol was introduced:
and, for each, a minimal version of the library needed to use
that symbol, which is typically the version of the package in
which it was introduced.
[...]
> <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.
I'm not sure what this passage is referring to. Can you say more?
(Maybe in a footnote.)
[...]
> udebs
> must also use <file>shlibs</file>, since the udeb infrastructure
> does not use <file>symbols</file>.
To avoid confusion it might be worth forbidding symbols files in
udebs, or at least symbols files without a corresponding shlibs file
accompanying them.
[...]
> 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
> different <file>substvars</file> file for each binary
> package.<footnote>
An alternative is to clear substvars between builds of different
binary packages.
[...]
> loads <tt>libbar</tt>. A package should depend on the
> libraries it directly uses, but not the libraries it
> indirectly uses.
Pedantry: what if my package uses the same library both directly and
indirectly? "but not the libraries it only uses indirectly" would
avoid that question.
> 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.
If I remove a symbol that was documented to be private or change
the behavior of a function when given invalid arguments, is that a
backward-compatible change?
If I add change the implementation in such a way that the library
becomes so large that some large programs cannot use it any more, is
that a backward-incompatible change?
[...]
> <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.
It's not obvious at first how the two clauses of this sentence relate
to each other. (Why would which package provides the file and its
path necessarily relate to each other?) Mentioning that this is a
control file in the package (i.e., adding "as a control file" before
"by the shared library package") might help.
[...]
> 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>.
s/of /on /g
[...]
> +++ b/policy.sgml
> @@ -848,10 +848,11 @@
> Among those files are the package maintainer scripts
> and <file>control</file>, the <qref id="binarycontrolfiles">binary
> package control file</qref> that contains the control fields for
> - the package. Other control information files
> + the package. Other control information files include
Unrelated change. The patch would have been easier to review if this
were a separate commit, which could have gone straight to master since
it doesn't change the output.
The rest looks good from a quick glance. Thanks again for writing
this.
Jonathan
Reply to: