Re: -DFOO_DISABLE_DEPRECATED -vs -lfoo-compat

[Michael Meeks <michael ximian com>]

On 27 Aug 2001, Owen Taylor wrote:
> 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.

        Hmm, but wait - I have no idea how FOO_DISABLE vs. ENABLE work,
which one is master, which is slave, where I should define them - as a
compile flag to gcc ? with ulgy #defines in my source code before gtk
includes ... etc. I see the argument for homogeneity, it just doesn't seem
good to me.

        Let me quickly outline the policy:

        "If you want to include compat code, you need to add the string
'libgnome1-compat' to your pkg-config dependency list"

	Fairly easy to explain, lucid and simple, IMHO.

>  - 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")

        Hmm - all of libgnome1-compat should go away in the future -
perhaps more complexity than we need.

>  - Using #defines allows us to deprecate at the method level, even if
> the methods use private internals of the object.

        That's a fairly good argument - but mostly the things that are bad
in gnome 1.4 we kill at the whole widget level; but perhaps we had more
evil APIs than Gtk+.

>  - 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.

        Problem with documentation is that if a method is documented,
people tend to use it - the converse being true too. The compat code is
simply to make porting easy; we have no desire for people to be easily
finding out about and using these old and nasty APIs. If they need to,
there are always the old API docs to refer to.

>  - 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.

        Well - lets say that this was the determining factor in startup
speed, and that it was a totaly unneccessary addition, and that the
library sat on top of plain gtk+. On my system an ldd on gtk-demo has 19
shared libraries linked in - with more at runtime no doubt; so we'd add a
5% performance penalty. Not significant in terms of some of the builtin
algorithmic inefficiencies around the place.

        In reality of course, none of these assumptions are true.

> 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.

        It's extremely easy with a separate library - you just do:

        ldd my-broken-app | grep 1-compat

> 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.

        This is nice indeed, but not a big issue for Gnome 2.0 I think.

        Regards,

                Michael.

-- 
 mmeeks gnu org  <><, Pseudo Engineer, itinerant idiot