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.