Re: Bug#571776: document symbols
Hi,
On Mon, 02 Jan 2012, Russ Allbery wrote:
> <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. 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 linnked
s/linnked/linked/
[...]
> <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.
[...]
> <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
> your <file>debian/rules</file> file in the source package.
> List all of the compiled binaries, libraries, or loadable
> modules in your package.
----
> 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.
> <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.
> </footnote>
> </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
> 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>.
> </footnote>
I would indicate in the footnote that dh_shlibdeps/dh_gencontrol use an
alternate substvars file by default (debian/<pkg>.substvars).
> <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 ?
[...]
> <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.
[...]
> <sect1>
> <heading>Providing a <file>shlibs</file> file</heading>
>
> <p>
> If your package provides a shared library, you need to create
> a <file>shlibs</file> file following the format described
> above. It is usual to call this
> file <file>debian/shlibs</file> (but if you have multiple
> binary packages, you might want to call
> it <file>debian/<var>package</var>.shlibs</file> instead).
> Then let <file>debian/rules</file> install it in the control
> information file area:
> <example compact="compact">
> install -m644 debian/shlibs debian/tmp/DEBIAN
> </example>
> or, in the case of a multi-binary package:
> <example compact="compact">
> install -m644 debian/<var>package</var>.shlibs debian/<var>package</var>/DEBIAN/shlibs
> </example>
> An alternative way of doing this is to create
> the <file>shlibs</file> file in the control information file
> area directly from <file>debian/rules</file> without using
> a <file>debian/shlibs</file> file at all,<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>
> since the <file>debian/shlibs</file> file itself is ignored by
> <prgn>dpkg-shlibdeps</prgn>.
> </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.
----
Besides those details, everything was excellent and I'm happy to second
this (with or without any of the suggested fixes above).
Thanks for the great work!
--
Raphaël Hertzog ◈ Debian Developer
Pre-order a copy of the Debian Administrator's Handbook and help
liberate it: http://debian-handbook.info/liberation/
Reply to: