Bug#571776: document symbols
Raphael Hertzog <hertzog@debian.org> writes:
> On Mon, 02 Jan 2012, Russ Allbery wrote:
> [...]
>> <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>
> In practice I don't think that we have any package providing a symbols
> files without a shlibs file.
Yes, but there was some discussion in the Policy bug asking why shlibs
files were required when they're not used if a symbols file is present,
and while I originally argued that keeping them both made sense, I came
around to that position after reviewing the bug discussion. It doesn't
hurt anything, but there doesn't really seem to be any point in providing
shlibs if symbols is present.
> ----
>> If your source package builds only a
>> single binary package that contains only compiled binaries and
>> libraries (but no scripts) and is not multiarch, you can use a
>> command such as:
>> <example compact="compact">
>> dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
>> debian/tmp/usr/lib/*
>> </example>
>> but normally finding all of the binaries is more
>> complex.
> I would drop the part above (up to the 4 dashes that I added). This
> example will only mislead people IMO because debian/tmp/ is far from
> being the norm. debian/<pkg> is much more common for single binary
> packages. And as you said, it doesn't cover all cases.
Yeah, good point. This was retained from the old shlibs documentation,
but at this point I don't think anyone really looks here to see how to do
this. Dropped.
>> 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>.
>> </footnote>
> I would indicate in the footnote that dh_shlibdeps/dh_gencontrol use an
> alternate substvars file by default (debian/<pkg>.substvars).
I now have:
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.
</footnote>
>> <sect1 id="symbols">
>> <heading>The <file>symbols</file> File Format</heading>
> [...]
>> For our example, the <tt>zlib1g</tt> <file>symbols</file> file
>> would contain:
>> <example compact="compact">
>> * Build-Depends-Package: zlib1g-dev
>> </example>
>> (Don't forget the leading space.)
> What leading space are you referring to ?
I now have:
(Don't forget the space before the <tt>*</tt> so that it will
be parsed as part of the entry for that library.)
Due to the way that the formatting of Policy works, it's very hard to tell
that there's a space there, and unlike with symbols where the indentation
is fairly obvious, it's not completely obvious that it's required.
> [...]
>> <sect1 id="shlibs-paths">
>> <heading>The <file>shlibs</file> files present on the
>> system</heading>
> [...]
>> <item>
>> <p><file>DEBIAN/shlibs</file> files in the "build
>> directory"</p>
>>
>> <p>
>> When packages are being built,
>> any <file>debian/shlibs</file> files are copied into the
>> control information file area of the temporary build
>> directory and given the name <file>shlibs</file>. These
>> files give details of any shared libraries included in
>> the same package.
>> </p>
>> </item>
> debian/shlibs is (no longer) a standard file... debhelper doesn't install
> such files, it generates shlibs files on the fly and I don't believe that
> any modern package still has debian/shlibs.
> So I would rewrite this paragraph to just say that DEBIAN/shlibs is the
> shlibs file produced by the current package build.
I now have:
<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>
> I would shorten the explanation here and drop the example of how to
> install a manually crafted shlibs file. This is far from being the norm
> and should not be difficult to find out alone if one really needs it.
I've replaced this section with just:
<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>
<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>
</sect1>
Thanks for the review!
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: