Bug#571776: document symbols

[Jonathan Nieder <jrnieder@gmail.com>]

Julien Cristau wrote:
> On Mon, Mar 19, 2012 at 17:26:04 -0500, Jonathan Nieder wrote:

>> What about libraries like glib (assuming one only uses old symbols)
>> that are never supposed to change soname?
>
> What about them?

I wanted to make sure that forbidding hard-coded dependencies on them
is intentional.  It seems like a good choice to me, but it should be a
deliberate choice (and it does not seem obvious to me that a patch
documenting symbols would automatically do that).

>> [...]
>>> 	  <file>shlibs<file> files also have a flawed representation of
>>> 	  library SONAMEs, making it difficult to use <file>shlibs</file>
>>> 	  files in some unusual corner cases.
>>
>> I'm not sure what this passage is referring to.  Can you say more?
>> (Maybe in a footnote.)
>
> libfooN.shlibs says 'libfoo N' not the actual SONAME, so if the SONAME
> doesn't match one of the two expected formats (libfoo-N.so or
> libfoo.so.N) it can't be represented.

Thanks.  Sounds like good text for a footnote.

[...]
>> To avoid confusion it might be worth forbidding symbols files in
>> udebs, or at least symbols files without a corresponding shlibs file
>> accompanying them.
>
> That makes no sense.  udebs don't have those files, when building an
> udeb the dependency information is read from the shlibs files of the
> debs corresponding to the libraries you depend on.

Oh, good catch.  Russ's text said:

	  <file>symbols</file> files are therefore recommended for most
	  shared library packages since they provide more accurate
	  dependencies.  For most C libraries, the additional detail
	  required by <file>symbols</file> files is not too difficult to
	  maintain.  However, maintaining exhaustive symbols information
	  for a C++ library can be quite onerous, so <file>shlibs</file>
	  files may be more appropriate for most C++ libraries.  udebs
	  must also use <file>shlibs</file>, since the udeb infrastructure
	  does not use <file>symbols</file>.

which sounded like it was saying that most shared libraries should
provide symbols files but udebs should not since the infrastructure
does not support it.

If I understand you correctly, the actual rule would be:

 - symbols files are always recommended

 - the deb corresponding to a shared library udeb must provide a
   shlibs file to support udeb infrastructure

 - udebs provide neither shlibs nor symbols files

[...]
>>>                                                    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>
>>
>> An alternative is to clear substvars between builds of different
>> binary packages.
>
> Who does that?

I did before I saw this patch, in a package not yet proposed for
upload to Debian.  Should I be ashamed?

>>> 	    There are two types of ABI changes: ones that are
>>> 	    backward-compatible and ones that are not.  An ABI change is
>>> 	    backward-compatible if any binary was linked with the previous
>>> 	    version of the shared library will still work correctly with
>>> 	    the new version of the shared library.  Adding new symbols to
>>> 	    the shared library is a backward-compatible change.  Removing
>>> 	    symbols from the shared library is not.
>>
>> If I remove a symbol that was documented to be private or change
>> the behavior of a function when given invalid arguments, is that a
>> backward-compatible change?
>>
>> If I add change the implementation in such a way that the library
>> becomes so large that some large programs cannot use it any more, is
>> that a backward-incompatible change?
>
> I'm not sure policy should go into such details.

Sorry for the lack of clarity.  I never meant to suggest that policy
should speak to these cases directly.  That would be insane, and among
other consequences it would result in a very long policy manual.

What I was trying to hint at is that the above definition gives the
wrong answer to both questions.

> And anyway, that's
> answered by the previous sentence (an incompatible change is one that
> breaks reverse deps).  The last two are simple examples.

The definition says a change is backward-compatible when "any binary
[that] was linked with the previous version of the shared library will
still work correctly with the new version of the shared library".  If
I understand it correctly, that means that the answer to the first
question is "no" (a binary using private symbols is still a binary)
and the answer to the second question is "yes" (a binary whose process
image barely fits in address space is still a binary).

I believe the definition would need a word like "reasonable" before
"binary" to be accurate.

Thanks for your help,
Jonathan