Difference between revisions of "GTK+ 3 migration"

From Inkscape Wiki
Jump to navigation Jump to search
(Started with a non-exhaustive list)
 
 
(17 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
<big style="color:darkred"><center>This page is out-of-date. Inkscape trunk must be built with GTK+ 3. See: [[Gtk issues]]</center></big>
 +
 +
<big><center>''Inkscape trunk will soon stop supporting GTK+ 2 builds.<br />The forthcoming Inkscape 0.92 release '''will''' still use GTK+ 2.<br />See the [[Notice of removal of GTK+ 2 support|migration page]] for details.''</center></big>
 +
 
Inkscape currently makes use of the GTK+ 2.20 library API.  Ultimately, we will need to switch to the new GTK+ 3 API.  This version of the library introduces a number of major changes that are incompatible with GTK, so we need to make some changes to Inkscape.
 
Inkscape currently makes use of the GTK+ 2.20 library API.  Ultimately, we will need to switch to the new GTK+ 3 API.  This version of the library introduces a number of major changes that are incompatible with GTK, so we need to make some changes to Inkscape.
  
−
== Guidance from upstream ==
 
−
The GTK+ 3 reference manual offers some [http://developer.gnome.org/gtk3/stable/gtk-migrating-2-to-3.html#id1391340 guidance] for the upgrade process.
 
  
−
== Deprecated symbols ==
+
== Building Inkscape against GTK+ 3 ==
−
Inkscape currently makes use of a number of deprecated GTK+ symbols.  We need to get rid of all of these before we can upgrade. Some are very easy to replace. Some are a little more challenging. We need to ensure that Inkscape still builds correctly when the "-DGTK_DISABLE_DEPRECATED" compiler flag is applied.
+
First, configure Inkscape to build against GTK+ 3 using <code>configure --enable-gtk3-experimental</code>.  I prefer to use a separate subfolder for these experimental builds.
 +
 
 +
<pre>
 +
# Create a subfolder in the source directory for the experimental builds
 +
mkdir build-gtk3
 +
cd build-gtk3
 +
 
 +
# Configure to use GTK+ 3
 +
../configure --enable-gtk3-experimental
 +
</pre>
 +
 
 +
After this, you can build as usual.
  
−
=== Switch to gobject ===
+
== Current status ==
−
The GtkType and GtkObject API has been replaced by the gobject library.
+
Inkscape builds successfully against GTK+ 3, but the resulting program is unstable and isn't recommended for users yet. A few key issues are as follows:
  
−
=== Use accessor functions to GtkWidget ===
+
* Several significant bugs affect the GTK+ 3 builds.  Please see the [https://bugs.launchpad.net/inkscape/+bugs?field.tag=gtk3 list of known bugs], and please report any more that you find!
−
Accessor functions such as <code>gtk_widget_has_focus()</code> should be used instead of deprecated macros such as <code>GTK_WIDGET_HAS_FOCUS()</code>
+
* The Gtk+ 3 builds introduce a number of dependencies, including version 3.3.4 of the GDL dockable-dialog library (Gtk+ 2 builds use an internal copy of the library).  Most linux distributions now provide this.  We're [[Tracking Dependencies|tracking the dependencies]]... keep an eye on the list.
 +
* There is currently no easy way of building against Gtk+ 3 on Windows.  However, there is [https://bugs.launchpad.net/inkscape/+bug/1088612 work in progress].
 +
* Gtk+ 3 is still evolving.  To avoid being affected by the level of pain we experienced with the Gtk+ 2 -> Gtk+ 3 migration, we should aim to stay as up-to-date with our API usage as possible... i.e., eliminate [[#deprecated symbols]] as soon as possible!
  
−
=== Get rid of "visual" functions for GtkWidgets ===
+
== Guidance from upstream ==
−
The visual for a widget, and also the default visual is now derived from the colormap for the widget and the default colormap. <code>gtk_widget_set_visual()</code>, <code>gtk_widget_set_default_visual()</code>, <code>gtk_widget_push_visual()</code> and <code>gtk_widget_pop_visual()</code> now do nothing. Since the visual always had to match that of the colormap, it is safe to simply delete all references to these functions.
+
The GTK+ 3 reference manual offers some [http://developer.gnome.org/gtk3/stable/gtk-migrating-2-to-3.html#id1391340 guidance] for the upgrade process.
  
−
=== Don't use GtkNotebookPage ===
+
== Deprecated symbols ==
−
The <code>GtkNotebookPage</code> structure has been removed from the public header files; this was never meant to be a public structure, and all functionality that could be done by accessing the struct fields of this structure should be accessible otherwise.
+
There are a few macros that can be defined during compilation to protect us against usage of deprecated GTK+ 3 symbols, by doing something like:
 +
<pre>make -k CPPFLAGS+="-DMACRO"</pre>
 +
where "<nowiki>MACRO</nowiki>" should be replaced by a macro from the following list:
 +
* GTK_DISABLE_DEPRECATED - prevent usage of deprecated GTK+ symbols
 +
* GDK_DISABLE_DEPRECATED - prevent usage of deprecated GDK symbols
 +
* GTKMM_DISABLE_DEPRECATED - prevent usage of deprecated Gtkmm symbols
 +
* GDKMM_DISABLE_DEPRECATED - prevent usage of deprecated Gtkmm symbols
  
−
=== Switch from GtkCombo to GtkComboBoxEntry ===
+
In addition to this, several deprecated symbols (in a number of libraries) have been tagged with the "deprecated" attribute in their C/C++ declarations. Most compilers will therefore warn you at compile time if the symbol is in use. To turn these warnings into errors, you can do something like:
−
See [http://developer.gnome.org/gtk/2.24/migrating-GtkCombo.html]
+
<pre>make -k CPPFLAGS+="-Werror=deprecated-declarations"</pre>
  
−
=== Get rid of GtkAction proxy functions ===
+
In all the above cases, the "-k" flag is used to tell make to keep processing after errors have been found. This lets us generate a complete "todo" list of errors in the code rather than just seeing the first.
−
gtk_action_connect_proxy has been deprecated since version 2.16 and should not be used in newly-written code. Use gtk_activatable_set_related_action() instead.
 

Latest revision as of 12:24, 6 March 2017

This page is out-of-date. Inkscape trunk must be built with GTK+ 3. See: Gtk issues
Inkscape trunk will soon stop supporting GTK+ 2 builds.
The forthcoming Inkscape 0.92 release will still use GTK+ 2.
See the migration page for details.

Inkscape currently makes use of the GTK+ 2.20 library API. Ultimately, we will need to switch to the new GTK+ 3 API. This version of the library introduces a number of major changes that are incompatible with GTK, so we need to make some changes to Inkscape.


Building Inkscape against GTK+ 3

First, configure Inkscape to build against GTK+ 3 using configure --enable-gtk3-experimental. I prefer to use a separate subfolder for these experimental builds. 

# Create a subfolder in the source directory for the experimental builds
mkdir build-gtk3
cd build-gtk3

# Configure to use GTK+ 3
../configure --enable-gtk3-experimental

After this, you can build as usual.

Current status

Inkscape builds successfully against GTK+ 3, but the resulting program is unstable and isn't recommended for users yet. A few key issues are as follows:

  • Several significant bugs affect the GTK+ 3 builds. Please see the list of known bugs, and please report any more that you find!
  • The Gtk+ 3 builds introduce a number of dependencies, including version 3.3.4 of the GDL dockable-dialog library (Gtk+ 2 builds use an internal copy of the library). Most linux distributions now provide this. We're tracking the dependencies... keep an eye on the list.
  • There is currently no easy way of building against Gtk+ 3 on Windows. However, there is work in progress.
  • Gtk+ 3 is still evolving. To avoid being affected by the level of pain we experienced with the Gtk+ 2 -> Gtk+ 3 migration, we should aim to stay as up-to-date with our API usage as possible... i.e., eliminate #deprecated symbols as soon as possible!

Guidance from upstream

The GTK+ 3 reference manual offers some guidance for the upgrade process.

Deprecated symbols

There are a few macros that can be defined during compilation to protect us against usage of deprecated GTK+ 3 symbols, by doing something like: 

make -k CPPFLAGS+="-DMACRO"

where "MACRO" should be replaced by a macro from the following list:

  • GTK_DISABLE_DEPRECATED - prevent usage of deprecated GTK+ symbols
  • GDK_DISABLE_DEPRECATED - prevent usage of deprecated GDK symbols
  • GTKMM_DISABLE_DEPRECATED - prevent usage of deprecated Gtkmm symbols
  • GDKMM_DISABLE_DEPRECATED - prevent usage of deprecated Gtkmm symbols

In addition to this, several deprecated symbols (in a number of libraries) have been tagged with the "deprecated" attribute in their C/C++ declarations. Most compilers will therefore warn you at compile time if the symbol is in use. To turn these warnings into errors, you can do something like: 

make -k CPPFLAGS+="-Werror=deprecated-declarations"

In all the above cases, the "-k" flag is used to tell make to keep processing after errors have been found. This lets us generate a complete "todo" list of errors in the code rather than just seeing the first.

Retrieved from "https://wiki.inkscape.org/wiki/index.php?title=GTK%2B_3_migration&oldid=104786"