Re: Deprecations

[Mart Raudsepp <leio dustbite net>]

On Thu, 2006-04-27 at 10:34 -0400, Owen Taylor wrote:
> On Thu, 2006-04-27 at 01:22 +0300, Mart Raudsepp wrote:
> > On Wed, 2006-04-26 at 21:23 +0100, Ross Burton wrote:
> > > On Wed, 2006-04-26 at 15:18 -0400, David Hampton wrote:
> > > > > Would it make sense to mark all of the deprecated API in GLib and GTK+
> > > > > with G_GNUC_DEPRECATED, so that people who are not using the
> > > > > DISABLE_DEPRECATED macros still get warned that they are using
> > > > > deprecated functions?
> > 
> > Yes, pretty please.
> > I'm trying to nuke out all uses of deprecated functions, but declaring
> > all the *_DISABLE_DEPRECATED macros is a bit rough still (I can't test
> > on all of the combinations of systems the thing is supposed to not error
> > out)
> 
> *_DISABLE_DEPRECATED is a tool for developers / for you; you should
> never ship like that, because *any* function may be deprecated in a
> future version and you have no control over that.

Good point.
This is for enforcing co-developers to not start using deprecated
functions anymore.
I'll have to factor it out a bit more to not slip into releases. Haven't
reached that point yet (and a release is far away), but didn't yet think
about it, so thanks for pointing out that I can't possibly predict what
becomes deprecated in GTK+-2.12 or later.

As for users having a newer version than developers or an old release
being used with a later released gtk, leading to zillions of warning -
personally I mainly seek G_GNUC_DEPRECATED for the gtk1 functions that
are deprecated. Old list, tree, text control, gtk_window_set_usize, etc.
Beyond that it becomes controversial, indeed.

In my case I need to compile cleanly down to gtk2.0, so I have
infrastructure to deal with that too, and in fact unconditional
deprecated warnings on things deprecated in gtk2.4 will have to stay as
warnings in our sources, if they'd start giving warnings -
a combo box is a GtkComboBox with gtk2.4+ compile- and runtime, but
GtkOptionMenu if runtime version is lower then 2.4. The library (yes,
wxWidgets) compiled against GTK+-2.8 will work with a GTK+-2.0 runtime.
In other words, GtkOptionMenu code is always compiled in, and
unconditional deprecation warnings would be annoying. However, the
source files using deprecated classes are isolated, and therefore I can
undefine GTK_DISABLE_DEPRECATED selectively. Warnings instead of
compilation errors would be desirable, of course.

Therefore I propose a fine-tunable solution as G_GNUC_DEPRECATED doesn't
affect ABI - have the ability to define the (major/minor) version number
up to which deprecation warnings are issued, 2.0 as default (or 1.0 if
so desired), through a macro definition.
That way, in the common case, an application developer can set that
value to the minimum supported gtk+ version by his application, be it
through a configure switch or not. If he has an enforced minimum version
of gtk, and he has ensured it doesn't utilize any functions deprecated
in that minimum supported version, it doesn't need a configure switch.

A --enable-deprecation-warnings switch could then be used to define the
version number, up to which deprecations are warned about, to a high
number, as to get a warning about any and all deprecations.


In a common gtk header (untested half-pseudocode):

#ifndef GTK_DEPRECATED_MAJOR
  #define GTK_DEPRECATED_MAJOR 2
#endif
#ifndef GTK_DEPRECATED_MINOR
  #define GTK_DEPRECATED_MINOR 0
#endif

#define GTK_DEPRECATED_WARNING(major, minor) \
  #if ((major) < GTK_DEPRECATED_MAJOR) ||    \
      ( ((major) == GTK_DEPRECATED_MAJOR) && \
          ((minor) < GTK_DEPRECATED_MINOR) ) \
    G_GNUC_DEPRECATED \
  #else \
  #endif \

In header for a deprecated function:
#ifndef GTK_DISABLE_DEPRECATED
/* Deprecated since 2.4 */
void gtk_option_menu_new(args) GTK_DEPRECATED_WARNING(2,4);
#endif

This should just work as before without app developer intervention, but
if he has defined GTK_DEPRECATED_{MAJOR,MINOR} prior to including any
gtk headers (in source code, -D in command line, config.h) to, for
example, 2.6, it should issue a deprecation warning.

Same idea for glib, pango, gdk-pixbuf, gdk, etc


I realize that this is getting quite complicated and quite possibly
unfeasible.
But I thought to throw the idea out regardless, be it good or awful.
I'm willing to get my hands dirty with this, though.

> Add a --configure switch that turns on *_DISABLE_DEPRECATED, configure
> your on compilations that way, fix all the resulting problems, but there
> is no benefit to shipping that way... a deprecation that one of your
> users sees but you don't is a deprecation you can't fix, because you
> aren't using a new enough version of GTK+ to have the replacement.

For this I'll have to research how to add configure flags to our
tinderbox systems, but yeah.

> 						Owen

Many thanks for the pointers,
  Mart