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

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

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

		  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.

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

	  <heading>Providing a <file>shlibs</file> file</heading>

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

	    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.

Thanks for the review!

Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>

Reply to: