Difference between revisions of "GTK+ 3 migration"

From Inkscape Wiki
Jump to navigation Jump to search
(Add instructions for experimental builds)
 
(10 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.
 +
  
 
== Building Inkscape against GTK+ 3 ==
 
== Building Inkscape against GTK+ 3 ==
First, configure Inkscape to build against GTK+ 3 using <code>configure --enable-gtk3-experimental</code>.  I prefer to use a separate subfolder for these (broken) builds.
+
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>
 
<pre>
Line 13: Line 18:
 
</pre>
 
</pre>
  
After this, you can build as usual. However, as there are a huge number of errors, it is useful to instruct the build to continue even if errors are encountered.  This is achieved by using the "<code>-k</code>" flag with Make.  It is also helpful to dump a log of the errors (>5000 lines at the time of writing!).  In summary, I use something like:
+
After this, you can build as usual.
  
<pre>
+
== Current status ==
make -k 2> gtk3-experimental.txt
+
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:
</pre>
+
 
 +
* 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!
 +
* 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!
  
 
== Guidance from upstream ==
 
== Guidance from upstream ==
Line 23: Line 32:
  
 
== Deprecated symbols ==
 
== Deprecated symbols ==
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.  An incomplete "to do" list follows:
+
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>
=== Switch to gobject ===
+
where "<nowiki>MACRO</nowiki>" should be replaced by a macro from the following list:
<https://bugs.launchpad.net/inkscape/+bug/813212>
+
* GTK_DISABLE_DEPRECATED - prevent usage of deprecated GTK+ symbols
 
+
* GDK_DISABLE_DEPRECATED - prevent usage of deprecated GDK symbols
The GtkType and GtkObject API has been replaced by the gobject library.  One of the few remaining issues here is that SPCanvasItem is a subclass of GtkObject.  However, this part of the class hierarchy is currently being rewritten, and will be based on a different parent class.
+
* GTKMM_DISABLE_DEPRECATED - prevent usage of deprecated Gtkmm symbols
 
+
* GDKMM_DISABLE_DEPRECATED - prevent usage of deprecated Gtkmm symbols
=== Use accessor functions to GtkWidget ===
 
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>
 
 
 
=== Get rid of "visual" functions for GtkWidgets ===
 
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.
 
:Done [[User:Valavanisalex|Valavanisalex]] 09:55, 23 June 2011 (UTC)
 
 
 
=== Don't use GtkNotebookPage ===
 
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.
 
 
 
=== Switch from GtkCombo to GtkComboBoxEntry ===
 
See [http://developer.gnome.org/gtk/2.24/migrating-GtkCombo.html]
 
:Done.  A few symbols are left in #if/#else blocks in src/dialogs/text-edit.cpp to allow build compatibility with GTK+ 2.20.  These can be removed once Inkscape has bumped its dependency level to GTK+ >= 2.24. [[User:Valavanisalex|Valavanisalex]] 09:46, 23 June 2011 (UTC)
 
 
 
=== Get rid of GtkAction proxy functions ===
 
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.
 
  
=== Merge GtkRuler into Inkscape ===
+
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 useTo turn these warnings into errors, you can do something like:
The GtkRuler class has been completely removed from GTK+ 3, and will not be replacedGIMP got around the problem by merging the GtkRuler code into their own project.
+
<pre>make -k CPPFLAGS+="-Werror=deprecated-declarations"</pre>
  
=== Build against external GDL ===
+
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.
We currently use our own fork of the GDL library (based on GDL 2.30.0).  This version of GDL contains a few deprecated GTK symbols.  Eventually, we need to get rid of our own fork, and build against the external library.  Progress is being tracked at https://bugs.launchpad.net/inkscape/+bug/792115
 

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.