Advances in deprecation technology

A while ago, I wrote about our new better way to do deprecation warnings in the GTK+ stack by letting the compiler do the warnings.  That work came out of the Montreal summit. Here we are, half a year later, and the our next get-together (the GTK+ hackfest last week in Brno) produces another big improvement for our deprecation technology.

This time it was Emmanuele Bassi who took the initiative and added versioning information to our deprecation annotations. This means that it is now possible to say to your compiler:

Warn me about deprecations up to version 2.30, but I don’t want to chase the recent deprecations that have been going into 2.31 yet.

Doing this is just as easy as turning off deprecation warnings altogether. You just define a preprocessor symbol. In the case of GLib, it would be


While Emmanuele was at it, he threw in another nicety: You can now get compiler warnings for ‘too new’ API too. And it is just as easy:


will produce a compiler warning if you use API that was not available in GLib 2.28. This comes in handy when you want to ensure that your application continues to build on older distributions.

GTK+ has these new deprecations as well, the relevant preprocessor symbols to use here are GDK_VERSION_MIN_REQUIRED and GDK_VERSION_MAX_ALLOWED.

Versioned deprecations should make it a lot easier to gradually port applications to new API, as opposed to the current situation where you either have to chase all the latest API or ignore deprecations altogether. Thanks, Emmanuele !

Hackfest stop 1


Color Chart // Crossett Library

I arrived late to the developer conference / hackfest / general get-together in Brno, but so far I am really enjoying it. The GTK+ hackfest is off to a very good start; not so much in producing code, but in clarifying my views on what direction we want to take for integrating touch into our APIs. The concrete take-away from todays multi-touch discussion are:

  • We will have basic touch events in GDK 3.4. These will be pretty direct wrappers of the TouchBegin/TouchUpdate/TouchEnd events that are the basis of touch support on all the platforms that we are interested in.
  • Support for smooth scrolling will also find its way into GTK 3.4.  This works on OS X and X11 (with XI 2.2).
  • Combining touch events into touch clusters and multi-touch events will not be part of GTK 3.4. The general consensus was that it is better to do this inside GTK+, instead of exposing it as GDK api.
  • Gesture recognition will also not make it into 3.4. The exact form in which this will appear in GTK+ 3.6 (or later) is still a bit up in the air, but breaking out event controllers as separate objects, and registering them with widgets seems like a very plausible approach. Doing things this way will allow us to unify touch gesture recognition with the handling of mouse event sequences like press-and-hold or double-clicks.
  • It is still somewhat undecided whether capture-bubble event propagation (ie sending events first from the top down, before propagating them from the target widget up) will make it into 3.4.

Tomorrow will be focused on talking about clutter and meeting the GNOME design team. Should be fun.


Better logging

First an update on deprecations: GLib and GTK+ master have been fully converted to use function attributes for deprecations now, and most uses of G_DISABLE_DEPRECATED guards in GLib headers have been removed. They are still used for deprecated things that are not symbols, like macros and enum values. I haven’t done the same for GTK_DISABLE_DEPRECATED yet, but it should happen fairly soon. Looking forward to a future of less deprecation-induced build breakage (unless you insist on -Werror, of course…).

Continuing the theme of ‘making things suck less for developers’… another favourite is logging.  It is very hard to get right; you want to add plenty of debug and diagnostic messages to help with, well, debugging. But then people complain if you fill up their syslog or .xsession-errors with tons of debug spew, like here. The GLib logging system with g_log() and the macro wrappers g_debug(), g_warning(), etc leaves much to be desired. It does have the concept of replaceable log handler functions, which is ok for complicated uses. But unfortunately, the default handler is so inflexible that many applications are forced to install a custom handler just to be able to turn debug output on and off.

As a small step towards making better logging, the default log handler in GLib master now only emits errors, warnings and criticals. Informational and debug messages are only emitted if you set the G_MESSAGES_DEBUG environment variable. The value can be a list of log domains that you are interested in, or the special value ‘all’ to get it all. As a reminder, the log domain is almost invisible in your code unless you use g_log() directly; it’s what you define by adding -DG_LOG_DOMAIN=”MyCoolApp” to your CPPFLAGS.


On deprecations

There was a lot of discussion last weekend about building an OS, and the various complications that inevitably come up when you put together a system out of many evolving pieces. One of the problems is that it is next to impossible to do a full build without running into at least a couple of modules that don’t build.

Naturally, this happens more frequently early in the cycle, when its deprecation season. Deprecations are meant to give the users of an API some early warning that a function they are using might disappear at some point in the future, and give them time to prepare.

We make things more difficult for ourselves by doing deprecations in a lo-tech way that involves just hiding deprecated symbols behind an ifdef. And to help people find the uses of deprecated symbols in their code, GNOME_MAINTAINER_MODE_DEFINES enables those ifdefs. Taken together, these two imply instant build breakage whenever a new deprecation is added.

Thankfully, gcc (other compilers too) has long supported a way to annotate deprecated functions so that each use triggers a compiler warning and we even have a macro wrapper (G_GNUC_DEPRECATED) around this function attribute in GLib. We just never got around to actually using these annotations for our own deprecations – in part because gtk-doc also used to rely on the ifdefs to recognize deprecated APIs and generate suitable warnings in the documentation.

During and after the Monreal summit, I set out to finally modernize the deprecation system in GLib and GTK+ by using annotations. If your code is using deprecated GLib or GTK+ function, you will now get compiler warnings. It is your choice to turn these into build failures with the help of -Werror. You can also make them go away by using -Wno-deprecated-declarations or by defining GLIB_DISABLE_DEPRECATION_WARNINGS (for GTK+, use GDK_ as a prefix for the define).

I’ve left the ifdef deprecation guards in place for now. For one thing, they can be used to deprecate other things like enumeration values, where the attribute doesn’t help.

Now we just need to neuter GNOME_MAINTAINER_MODE_DEFINES for a future with hopefully less deprecation-induced build breakage.