GEPS 029: GTK3-GObject introspection Conversion
GEPS Closed This GEPS (Gramps Enhancement Proposal) is closed and available in the version of Gramps indicated below. |
Implemented for the release of Gramps 4.0
Gramps was written with GTK 2 toolkit. This has been replaced upstream with GTK 3, so Gramps should convert to GTK 3.
Contents
- 1 Guideline
- 2 Documentation
- 3 Installation
- 4 Problems
- 5 Related Gramps Bugs
- 6 How to investigate a hard crash?
Guideline
We try to convert 1 to 1. If there are problems due to deprecated features, or otherwise, add in the code:
# TODO GTK3: write what problem is due to gtk 3 conversion
Before release, all TODO GTK3 in the code must be cleaned up
Documentation
Python GTK3 docs: [1]
Alternative is to look at the base C documentation, and understand from experience how the introspection works. Gnome docs: [2].
As python works with classes, it looks somewhat like the C++ interface: [3]. To investigate the specific override (how to init Gtk classes):
- python overrides: [4]
Furthermore, for the other gi libs:
Installation
Ubuntu 12.10 (Linux Mint 14)
On Ubuntu 12.10 (as of December 1, 2012), or Linux Mint 14 (as of December 24, 2012), you need only (replace python with python3 if you want to run the python 3 version!):
sudo apt-get install python-dev libglib2.0-dev libcairo2-dev sudo apt-get install python-cairo-dev python-gobject-dev libgirepository1.0-dev sudo apt-get install gir1.2-freedesktop python-gi python-gobject python-gi-cairo sudo apt-get install gir1.2-pango-1.0 libgtkspell-3-0 python-gtkspell sudo apt-get install python-pyicu
Old note The removal of python-gnome2 (and anything that relies on it) is necessary apparently because some "selectors" have not yet been converted. The right thing to do here is to fix the selectors rather than removing the package.'
You can also run Gramps 4.0+ in Python 3 first Install the Python BSDDB interface and check that it works
sudo apt-get install python3-bsddb3
You will probably want these optional packages:
sudo apt-get install python-pygoocanvas gir1.2-goocanvas-2.0-9
For additional functionality, install these:
sudo apt-get install python-pyexiv2
Ubuntu 12.04
For people on Ubuntu 12.04, you need:
1. add the gnome_shell repo to have the latest version of glib and friends, see how to add the ppa on: gnome_shell pppa Then upgrade your system via the system manager.
Note 1 : If you use Gnome3, also add the gnome3 ppa!
Note 2: this can make gnome shell unstable if the ppa is too bleeding edge!!
2. install version 3.3.2 of pygobject. No ppa for this, I use the git repo on gnome.org, so my git config:
[remote "origin"] fetch = +refs/heads/*:refs/remotes/origin/* url = http://git.gnome.org/browse/pygobject
So to install it to folder pygobject, do
git clone git://git.gnome.org/pygobject pygobject
Then checkout tag 3.3.2, so
cd pygobject git checkout 3.3.2
Make sure you have the dependencies installed, you will need:
- libglib2.0-dev package (otherwise you will obtain an error like undefined mqcro: AM_PATH_GLIB_2_0.
- autoconf, automake, libtool, intltool package
- python-dev package
- libcairo2-dev, python-cairo-dev
- python-gobject-dev
- libgirepository1.0-dev
So, use the line:
sudo apt-get install autoconf automake libtool python-dev libglib2.0-dev libcairo2-dev python-cairo-dev python-gobject-dev libgirepository1.0-dev
Then compile pygobject:
./autogen.sh make sudo make install
Now this installs to /usr/local, so to run the test with that, on ubuntu in your terminal:
PYTHONPATH=/usr/local/lib/python2.7/site-packages/ python gramps.py
If you then get:
$ PYTHONPATH=/usr/local/lib/python2.7/site-packages/ python src/gramps.py Gtk typelib not installed. Install Gnome Introspection, and pygobject version 3.3.2 or later. Gramps will terminate now.
You may need to:
export LD_LIBRARY_PATH=/usr/local/lib
Also, I had to get rid of the older gobject:
sudo rm -rf /usr/lib/python2.7/dist-packages/gobject
Debian Testing
As of 25 July 2012, the Debian repositories does not contain sufficiently up-to-date python GObject introspection packages and so need to be installed from the experimental repository, which currently contains version 3.4.2-2. Perhaps the simplest way to install is just to download the latest packages from the Debian packages web site. The files required can be found for different architectures at:
python-giError: Package not available in this suite.- python-gi-cairo
Install the package files with dpkg. eg
dpkg -i python-gi_3.4.2-2_i386.deb
GTK 3 theme
A GTK3 theme engine is required to make Gramps look visually more appealing.
- Try gtk3-engines-oxygen.
- install GTK Theme Preferences
If Gramps looks ugly in GTK 3, you probably are not using a GTK 3 theme. In that case, GTK falls back to the Raleigh theme.
The solution is to install a theme that comes with a GTK 3 theme. For example the Adwaita theme:
For a good dark theme, consider elementary-dark-theme, installable from [5]
- Elementary theme and warnings
If you see some warnings[6] by running Gramps with Elementary theme:
(Gramps.py:3359): Gtk-WARNING **: Theme parsing error: gtk-widgets.css:217:20: Not using units is deprecated. Assuming 'px'.
(Gramps.py:3359): Gtk-WARNING **: Theme parsing error: gtk-widgets.css:218:20: Not using units is deprecated. Assuming 'px'.
(Gramps.py:3359): Gtk-WARNING **: Theme parsing error: gtk-widgets.css:250:20: Not using units is deprecated. Assuming 'px'.
(Gramps.py:3359): Gtk-WARNING **: Theme parsing error: gtk-widgets.css:251:20: Not using units is deprecated. Assuming 'px'.
(Gramps.py:3359): Gtk-WARNING **: Theme parsing error: gtk-widgets.css:277:20: Not using units is deprecated. Assuming 'px'.
(Gramps.py:3359): Gtk-WARNING **: Theme parsing error: button.css:151:20: Not using units is deprecated. Assuming 'px'.
(Gramps.py:3359): Gtk-WARNING **: Theme parsing error: button.css:152:20: Not using units is deprecated. Assuming 'px'.
(Gramps.py:3359): Gtk-WARNING **: Theme parsing error: content-view.css:92:20: Not using units is deprecated. Assuming 'px'.
then the best solution is maybe to try to fix it by yourself,
/usr/share/themes/elementary/gtk-3.0/
GtkSwitch { - text-shadow: 0 1 alpha (#fff, 0.4); + text-shadow: 0 1px alpha (#fff, 0.4); - icon-shadow: 0 1 alpha (#fff, 0.4); + icon-shadow: 0 1px alpha (#fff, 0.4); ..
and to provide a patch for this theme!
http://bazaar.launchpad.net/~elementary-design/egtk/egtk-2a/files/head:/gtk-3.0/
KDE
To set the theme, open gramps, and open System settings -> Application Appearance -> GTK+ Appearance, and select different theme, click on apply. If you see Gramps update completely, you have selected a theme with GTK 3 support. If the theme falls back to something consisting of Raleigh theme components, the theme does not have good GTK 3 support. Even if Gramps updates, not all elements visible will update. Restart Gramps to be sure the theme works as intended. You can install gtk-theme-switch to test themes.
Spell Check Install
For working spell check, you need gtkspell3 3.0.
(In Ubuntu 12.10, the libgtkspell-3-0 package is not suitable [7] as it is API incompatible with the official release 3.0.0, released on 2012-11-12 )
If the package is not in your distributions packages, you need to compile the spell check. For this, obtain the GtkSpell3 3.0 or later source code, and extract the code to a directory, eg gtkspell3, and go into this directory using the terminal.
Before continuing, remove any old version of gtkspell v3 you might have installed before!
Now obtain the packages needed to compile this code.
Install the program 'hg' to get the code.
sudo apt-get install mercurial
Download the Gtkspell code with:
hg clone http://hg.code.sf.net/p/gtkspell/code gtkspell-code
You may need to install the following:
sudo apt-get install gtk-doc-tools libenchant-dev valac
You may also need gtk3 devel packages:
sudo apt-get install gtk+-3.0-dev
Now compile and install the code
./autogen.sh make sudo make install
Gramps now needs to find the gtkspell typelib and introspection lib. By copying the typelib to the correct location:
sudo cp /usr/local/lib/girepository-1.0/GtkSpell-3.0.typelib /usr/lib/girepository-1.0/
The lib can be found by path by setting the LD_LIBRARY_PATH environment variable. Hence, start Gramps as follows:
LD_LIBRARY_PATH=/usr/local/lib python Gramps.py
If you followed the guide above and compiled your own pygobject module, you need to start Gramps with the command
PYTHONPATH=/usr/local/lib/python2.7/site-packages/ LD_LIBRARY_PATH=/usr/local/lib python Gramps.py
Install your Dictionary
Note, dictionnaries provided by hunspell work fine and have unicode support.
If your language is missing from the list of dictionaries to spellcheck against you can install them.
eg: For Australian English:
sudo apt-get install myspell-en-au hunspell-en-au
You can check that the language installed correctly by running
enchant-lsmod -list-dicts
The result should list all the language dictionaries installed and include the one you installed eg: en_AU (myspell) en_AU (hunspell)
Old install method
we need a patched gtkspell version that supports gobject introspection. A working version is the changes branch at https://github.com/manisandro/gtkspell3/tree/changes. So one needs to install this version of gtkspell. The python-gtkspell code is then no longer needed, and can be removed. Source of this code is a sourceforge bug entry [8] and a redhat bug entry: [9]
Gramps supports this version since revision 20130.
First we install the git package to obtain the code:
sudo apt-get install git
Obtain the source code, and change to the version with gtk3 and gobject introspection support:
git clone git://github.com/manisandro/gtkspell3.git cd gtkspell3/ git checkout -b changes origin/changes
WebKit for Htmlrenderer
The htmlview requires WebKit. Introspection bindings for this is available, in Ubuntu package gir1.2-webkit-3.0
Developerwize, we need to replace size-request signal, see [10]
OsmGpsMap for Geography
The Geography requires osmgpsmap. Introspection bindings for this is not currently available, so you need to compile it from the repository listed below:
Or simply install from package (Linux Mint 18.2):
Libosmgpsmap-1.0-dev
Download from the home site
http://nzjrs.github.io/osm-gps-map/
Download the tar source and do :
tar zxvf osm-gps-map-1.0.1.tar.gz cd osm-gps-map-1.0.1
Download from github
You can also continue to use git to get the last development version :
git clone git://github.com/nzjrs/osm-gps-map.git cd osm-gps-map
As we can have some new patches, If you already have osm-gps-map and you want to get the last version, do :
git pull
How to compile osm-gps-map
You might have all your dependencies if you already compiled pygobject as explained above. For Ubuntu you still need packages libsoup2.4-dev and libsoup2.4
You may also need gtk3 and gobject-introspection devel packages:
sudo apt-get install gtk+-3.0-dev libgirepository1.0-dev checkinstall
and some other stuff like:
sudo apt-get install gnome-common gtk-doc-tools
Now compile osmgpsmap:
gnome-autogen.sh make sudo make install sudo cp /usr/local/lib/girepository-1.0/OsmGpsMap-1.0.typelib /usr/lib/girepository-1.0/
To use this now, you have to, or remove the installed version of osmgpsmap on your computer, or set the LD_LIBRARY_PATH to point at the installed version. Using the latter, you can start Gramps in trunk with:
LD_LIBRARY_PATH=/usr/local/lib PYTHONPATH=/usr/local/lib/python2.7/site-packages/ python Gramps.py
or
LD_LIBRARY_PATH=/usr/local/lib PYTHONPATH=/usr/local/lib/python2.7/site-packages/ python -c 'from gramps.grampsapp import main; main()'
First sets library to /usr/local/lib so as to find osmgpsmap and gtkspell, second /usr/local/lib/python2.7/site-packages/ to find the local install of pygobject
An easier way is to do it with checkinstall:
gnome-autogen.sh ./configure --prefix=/usr make sudo checkinstall make install
then you don't need all the path wizardry, and can later manage the package via the package management system
Ubuntu 14.04 - Trusty Tahr
The packages contained in the repository are too old (0.7.3) so use (1.0.2-1~ubuntu14.04.1) from the backports (universe) made available 2014-07-03. Or (Not recommended) You could download 1.0.x packages manually from the Utopic (14.10) proposed repository. https://launchpad.net/ubuntu/+source/osm-gps-map
sudo dpkg -i libosmgpsmap-1.0-0_1.0.2-1_amd64.deb sudo dpkg -i gir1.2-osmgpsmap-1.0_1.0.2-1_amd64.deb
GExiv2 for Image metadata
As at 9 Mar 2013 Fedora 18 only has a libgexiv2-0.4.1-3.fc18.i686.rpm. and version 0.5 (released October 2012) is needed in order to have the Python bindings for GExiv2.
The GExiv2 maintainer's homepage is: redmine.yorba.org/projects/gexiv2/wiki which points to the latest sources, and tells you how to compile it.
But to compile a Fedora 18 GExiv2 library, you need to have installed both exiv2-devel-0.23-3.fc18.i686.rpm and exiv2-libs-0.23-3.fc18.i686.rpm also. And you also need (unless you already have the /usr/bin/g-ir-scanner program) gobject-introspection-devel-1.34.2-1.fc18.i686.rpm too -- but that requires pkgconfig (which I already had) and also libffi-devel-3.0.10-3.fc18.i686.rpm for it to be happy.
The 0.5 GExiv2 sources are in www.yorba.org/download/gexiv2/0.5. There you can download "libgexiv2-0.5.0.tar.xz" (not .bz2 or .gz) -- which will again only be necessary if Fedora has not yet updated its official RPM (to 0.5).
Then, make a temporary directory and copy libgexiv2-0.5.0.tar.xz into it. Then "cd" into that directory and say "tar xpfJ libgexiv2-0.5.0.tar.xz". Then "cd" into the "libgexiv2-0.5.0" it made, and type:
./configure --enable-introspection --prefix=/usr make
(with the "/usr" being needed to override the "/usr/local" default)
Then say (as root):
make install
Since I already had Python3 installed on that F18, along with the Python2 which came with the F18, the "make install" put GExiv2.py into both the python2.7 and python3.3 site-packages/gi/overrides directories, thus enabling it on both. If you only have one Python it will put it only there.
As a test, in both (for me) "python" and "python3" say:
from gi.repository import GExiv2
Let's not tell users that they should install self-built software into /usr. They shouldn't, and neither should you. Either /usr/local or /opt are better choices and more-or-less standard practice. To make the library findable one should either add the directory of choice to /etc/ld.so.conf and run ldconfig(8) or add it to $LD_LIBRARY_PATH in one's profile.
FWIW it seems a bit simpler with Linux Mint Debian Update 6
(Cinnamon)
libexiv, etc, etc............. are already installed or can be installed via synaptic.
Then
git clone git://git.yorba.org/gexiv2" to get gexiv2 0.5;
going into gexiv2/ and running
./configure --enable-introspection make (as root) make install"
installs in usr/local And
python3 from gi.repository import GExiv2"
tests OK.
Ubuntu 14.04 - Trusty Tahr
On Ubuntu 14.04 it is a lot easier. According to the Gramps-devel mailing list you can simply install:
sudo apt-get install gir1.2-gexiv2-0.10
You can verify that everything is correct by executing the following command:
python -c "from gi.repository import GExiv2"
No errors should be displayed.
Problems
If anyone files a bug against PyGobject, Gtk or any of the Gtk dependencies (except Cairo, which isn't part of Gnome), please add John (the address bugzilla has is [email protected]) to the CC list at the bottom of the bug report page or post the bug URI to the gramps-devel list.
Open
- Geography : missing tiles : osm-gps-map problem. issue:??
(Gramps.py:4515): OsmGpsMap-WARNING **: Error getting missing tile
- Geography : for all other problems, use last version with git pull. (file issues on the bugtracker)
Solved or workaround
- there are some drag and drop issues: [11], [12]. Solved: Use set_target_list functions for drag and drop with a created TargetList.
- error in list_families on textview in styledtexteditor: [13]. Workaround: we use a global function that calls this once as workaround. There is a fix upstream.
- str and unicode no longer seem to work, the encoding must be passed too; Future: deprecate unicode() in the code, as we want to support python 3' - SOLVED FOR NOW: added reload(sys) in gramps.py and set encoding to utf-8. Is there a better way that is userfriendly?
- there is no longer automatic conversion to str utf-8 when using GTK functions, we must convert before passing to GTK.
- glade can no longer work with our catalog. We need to upgrade comboboxentry to combobox with has_entry manually, and hope editors keep working... - Solved: Although our catalog cannot be opened, we can use glade with undefined elements without issues.
- menu.popup does not seem to work in some instances. Solved: Make sure the reference to menu survives, so eg, do self.menu= function, then self.menu.popup. Alternatively, passing position function seems to also work as workaround, see grampsbar.py for example
- Many Gtk elements no longer grab certain events. Solved: Add a Gtk.EventBox under them to grab the event.
- Geography : bad placement of markers : osm-gps-map problem. Solved : git pull the latest version. Need to be acknowledge by osm-gps-map team.
- Geography : We cannot mix osmgpsmap between trunk and gramps34 and others. Solved : git pull the latest version. You must remove all libosmgps* from /usr/local/lib before make install
- osmgpsmap is GTK2. There is a GTK3 branch in git, we should try it, and contribute to the conversion. In Progress: Geography really minimalist : no menu, no markers, ... Solved GTK3 available
- pyexiv2 module causes a segmentation fault when exiting Gramps - see bug #6042 - resolved
- python-gnome2 package causes a segmentation fault when Gramps starts - see bug #5972 - resolved
TypeError: Error when calling the metaclass bases metaclass conflict: the metaclass of a derived class must be a (non-strict) subclass of the metaclasses of all its bases
- Gtk.ColorSelectionDialog has no more colorsel attribute : it's replaced by get_color_selection() - see bug #6917 - resolved
- We cannot set strings in struct, see GTK bug [14] It seems we can do without this, so not an issue at the moment (upstream bug shows: RESOLVED FIXED 2013-01-11)
- No rows_reordered function on treemodels in python, see GTK bug [15]. Current fix: disconnect and reconnect the model so sort need not emit rows-reordered signal. However, this means the history of expand collapse of nodes in a treeview is lost after rows have been reordered (this happens in gramps on click on the column that is already sorted. (upstream bug shows: RESOLVED FIXED 2013-07-22)
- GraphView : GooCanvas and dash lines : https://bugzilla.gnome.org/show_bug.cgi?id=703592 (upstream bug shows: RESOLVED FIXED 2013-11-02)
Related Gramps Bugs
- #5009: Use gobject introspection for GTK 3 dependency
How to investigate a hard crash?
With GTK 3, hard crashes are a lot more likely than before. Very troubling for a python developer, as you do not know where the crash happens. So, to investigate these, do the following.
First install python with debug symbols, in Ubuntu:
sudo apt-get install python-dbg
Now, you can start python with gdb
$ > gdb python (gdb) set env GRAMPSCODE /path/to/code/gramps/src (gdb) set env PYTHONPATH $PYTHONPATH:$GRAMPSHOME:/usr/local/lib/python2.7/site-packages/ (gdb) r $GRAMPSCODE/gramps.py ...after the crash... (gdb) bt
This works best if you have the debug symbols installed for everything relevant, or are running from a self-built tree built with debugging CFLAGS (-g -O0). At a minimum, in addition to Python itself, you'll need symbols for Gtk+ (libgtk-3.0.so and libgdk-3.0.so), PyGObject, and GLib.
To see the python stack:
(gdb) pystack
This works with gdb7 as-is; for earlier versions, you need to install gdbinit as .gdbinit in your home directory before starting gdb. On some systems (MacOS X in particular), the structure PyStringObject isn't exported in the debug symbols, so if you get the error
No symbol "PyStringObject" in current context.
then you need to tell gdb
add-symbol-file /path/to/Python-build-dir/Objects/stringobject.o
which will be possible only if you've built Python from source.