Re: -DFOO_DISABLE_DEPRECATED -vs -lfoo-compat

[Michael Meeks <michael localhost localdomain>]

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 explain the libgnome1-compat policy:

	"If you want to include compat code, you need to add the string
'libgnome1-compat' to your pkg-config dependency list, try looking in
configure.in for this"

	Not tough, or confusing ( at least to me ), lucid and simple.

>  - 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 finding
out about and using these new 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. Gack 5% !?

	In reality of course, none of the above 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, but not a big issue for Gnome 2.0 I think.

	Regards,

		Michael.

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