-DFOO_DISABLE_DEPRECATED -vs -lfoo-compat

[Owen Taylor <otaylor redhat com>]

Michael Meeks <michael localhost localdomain> writes:

> > *  whack libgnome1-compat and use GNOME_DISABLE_DEPRECATED,
> >    following the gtk+ scheme
> 
> 	Simply because Gtk+ does it is no good reason for us to; we are
> talking a big chunk of duplicated code here. Linking against
> libgnome1-compat has no intrinsic shame - simply that you are most likely
> to get screwed by Gnome 3.0, and it would be good to start moving now.

Actually just because GTK+ does it _is_ a good reason to do it. Even
if it was a bad idea to do it that way, it's a lot easier to explain
people the operation of FOO_DISABLE_DEPRECATED and FOO_ENABLE_COMPAT
_once_ than to explain a different system for each library.

There are other reasons as well:

 - Using #defines allows us to have two different levels of deprecated.
   ("Helpful for porting, don't use" and "OK to use, but going away
   in the future")

 - Using #defines allows us to deprecate at the method level, even if
   the methods use private internals of the object.
   
 - Using #defines allows integration of the docs for the deprecated functions
   with the main docs using gtk-doc. gtk-doc will catch the #ifdef
   when parsing the headers and put a warning by deprecated functions.

 - And least importantly, but not irrelevant - adding extra functions
   to a library has very little overhead - adding extra libraries 
   has a big overhead. This is a consequence of the way ELF works - basically
   you need to do a hash table lookup for each loaded library.

> 	I also propose that libgnome1-compat is marked as a separate
> help library for which we have no long term plans for keeping API
> compatibility. I have real worries that the extraordinarily anal backwards
> compatibility people are going to be arriving rsn. and we don't want to be
> shooting ourselves in the API foot - indeed a lot of work as gone in to
> try and stop this happening.

This is one of the points of having consistent FOO_DISABLE_DEPRECATED 
macros ... it's very easy for automated tools to track what what entry
points are deprecated and check if a library is using them.

And since -DFOO_DISABLE_COMPAT allows deprecation on the individual
function level, we can make sure that all functions that need to be
deprecated are deprecated.

Regards,
                                        Owen