Sugar Labs

Features/GTK3/Porting: Difference between revisions

← Older editNewer edit →
Pro-panda (talk | contribs)
43 edits
No edit summary
Tag: visualeditor-switched
Line 1: Line 1:
=Porting an existing activity to GTK3=
=Porting an existing activity to GTK3=
This is a guide to porting an existing activity from GTK2 to [http://developer.gnome.org/gtk3/stable/ GTK3]. It also shows the changes to use the new Sugar toolkit that also now uses [[Features/GTK3|GTK3]]. This guide uses the [http://git.sugarlabs.org/hello-world hello-world] activity as a simple example.
This is a guide to porting an existing activity from GTK2 to [http://developer.gnome.org/gtk3/stable/ GTK3]. It also shows the changes to use the new Sugar toolkit that also now uses [[Features/GTK3|GTK3]]. This guide uses the [https://github.com/sugarlabs/hello-world hello-world] activity as a simple example.


There is another guide written from scratch that uses this one as reference. It was done porting GetBooks Activity [[Features/GTK3/Porting/GetBooks]]
There is another guide that uses this one as reference. It was made while porting GetBooks Activity [[Features/GTK3/Porting/GetBooks]]


If you would like to reference other examples of GTK3 port:
If you would like to reference other examples of GTK3 port:
* [https://github.com/sugarlabs/biorhythm/commit/c16de3b70cce2cc6f8af933e2b062c844a47c144/ Biorhythm]
* [https://github.com/sugarlabs/biorhythm/commit/c16de3b70cce2cc6f8af933e2b062c844a47c144/ Biorhythm]
* [https://github.com/sugarlabs/peru-learns-english-activity/commit/caa2cde526b3823a5a1f7d200a76ad5bc3502b0e Peru Learns English, includes GStreamer and GST update]
* [https://github.com/sugarlabs/peru-learns-english-activity/commit/caa2cde526b3823a5a1f7d200a76ad5bc3502b0e Peru Learns English, includes GStreamer and GST update]
==Preparation==
Before you start porting your activity you are encouraged to branch off a stable branch. This will allow you to keep on doing stable releases on the stable branch and new releases on the master branch. We highly recommend that you use the 'sugar-0.94' as the stable branch name because this will keep the repositories consistent and eases the development work. Let's step through this with a real life example:
The latest release of hello-world was version 3 (commit 04fb9beb708f1078aae93995da3ec06bac7aa433). We want to branch off at that point. If you did not do any changes after the last stable commit simply create a branch with:
git branch sugar-0.94
If you have already made commits after that, you need to go to that commit first and create a branch at that specific point in our case commit 04fb9beb708f1078aae93995da3ec06bac7aa433, there is a command to do that in one go:
git checkout -b sugar-0.94 04fb9beb708f1078aae93995da3ec06bac7aa433
In both cases this has created a local branch, as you can see by running 'git branch'; you should see the following (if you did the second command you will have sugar-0.94 already selected):
<pre>
[erikos@T61 helloworld]$ git branch
* master
  sugar-0.94
</pre>
The 'sugar-0.94' branch is only available locally, as you can see by running 'git branch -r' which shows the remote branches:
<pre>
[erikos@T61 helloworld]$ git branch -r
  origin/HEAD -> origin/master
  origin/master
  origin/sucrose-0.84
</pre>
The only branch available besides the master branch is the 'sucrose-0.84' branch. Let's push now our new branch to the remote repository to make it available for others:
<pre>
git push origin sugar-0.94
</pre>
The branch is now listed as a remote branch. You can verify as well on your [http://git.sugarlabs.org/hello-world/mainline gitorious page].
<pre>
[erikos@T61 helloworld]$ git branch -r
  origin/HEAD -> origin/master
  origin/master
  origin/sucrose-0.84
  origin/sugar-0.94
</pre>
You can switch now between those branches using 'git checkout <branch>'. And you can use 'git branch' to see which branch you are on (the one with the * before is the branch you are currently on).
<pre>
git checkout sugar-0.94
git checkout master
</pre>


==Cleanup, adopt to API changes in sugar-toolkit-gtk3 ==
==Cleanup, adopt to API changes in sugar-toolkit-gtk3 ==
''This should be done only on the master branch''! In the new sugar-toolkit-gtk3 we have removed old API, you should adjust your activity accordingly:
* the keep button has been removed completely
* the keep button has been removed completely
* the old-style toolbar has been removed
* the old-style toolbar has been removed
* do not use set_toolbox anymore use set_toolbar_box instead (see in [http://git.sugarlabs.org/~walter/abacus/walter-cairo/commit/6871dd340a89ade3b5361457e1bd1d58276a8efc Abacus])
* set_toolbar_box is used instead of set_toolbox (see in [http://git.sugarlabs.org/~walter/abacus/walter-cairo/commit/6871dd340a89ade3b5361457e1bd1d58276a8efc Abacus])
* remove import of deprecated ActivityToolbox (see [http://git.sugarlabs.org/hello-world/mainline/commit/22060a3063b2d6fd38d6b1cd8d44946170255af3 hello-world])
* remove import of deprecated ActivityToolbox (see [http://git.sugarlabs.org/hello-world/mainline/commit/22060a3063b2d6fd38d6b1cd8d44946170255af3 hello-world])
* support for 'service_name' and 'class' has been removed from the activity.info make sure you are using: 'bundle_id' instead of 'service_name' and 'exec' instead of 'class' (see in [http://git.sugarlabs.org/record/mainline/commit/6e8968c71e474e2d8d86886badf5cf7d70217dc5 Record])
* support for 'service_name' and 'class' has been removed from the activity.info make sure you are using: 'bundle_id' instead of 'service_name' and 'exec' instead of 'class' (see in [http://git.sugarlabs.org/record/mainline/commit/6e8968c71e474e2d8d86886badf5cf7d70217dc5 Record])
Line 66: Line 19:
  import gtk
  import gtk
to
to
import gi
gi.require_version('Gtk', '3.0')
  from gi.repository import Gtk
  from gi.repository import Gtk


Remember to import the gi module and specify the Gtk version as 3.0 as well.
Note that require_version needs to called only the first time when Gtk is being imported.
<pre>
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk
</pre>


Here are some more examples of imports that may be used:  
Here are some more examples of imports that may be used:
<pre>
<pre>
from gi.repository import Gdk, Pango, Gobject
from gi.repository import Gdk, Pango, Gobject
Line 293: Line 243:
  GdkPixbuf.Pixbuf.new_from_file()
  GdkPixbuf.Pixbuf.new_from_file()


==Make a release==
==Releasing activities (for maintainers)==
===Versioning===
Once an activity is ported, a new release can be made. The major version should be greater than the existing one.
If you do new releases the versioning of the GTK2 and GTK3 release should be different. For GTK2 releases you should use dotted versions for new development releases major versions. Let's have a look at hello-world as an example. The latest release of hello-world was version 3. Bug fix releases should be named 3.1 then 3.2 and so on. The new releases for the new development branch should be starting with a major number, in the case of hello-world version 4.
 
To minimise the maintainer overload we highly encourage you to only do bug-fix releases for the GTK2 branch. New features should only go into the new branch that is based on gobject-introspection and GTK3.
 
Note that some older versions of Sugar don't know how to parse dotted version numbers. An alternative to the above is to simply ensure that the version number of the GTK3 branch is always greater than (>) the version number of the GTK2 version.
 
===GIT conventions===
We've agreed that the GTK3 version should be in the '''master''' branch on gitorious.sugarlabs.org. The GTK2 version should be in a branch called '''gtk2'''.


Some helpful git foo:
Please follow [https://github.com/sugarlabs/sugar-docs/blob/master/src/contributing.md#checklist---maintainer this] guide for releasing a new version


From your repository, first create the GTK2 branch with:
==Port to Python 3==
git branch gtk2
We are migrating towards Python 3. Python 3 does not support GTK+ 2. Hence, once the activity is ported to GTK+ 3, please also continue porting the activity from Python 2 to Python 3.


Then pull in all GTK3 changes on top of the master branch:
Ref: [https://github.com/sugarlabs/sugar-docs/blob/master/src/python-porting-guide.md Guide to port activities to Python 3]
git pull git://path/to/gtk3/repo
 
To move the gtk2 to gitorious.sugarlabs.org:
git checkout gtk2
git push -u origin gtk2


== Tips to Activity Developers ==
== Tips to Activity Developers ==
Line 516: Line 453:


== Resources ==
== Resources ==
* PyGtk documentation
PyGI Documentation: https://lazka.github.io/pgi-docs/
:: Gtk3: http://python-gtk-3-tutorial.readthedocs.org
 
:: gtk2: http://www.pygtk.org/docs/pygtk/
gtk2: http://www.pygtk.org/docs/pygtk/
* Reference Manual
* Reference Manual
:: Gtk3: http://developer.gnome.org/gtk3/3.4/
:: Gtk3: http://developer.gnome.org/gtk3/3.4/
Retrieved from "https://wiki.sugarlabs.org/go/Features/GTK3/Porting"