Getting started with Gramps development
This tutorial is work in progress. Feel free to help and modify it.
This tutorial aims to help you in your first hacking of GRAMPS. It will help you setting up a development environment and explain where to find the files you need.
This tutorial assumes that you are using GNU/Linux (but it might help under another OS) and that you know the basics of Python programming language.
- 1 Set up your environment
- 1.1 Optional : set up a development environment
- 1.2 Get the source tree
- 1.3 Install a text editor
- 1.4 Run GRAMPS from the source
- 2 Browse the source code
Set up your environment
Optional : set up a development environment
I highly recommend that you do not use your usual environment for developing GRAMPS. Definitely do not work on your main GRAMPS family tree. Doing so may result in data loss in your GRAMPS Family Tree !
If you run your development version of GRAMPS as the usual user, it will show all your usual GRAMPS family trees, so loading one by mistake is possible and a bug may result in losing productive data. To prevent this, you could use a GRAMPSHOME environment variable to create a separate folder for productive data, see Run GRAMPS from a portable drive for more information.
Here are some options you may choose to prevent this. If you have enough resources, I recommend using VirtualBox.
VirtualBox is an open source virtualisation solution. Install it, run it and you have a virtual PC in your PC. Network connection works out of the box without extra configuration needed. Install your favorite Linux distribution and start hacking GRAMPS in a full separated environment.
You may also use a chroot to result in a similar separation as virtualbox.
If you use Ubuntu, you can set up the chroot environment following these instructions: Creating a basic Ubuntu chroot If you use GRAMPS in a chroot jail with another Linux distribution, please add information here.
You should then have a working chroot environment in /var/chroot (or whichever location you chose). Enter it with
sudo chroot /var/chroot
This means that within this directory, applications cannot access files without the chroot jail, i.e. your GRAMPS install within the directory cannot destroy another install of GRAMPS in your usual home directory.
From a shell within your chroot directory, just svn-checkout the GRAMPS trunk into the chroot folder as usual. Please note that before running the autogen-Script for generating makefiles, you may need to get some packages:
apt-get python intltools libglib2.0-dev gedit
You may also simply do your development as another user, so you won't access your usual ~/.gramps database when testing.
You can also create an alias account with the same user and group IDs, but with a different login name and different home directory, typically, a subdir of the real user's home directory. This gives the benefit of less disk usage, and no permission boundary between the two account aliases. On the other hand, if you are afraid of malicious code within gramps purposefully breaking out and wreaking havoc on your real home account's .gramps, this method is too weak for you. For regular development scenario, though, this setup certainly does suffice.
This is what the cloning looks like in my /etc/passwd:
vassilii:x:1000:1000:Vassilii Khachaturov,,,:/home/vassilii:/bin/bash v:x:1000:1000:Vassilii Khachaturov,,,:/home/vassilii/pub:/bin/bash
Create symlink to the dotfiles you want to reuse. Obviously, don't do this for .gramps! Something like (inside ~vassilii/pub):
ln -s ../.bashrc ../.mozilla ../.ratpoisonrc .
You can use the alias account in a standalone matter (X session under it), or just inside a terminal window (su - <name of the alias account>). All the build, install, and test run of gramps should be done under this account. This will preserve your normal account's .gramps.
Having obtained the gramps source tree, as the first build step, do
./autogen.sh -- --prefix=/home/vassilii/pub/local
(replace /home/vassilii/pub/ with the actual aliased home directory!!!)
After you build and install (no root needed! you install under the local prefix), check that the right (locally built) gramps is on your PATH. Tweak your shell profiles as needed.
None of above
You have been warned! At a minimum name your test family trees 'a_test_name'. By starting with 'a_test' they show at the top of the family tree manager, and the test makes it clear what they are for.
Get the source tree
To get the source tree, you will need SVN. Please have a look at the dedicated tutorial Brief introduction to SVN for details on getting the source trees for the latest current stable branch and the development trunk.
You can also use a graphical SVN manager like "kdesvn" or "SVN Workbench".
This tutorial now assumes you have downloaded GRAMPS' trunk into "~/gramps-trunk". If not, you have to change this path when it is used below.
Let it be clear that the settings directory "~/.gramps/" is a different hidden directory in your home-dir. Do not store anything there.
Install a text editor
The following is in alphabetic order. Choose the one you like. Whichever editor you use, make sure that it is set up so that the indent level is 4 spaces. Do not use the Tab character to indent.
Eclipse + pydev
Eclipse with pydev brings an integrated IDE for Python. To run it, you have to do a few steps configuration.
First, you have to set the path to your python interpreter. Go in the menu "Window"->"Preferences...", then choose "Pydev"->"Interpreter - Python". With "new", you can create a link to "/usr/bin/python2.5". there you are.
Next, you have to set up a pydev project. Go in the menu "File" -> "New" -> "Project", and choose a Pydev projet. Project name could be "GRAMPS trunk", uncheck "Use defaults" and choose "~/gramps-trunk" as the project directory. Project type is "Python 2.5", and then you can press "Finish". You are now ready to start coding !
PyCharm is more powerful and out-of-the-box than Eclipse with pydev, although it is not Free Software like Eclipse is. Seems to be recognizing more Python syntax and feels faster on my box. I unpacked the distribution, launched bin/pycharm.sh script, and it just worked. 'File » Open Directory' and selected the "trunk/src" directory in my local checked out SVN WD, and things work from there.
'Version Control » Update Project' automatically syncs up with the svn (which it picks up from the .svn directories, unlike Eclipse+pydev that dumbly shows the .svn directories for me and keeps complaining on things going out of sync).
Some free software projects qualify for a Jetbrains free pycharm usage licences. We have applied for one to use in GRAMPS development, and currently GRAMPS has been awarded such a license -- as a consequence of the GRAMPS distribution terms (GPL). Here's what you should do to get a copy (and use it for GRAMPS development only, not for other work, under this license!), according to Benny:
1/ be a gramps developer with commit rights to our repository 2/ write Vassilii with your sourceforge login name and ask him for the license key 3/ keep the license private. We do OSS software so I assume we are all against software piracy.
If you don't have commit rights, you can still use pycharm for 30 day trial period.
Emacs or Vim
Experienced Unix-like users and developers will often use one of these editors. They're available with virtually all distributions of modern Unix-like systems.
Eric4 is a python editor. It has everything you need (code completion, python shell, ...)
Geany is a nice development Editor. One feature I like is that it will automaticly recognise python code and list Symbols in a side bar, allowing to jump quickly in your code.
Install it and you can start coding !
SPE or Stani's python editor, is a python editor. It is somewhat more powerfull than Erik4 (quick access to code fragments, extensive search, ...) but can be unstable on some setups. Try it to know.
Scribes is a text editor written in python and Gtk, that uniquely blends simplicity with well researched powerful functions.
"Kate" works well as a general editor for Python. It also recognises key words of Python and marks them in colours. Kate is a Linux KDE desktop program. Of course, it also works on gnome installations.
"Idle" is a handy simple editor that takes advantage of the interpreter features of Python. Often Idle comes with Python packages. Idle works well in Linux and other OS's, including the "dominant OS". If you install Windows version of Python, you will probably install from the same package Idle. One feature of Idle tends to confuse newcomers: Idle main window is NOT used for program writing, but for displaying the results. Notice that there is a Python tutorial, automagically installed with Idle on a Windows box. It is worth noting that the Tutorial gives quite extensive introduction into Python and is authored by the originator of Python Guido van Rossum.
(If you have a favourite Editor and want to share it : describe how to set it up here.)
Run GRAMPS from the source
To test that you did all well, you may want to run GRAMPS from your downloaded svn tree. This is explained in the Brief introduction to SVN but here are the quick steps :
cd ~/gramps-trunk ./autogen.sh make python src/gramps.py
These lines will not work before you have installed some build-dependencies. On Debian, just run (as root):
apt-get build-dep gramps
On Fedora 8 - 10, you will need:
yum install gnome-common intltool glib2-devel gnome-doc-utils gcc emacs gettext subversion make rcs
Browse the source code
You will find here various data files used by gramps : manpages, icons...
In this folder, you will find GRAMPS' source code. There are a lot of subfolders, which are explained in the folowing sections.
In most folders, there is an __init.py__ file. You may find some explanations there about the package.
This is GRAMPS' core. It defines database classes (Person, Place, Note...), database access :
- src/gen/db : GRAMPS Database Handling
- src/gen/lib : The core library of GRAMPS objects
- src/gen/proxy : Proxy class for the GRAMPS databases. This is a very powerful tool used to propose a filtered view of the database : Objects which are not marked private, (not) living persons...
- src/gen/utils : Common utilities for GRAMPS code (progess monitor dialog, database utilities, callbacks between UI and database code)
- src/BasicUtils : Basic functions to be called from other Gramps code
- src/Config : This package implements access to GRAMPS configuration. It provides the choice between different storage backends.
- src/data : Data for Gramps (What is the difference with the root data folder ?)
- src/DataViews : Gramps Main Views (PersonView, FamilyList...)
- src/DateHandler : Class handling language-specific selection for date parser and displayer.
- src/DisplayModels : ??
- src/DisplayTabs : ??
- src/docgen: Gramps Document Generator (for reports)
- src/Editors: Editors for the different Gramps Objects (Person, Place...)
- src/FilterEditor: Filter Editor
- src/Filters: Package providing filtering framework for GRAMPS
- src/glade: UI designed with glade. There are few UIs designed with glades. I suppose the other are hard-coded.
- src/glade/catalog/README will give you tips on how to run glade tuned to Gramps source locations and using the proper preferences compatible with Gramps code base.
- src/GrampsDbUtils: This package implements additions to the the GrampsDb database.
- src/GrampsLocale: locale workaround for some OSes
- src/GrampsLogger: This package implements some extensions to the standard Python logging module that support a consistent logging and bug reporting framework for Gramps.
- src/images: images for Gramps.
- src/Merge: Merge functions
- src/Mime: Mime types handling
- src/Simple: Provides a simplified database access interface to the Gramps database.
Further information about files can be found in GEPS 008: File Organization. Please note that GEPS 008 is a change proposal and does not reflect the actual source tree.