Difference between revisions of "Getting started with Gramps development"

From Gramps
Jump to: navigation, search
(other: Added link to extant file information page.)
(Optional : set up a development environment)
Line 11: Line 11:
 
= Set up your environment =
 
= Set up your environment =
 
== Optional : set up a development environment ==
 
== Optional : set up a development environment ==
I highly recommend that you do not use your usual environment for developing GRAMPS. Doing so may result in data loss in your GRAMPS database !
+
I highly recommend that you do not use your usual environment for developing GRAMPS. Defenitely 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 you usual user, it will access to your usual GRAMPS database and a bug may result in losing productive data. Here are some options you may choose to prevent this. If you have enough resources, I recommend using VirtualBox.
+
If you run your development version of GRAMPS as the usual user, it will show all your usual GRAMPS fmily trees, so loading one by mistaken is possible and a bug may result in losing productive data.  
 +
 
 +
Here are some options you may choose to prevent this. If you have enough resources, I recommend using VirtualBox.  
 +
 
 
=== VirtualBox ===
 
=== VirtualBox ===
 
[http://www.virtualbox.org/ VirtualBox] is an opensource 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 favourite Linux distribution and start hacking GRAMPS in a full separated environment.
 
[http://www.virtualbox.org/ VirtualBox] is an opensource 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 favourite Linux distribution and start hacking GRAMPS in a full separated environment.
Line 18: Line 21:
 
You may also use a chroot to result in a similar separation as virtualbox. If you use a chroot for developping GRAMPS, please add informations here.
 
You may also use a chroot to result in a similar separation as virtualbox. If you use a chroot for developping GRAMPS, please add informations here.
 
=== Another user ===
 
=== Another user ===
You may also simply do you development as another user, so you won't access to your usual ~/.gramps database when testing.
+
You may also simply do your development as another user, so you won't access to your usual ~/.gramps database when testing.
 +
 
 +
=== 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 ==
 
== Get the source tree ==

Revision as of 07:07, 1 September 2008


Warning : this tutorial is work under progress. Feel free to help and modify it


Introduction

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.

Set up your environment

Optional : set up a development environment

I highly recommend that you do not use your usual environment for developing GRAMPS. Defenitely 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 fmily trees, so loading one by mistaken is possible and a bug may result in losing productive data.

Here are some options you may choose to prevent this. If you have enough resources, I recommend using VirtualBox.

VirtualBox

VirtualBox is an opensource 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 favourite Linux distribution and start hacking GRAMPS in a full separated environment.

Chroot

You may also use a chroot to result in a similar separation as virtualbox. If you use a chroot for developping GRAMPS, please add informations here.

Another user

You may also simply do your development as another user, so you won't access to your usual ~/.gramps database when testing.

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

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.

Install an Edior

Geany

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 !

Eclispe + 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 !

Other

"Kate" works well as a general editor for Python. It also recognises key words of Python and marks them in colours. Of course, "Idle" is a handy simple editor that takes advantage of the interpreter features of Python. Often Idle comes with Python packages. "Eric" is another widely used, fully featured editor for Python. Idle works well in Linux and other OS's, including the "dominant OS".

(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

Browse the source code

data

You will find here various data files used by gramps : manpages, icons...

src

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.

src/gen

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)

other

  • 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/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/Models
  • src/plugins
  • src/PluginUtils
  • src/ReportBase
  • src/Selectors
  • src/Simple
  • src/test
  • src/widgets

Further information about files can be found in GEPS_008.