Re: deprecation

[Roland McGrath <roland at hack dot frob dot com>]

[I've trimmed the CC and changed the subject line since this has turned
into a general discussion.]

> There's a general page about deprecations: 
> <http://sourceware.org/glibc/wiki/Deprecation>.  

So far this only talks about "internal" sorts of things, i.e. deprecating
possible configurations for building libc.  I think deprecation of public
APIs is mostly an independent subject.

> To deprecate an interface to the shared libraries, you arrange for it no 
> longer to be available for newly linked programs and shared libraries, 
> only previously linked ones, as was done for the RPC code.

That is, use the compat_symbol macro at the definition site.

> At the same time, you remove it from the headers (I don't think there
> should be an intermediate stage when it's available for linking but not
> in the headers, or vice versa).  

Agreed.

> Unless it's needed internally (like the RPC code), you also arrange for
> it not to be built at all for architectures whose minimum symbol version
> is sufficiently new.

That is, use #if SHLIB_COMPAT (...) around the definition.

> (What would the versions for the RPC symbols look like for an architecture 
> with GLIBC_2.14 or later as minimum version?  I suppose that without 
> --enable-obsolete-rpc the symbols would be present at the minimum version, 
> but not available for linking against.  Only if we eliminate the need for 
> the symbols to be used internally, maybe arranging for libtirpc to be 
> dlopened as needed once it has all the required features, could we then 
> set a later version as the one such that if the minimum symbol version is 
> that recent then the code isn't built in at all.)

I was too lazy to bring this up earlier.  In theory, it's already a problem
for x32, with minimum version 2.16.  But I'm adequately sure that everybody
who builds an x32 distro is going to use --enable-obsolete-rpc for now that
we can put off "doing it right" until 2.17 at least.  Once we're doing this
correctly, it will really be a problem to keep --enable-obsolete-rpc around
unless we figure out some new machinery.

We have the #if SHLIB_COMPAT mechanism for excising code that is entirely
dead.  

For code that is used internally but never exported outside libc itself, we
can just drop the exports entirely.  Doing this for a case like sunrpc
(that is, a putative case like sunrpc in a new configuration that has
minimum symbol version 2.17), where we're preserving the code with its
original symbol names and conditionally exporting it for ABI compatibility
in some subset of configurations, will require some new machinery we don't
yet have.

For code that is used internally by other DSOs but not meant to be exported
outside the glibc-controlled family of libraries (as is the true case with
sunrpc), then we have to use GLIBC_PRIVATE exports.  Doing this
conditionally is again new territory requiring new machinery.

> Perhaps someone familiar with the relevant symbol versioning mechanisms 
> could write up something for the wiki about how to make a symbol not 
> available for new programs, and how to make it not available at all if the 
> minimum symbol version is new enough?

That much is pretty straightforward with shlib-compat.h mechanisms.


Thanks,
Roland