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

Re: Bug#571776: document symbols

Dear Russ and Raphaël,

here are some comments about the current patch.  I agree with the other changes
made subsequently in that thread.

> +	  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 linked
> +	  with.

I have a difficulty with that sentence : isn't the goal of the symbols system
to actually avoid that a dependancy changes when a package is built on a newer
version of a library ?  What rather changes is that the dependancy is modified
when a new version of the package makes new calls to the library, which may
have been implemented only in newer versions of the library.

If the misunderstanding is on my side, please consider it a hint that the
explanations can be expanded :)  [PS: after reading the whole patch, maybe
this has something to do with minimal-version ?]

> +	<p>
> +	  When a package that contains any shared libraries or compiled
> +	  binaries is built, it must run <prgn>dpkg-shlibdeps</prgn> on
> +	  each shared library and compiled binary to determine the
> +	  libraries used and hence the dependencies needed by the
> +	  package.<footnote>
> +	    <prgn>dpkg-shlibdeps</prgn> will use a program
> +	    like <prgn>objdump</prgn> or <prgn>readelf</prgn> to find the
> +	    libraries and the symbols in those libraries directly needed
> +	    by the binaries or shared libraries in the package.
> +	  </footnote>
> +	</p>

(I understand that this is carried over from 3.9.2, but…) Just running
dpkg-shlibdeps is not enough, as this program only populates debian/substvars.
This is actually documented later in this chapter, which makes this paragraph
redundant.  If its purpose is to lock the use of dpkg-shlibdeps and prevent
parallel implementations, it could be slimmed as follows.

	  Packages that contain any shared libraries or compiled binaries must
	  determine their dependencies by using the <prgn>dpkg-shlibdeps</prgn>
	  program and the <qref id="substvars"><tt>${shlibs:Depends}</tt></qref>
	  substvar.  See <ref id="dpkg-shlibdeps"> for detailed instructions.

> +		<p>
> +		  During the package build, if the package itself contains
> +		  shared libraries with <file>symbols</file> files, they
> +		  will be generated in these staging directories
> +		  by <prgn>dpkg-gensymbols</prgn>.  <file>symbols</file>

With a linear reading, it is the first time dpkg-gensymbols appears in the
Policy.  How about linking to the "symbols" section, that gives a few more
words and refers to the manual page ? 

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

The footnote removed above could be added here:

	    <prgn>dpkg-shlibdeps</prgn> will use a program
	    like <prgn>objdump</prgn> or <prgn>readelf</prgn> to find the
	    libraries and the symbols in those libraries directly needed
	    by the binaries or shared libraries in the package.

> +	  <p>
> +	    This command puts the dependency information into
> +	    the <file>debian/substvars</file> file, which is then used
> +	    by <prgn>dpkg-gencontrol</prgn>.

I propose to mitigate this by adding “by default”, because when using
debhelper, which is very frequent, debian/substvars is actually not used.  (It
took me hours to understand why I could not populate new substvars in
debian/control by simply adding their values in debian/substvars in my
debhelper-managed packages).

> -	<sect1 id="pkg-dpkg-shlibdeps">
> -	  <heading>
> -	    <prgn>dpkg-shlibdeps</prgn> - calculates shared library
> -	    dependencies
> -	  </heading>

I propose to keep a placeholder so that the next subsections are not
renumbered.  Once all these sections are trimmed, we could consider removing
the appendix altogether.

Have a nice day,

Charles Plessy
Tsurumi, Kanagawa, Japan

Reply to: