Re: document symbols
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
>> 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,