GTK+ 3.0 tasks

On this wiki page the tasks required to be done for GTK+ 3.0 are listed, together with their progress. The page layout is similar to that of the GtkTasks page, please scroll down for more elaborate descriptions of the task and its current status. The original mail outlining the steps to GTK+ 3.0 can be found here: http://mail.gnome.org/archives/gtk-devel-list/2008-June/msg00014.html.

The tasks have been split up in a set of tasks that can be done in the current development line to prepare the 2.x branch and a set of tasks that should be done once we have branched for a 3.0 development line. Note that not all tasks are fully explained in detail yet -- a lot will still have to be hashed out on the mailing list.

Preparative tasks

• Task Description	Person in charge	Status
  #P1 Sealing structure fields	Javier Jardón	Done See PendingSealings
  #P2 Implement class private data	Tim Janik	#521707 (Done)
  #P3 Deprecate public class data		Not started
  #P4 Introduce GObject convenience accessors	Christian Dywan	#541569 (not needed)
  #P5 Replace macro accessors	Christian Dywan, Mitch	#69872 done
  #P6 Investigate GtkStyle	Garnacho	#541136 proposal
  #P7 Investigate diagnostic mode	Christian Dywan	#601686 (has patch)
  #P8 Single header includes	Michael Natterer	Done
  #P9 Investigate sealings in GLib		Not going to happen
  #P10 Investigate sealings Gdk fields	Kristian Rietveld	#592580 done
  #P11 Deprecate non-multihead API	Christian Dywan	#547920 (has patch, need discussion)
  #P12 Investigate using -Bsymbolic	Ryan Lortie	done in GLib and GTK+
  #P13 Investigate using attribute((deprecated))		done

2.9 development branch tasks

• Task Description	Person in charge	Status
  #Q0 Create a 2.90 branch	Christian Dywan	Done
  #Q0 Rebase 2.90 branch	Javier Jardón Emmanuele Bassi	Done
  #Q1 Remove all deprecate code	Christian Dywan Javier Jardón	gtk and gdk
  #Q2 Remove all structure fields	Javier Jardón	done
  #Q3 Disable deprecated functions by default		done
  #Q4 Enforce single header includes	Michael Natterer	Done
  #Q5 Ensure parallel installability with GTK+ 2.x		Done

#P1

Seal all public structure fields using the GSEAL() macro. If necessary, provide new accessor functions to these fields. Also "priv" fields that point at structures containing private object data are sealed.

Need to make sure that tools that parse headers, like gtk-doc, binding generation tools, etc, still work and can thus handle the insertion of the GSEAL() macro.

#P2

Implement class private data. This is very similar to what we already have for creating the private object data. It involves changing the GType code and fortunately Tim is going to take care of this for us

#P3

We should deprecate public class data through GSEAL(). Later on these fields can be moved into private class data on demand.

#P4

We will completely lose all means to simply access fields by just dereferencing the structure. Instead, we will start to use accessor functions and GObject properties. We should introduce a couple of convenience accessors for GObject properties such as g_object_get_int(), *double(), *string(), etc.

See bug #541569

#P5

There are a couple of "macro accessors", like GTK_WIDGET_GET_FLAGS() that have always been troublesome (see bug #69872). We should provide normal accessors (functions) for these instead and then get rid of the macro accessors.

#P6

Without question, GtkStyle is most definitely the hardest thing to properly seal. In addition, a lot of people agree that there are some parts to fix here before we release 2.9, since there is a good chance that otherwise we will not be able to fix this in 3.0 onwards like we can do with the other components. This will need to be investigated and reported on. See #541136.

#P7

In our original plans we have been talking about a diagnostic mode. One of the main ideas was that this can be enabled during run-time to check whether an application is easily portable to a newer GTK+ version, ie. it does not do things that are not covered by ABI/API guarantees. Such things include the poking inside widget hierarchies, calling deprecated functions, etc. When an application does such things, a runtime warning could be printed on standard output. What exactly the diagnostic mode should include and be able to do is not at all clear yet. This should be investigated and a proposal be written and discussed.

#P8

We should start to enforce the usage of single header includes and not make this optional.

#P9

We should investigate what things in GLib we want to seal, if any. If we do decide to seal things in GLib, the GSEAL macro definition will have to be moved to GLib from GTK+. Then we can remove the extraneous gdkconfig.h includes from the GTK+ header files where needed (we had to add these includes to for example gtktreemodel.h to get the GSEAL macro defined).

#P10 - Sealing Gdk

Publically exposed strcutures in Gdk should be sealed just like in Gtk. Some judgement is needed to not seal value structures such as GdkWindowAttr.

#P11 - Deprecate non-multihead API in Gdk and Gtk

Gdk and Gtk contain some backwards compatibility API from before it was multihead safe. Deprecating this for 2.16 wil enable us to get rid of it for 3.x.

#P12 - Investigate using -Bsymbolic

GLib and GTK+ currently use a somewhat cumbersome method of avoiding PLT overhead for internal calls to public functions (using hidden aliases, see makegtkalias). It may be possible to achieve the same effect but passing -Bsymbolic to the linker. That would be a considerable simplification of the code and the build process.

Complications: the symbol lists that are used for the current method are also used to create .def files for win32 and to check the ABI for accidental exports.

#P13 - Investigate using attribute((deprecated)) for deprecation

GLib and GTK+ currently use a cpp-based method of deprecation. Switching to the attribute-based method would have the benefit that it can give warnings, instead of just breaking the build (as the current method) and the warnings can point exactly to the source location of deprecated api usage.

Also, if we hide the attribute behind a macro, we may be able to do add some more magic to e.g. move deprecated functions to its own text segment, reducing their runtime overhead.

The downside of switching to the attribute-based method is that gtk-doc supports the current method, so it would have to be enhanced to handle both. See 624001

#Q0

Development towards 2.90/ 3.0 is happening on a branch, in parallel to the GTK+ 2.20 development on master. The branch is rebased regularly.

#Q1

Remove all code that has been deprecated in the 2.x series. This includes all widgets and functions that have been marked as such. To make it clear, we will not mark any code as newly deprecated in the 3.0 release

There has been discussion about moving deprecated widgets to a separate library, libgtk3deprecated or similar, instead of removing them altogether. See e.g. http://mail.gnome.org/archives/gtk-devel-list/2008-July/msg00151.html

#Q2

Remove all structure fields from the public API. There are two ways this can be done:

1. Move struct member to private headers.
2. Move struct member to the local C file, the rest of GTK+ will then also have to use accessors.

If we pick option b), this step will include adapting all GTK+ source files to use accessors instead of direct field accesses. For a) we can also choose to have only bigger widgets (such as GtkTreeView) share the private headers with the structures and then the other parts of GTK+ that do not include these headers will again have to use accessors.

Note: It was decided that b is the best option in the 20100323 meeting

#Q3

Change the compile flags to disable deprecated functions by default.

#Q4

Remove G_ and GTK_DISABLE_SINGLE_INCLUDES and enforce including glib.h and gtk.h only.

#Q5

It must be possible to install GTK+ 2.x and GTK+ 3.x in parallel, and build applications against each of them by choosing the right pkgconfig files. It is not required that one can use both versions in the same process.