Using public headers to write ABI vscripts

[Alexander Bokovoy]

Hi Andrew,

On Wed, Aug 29, 2012 at 7:54 AM, Andrew Bartlett <abartlet at samba.org> wrote:
> I've been working on a patch to use the mksyms.awk approach to get a
> list of public headers and symbols from our public headers files, and
> use that instead of just the regular-expression abi_match.
>
> https://git.samba.org/?p=abartlet/samba.git/.git;a=shortlog;h=refs/heads/abi-public-headers
>
> It would be great to get this in to 4.0, but I'm having some waf
> challenges I'll need to get past.  The challenge relates to the grouping
> from the build ordering, because we need a vscript for libreplace (very
> early) but vscripts can depend on pild-generated headers.  We may need
> to rely on pure dependencies rather than also the groups.
>
> This came up because I had to bump the ldb ABI (it needed a bump for the
> behaviour change, but it spiked my interest) when adding a private,
> internal symbol.
I'm also working in this area though my needs are bit different at the moment.

https://git.samba.org/?p=ab/samba.git/.git;a=shortlog;h=refs/heads/stableabi
has number of patches that attempt to introduce API namespaces.

I need stable mapping between API namespace and version node name
associated with it that spans across multiple releases (instead of
SAMBA_<VERSION> default symbol changing every release without actual
semantical and ABI change) for certain important private libraries.

One issue we have currently is that ABI generators expect to use
numbers as versions only. This is done with the idea that vnum
(version number) for the library is then used to generate soname as
well. As result, all symbols  in the shared library will be marked
with uniform @NAME_VERSION version nodes, regardless of their intended
use, they only capture when they were introduced,  assuming a single
library provides single API.

Certain important libraries like libpdb contain multiple APIs, due to
internal grouping and bundling of PASSDB modules/features in certain
configurations. Such shared library would have different ABI exposed
when built differently, with more or less symbols available for WAF
builds with or without Samba 4 AD DC support, for example, or other
integrated PASSDB backends.

As result, even marking up symbols as introduced in different versions
of the shared library would still get different results as versioning
is orthogonal to configuration capturing build's features.

If we wanted to mark up features according to their API usage in the
current design of ABI generators, we would need to artificially
inflate version numbers for pdb, assigning 'historical' versions to
certain interface groups, like 'pdb_*' functions or 'sid_*' functions.
 Obviously, this is not helping at all in advertizing what is the
meaning of the version of the ELF symbol, as there is little context
you can discover from a symbol named pdb_get_foo at PDB_0.0.0.5.

Luckily, these @NAME_VERSION version nodes' names have no specific
meaning to the system software itself.  For example, GNU ld manual
states (http://sourceware.org/binutils/docs/ld/VERSION.html#VERSION):
==========================================================================
The names of the version nodes have no specific meaning other than
what they might suggest to the person reading them. The `2.0' version
could just as well have appeared in between `1.1' and `1.2'. However,
this would be a confusing way to write a version script.
==========================================================================

This is exactly what we want to achieve: use version node names to
provide context of use and name/version of API introduced.

This patch adds facilities to override default (global or
per-subsystem) version node name for specific symbols. if
abi_directory for the subsystem contains files
<subsystem>-<name-version>.api, then for each symbol from .api file
corresponding <name-version> will be used as its version node.

If symbol is not referenced anywhere, default version node name is used.

.api files use the same format as .sigs files but anything after
column (:) is ignored. While .sigs files are used for maintaining
strict ABI for purposes of tracking versions of the shared library,
.api files provide contextual history of tracking API additions.

I also fixed abi_match processing to allow negative matches and
corrected vscript generator to apply both positive and negative
matches in appropriate scopes (global/local).

Please note that .api files as they are can easily be used with
abi_match generator that you are working on as they complement each
other.

-- 
/ Alexander Bokovoy