[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Bug#571776: document symbols


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


> 	<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: