Difference between revisions of "Getting started with Gramps development"

From Gramps
Jump to: navigation, search
m (Option 2: use the build code: svn)
m
 
(70 intermediate revisions by 12 users not shown)
Line 1: Line 1:
{{man warn|Warning:|This tutorial is work in progress. Feel free to help and modify it.}}
+
{{man tip|The article is about setting up for full-scale development of the Gramps core program|For information about developing on a smaller scale visit:
 
+
* [https://gramps.discourse.group/tag/hacks Specific Hacking discussions] 
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.
+
* Tools for developing at a micro scale: [[Addon:Isotammi_addons#SuperTool|SuperTool]], [[Addon:Python_Shell_Gramplet|Python Shell]]
 +
* [[Report-writing tutorial]]
 +
* [[Addons_development|Addons development]]
 +
<br />For how to use the Gramps program or install addons visit:
 +
* [[Portal:Using Gramps]]
 +
* [[Third-party Addons]]}}
 +
{{man warn|Warning:|This tutorial is a work in progress. Feel free to help and modify it.}}
 +
{{stub}}
 +
This tutorial aims to help you get started initially with Gramps development and shows you a general overview of what you need to know when working with the Gramps source code. The following will help you setup 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.
 
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 =
 
= Set up your environment =
== Optional : set up a development environment ==
+
== Linux: Optional : set up a development environment ==
  
{{man warn|Warning:|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 !}}
+
{{man warn|Warning:It is highly recommended that you do not use your normal/usual environment for developing Gramps.|Definitely do '''not''' work on your main Gramps family tree.<br />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.
+
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.  
 
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 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.
+
[https://www.virtualbox.org/ 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 fully separated environment.
  
 
=== Chroot ===
 
=== Chroot ===
You may also use a chroot to result in a similar separation as virtualbox.  
+
You may also use a [https://wikipedia.org/wiki/Chroot <code>chroot</code>] to result in a similar separation as virtualbox.  
  
 
If you use Ubuntu, you can set up the chroot environment following these instructions:
 
If you use Ubuntu, you can set up the chroot environment following these instructions:
 
[https://help.ubuntu.com/community/BasicChroot Creating a basic Ubuntu chroot]
 
[https://help.ubuntu.com/community/BasicChroot 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).
+
If you use Gramps in a chroot jail with another Linux distribution, please add information here.
 +
{{stub}}
 +
 
 +
You should then have a working chroot environment in <code>/var/chroot</code> (or whichever location you chose).
 
Enter it with  
 
Enter it with  
 
  sudo chroot /var/chroot  
 
  sudo chroot /var/chroot  
 
This means that within this directory, applications cannot access files without the chroot jail,  
 
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.
+
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.
+
From a shell within your chroot directory, just clone the Git repository into the chroot folder as usual.
 
Please note that before running the autogen-Script for generating makefiles, you may need to get some packages:  
 
Please note that before running the autogen-Script for generating makefiles, you may need to get some packages:  
 
  apt-get install python intltool libglib2.0-dev gedit
 
  apt-get install python intltool libglib2.0-dev gedit
  
 
=== Another user ===
 
=== Another user ===
You may also simply do your development as another user, so you won't access your usual ~/.gramps database when testing.
+
You may also simply do your development as another user, so you won't access your usual <code>~/.gramps</code> 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.  
+
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 <code>.gramps</code>, this method is too weak for you. For regular development scenario, though, this setup certainly does suffice.
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:
+
This is what the cloning looks like in my <code>/etc/passwd</code>:
 
  vassilii:x:1000:1000:Vassilii Khachaturov,,,:/home/vassilii:/bin/bash
 
  vassilii:x:1000:1000:Vassilii Khachaturov,,,:/home/vassilii:/bin/bash
 
  v:x:1000:1000:Vassilii Khachaturov,,,:/home/vassilii/pub:/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):
+
Create symlink to the dotfiles you want to reuse. Obviously, don't do this for ''<code>.gramps</code>''! Something like (inside <code>~vassilii/pub</code>):
  ln -s ../.bashrc ../.mozilla ../.ratpoisonrc .
+
  ln -s ../.bashrc ../.mozilla ../.ratpoisonrc ../.gitconfig .
  
 
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.  
 
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.  
Line 56: Line 65:
  
 
=== None of above ===
 
=== 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.
+
{{man warn|You have been warned!|At a minimum:
 
+
* [[How to make a backup|Make a Gramps XML Backup]]
[[Category:Developers/General|G]]
+
* Prefix the name of your test family trees '<code>a_test</code>' eg:'<code>a_test_FamilyTreeName</code>'. By starting with <code>'a_test'</code> they will show at the top of the {{man label|Family Tree}} manager, and the word '''test''' makes it clear what they are created for.}}
  
 
== Mac OS X ==
 
== Mac OS X ==
In order to develop (or even use) Gramps on an Apple Macintosh, you must first install all of the prerequisite libraries and their headers. There are three choices for this [http://live.gnome.org/Gtk%2BOSX Gtk-OSX], [http://www.macports.org MacPorts], or [http://www.finkproject.org Fink]. Full instructions for building Gramps for each is provided here: [[Mac OS X:Build from source:Application package]], [[Mac OS X:Build from source:MacPorts]], or [[Mac OS X:Build from source:fink]].
+
In order to develop (or even use) Gramps on an Apple Macintosh, you must first install all of the prerequisite libraries and their headers. There are three choices for this:
The last only works with X11, which is no longer included in OS X but can be installed separately. MacPorts can be built with/for either X11 or OS X's native Quartz graphics backend, and Gtk-OSX is exclusively for Quartz.  
+
# [http://live.gnome.org/Gtk%2BOSX Gtk-OSX],
 +
# [http://www.macports.org MacPorts], or  
 +
# [http://www.finkproject.org Fink].  
  
== Get the source tree ==
+
Full instructions for building Gramps for each is provided here:
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 could use [[Git]] rather than subversion if you prefer.)
+
# [[Mac OS X:Build from source:Application package]],
 +
# [[Mac OS X:Build from source:MacPorts]], or
 +
# [[Mac OS X:Build from source:fink]].
  
You can also use a graphical SVN manager like "kdesvn" or "SVN Workbench".
+
The last only works with X11, which is no longer included in OS X but can be installed separately. MacPorts can be built with/for either X11 or OS X's native Quartz graphics backend, and Gtk-OSX is exclusively for Quartz.
  
'''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.'''
+
== Windows ==
 +
In order to develop (or even use) Gramps on Windows, you must first install a development environment and all of the prerequisite libraries and their headers.
 +
[[Gramps_for_Windows_with_MSYS2]]
  
{{man warn|Warning:|Let it be clear that the settings directory "~/.gramps/" is a '''different''' hidden directory in your home-dir. Do not store anything there.''}}
+
Full instructions for building Gramps is provided here:
 +
[[Building_Gramps_AIO_cx_freeze-based]]
 +
== Install a text editor ==
 +
{{man tip|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.}}
  
== Install a text editor ==
+
Choose the text editor you like to work with. If your favourite text Editor is not listed you can add it and describe how to set it up here.
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 + PyDev ===
Eclipse with pydev brings an integrated IDE for Python. To run it, you have to do a few steps configuration.
+
[http://www.eclipse.org/downloads/ Eclipse] with [http://www.pydev.org/manual_101_install.html 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.
+
* First, you have to set the path to your python interpreter:
 +
** Go in the menu '''Window > Preferences...''';
 +
** Then choose '''PyDev > Interpreters > Python Interpreter'''.
 +
** Click '''New...''' to create a link to your Python executable (for example ''/usr/bin/python3.5'').
  
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.6", and then you can press "Finish". You are now ready to start coding !
+
* Next, you have to set up a PyDev project:
 +
** Go in the menu '''File > New > Project...''';
 +
** Choose '''PyDev Project'''
 +
** Project name could be ''Gramps''
 +
** Uncheck '''Use defaults''' and choose '''~/gramps-master''' as the project directory.
 +
** Project type is '''Python 3.5'''
 +
** Interpreter is the one you created at the first step above
 +
** And then you can press '''Finish'''.
  
=== pycharm ===
+
You are now ready to start coding!
[http://www.jetbrains.com/pycharm/ 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).
+
=== PyCharm ===
 +
[https://www.jetbrains.com/pycharm/ PyCharm] is not Free Software like Eclipse is. But 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 "Gramps/src" directory in my local checked out Git WD, and things work from there.  
  
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 [[User:Bmcage|Benny]]:
+
'Version Control » Update Project' automatically syncs up with the Git repository.
1/ be a gramps developer with commit rights to our repository
 
2/ write [[User:BACbKA|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 ===
 
=== 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.
 
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 ===
+
=== The Eric Python IDE  ===
[http://eric-ide.python-projects.org/index.html Eric4] is a python editor. It has everything you need (code completion, python shell, ...)
+
[https://eric-ide.python-projects.org/ Eric] is a python editor. It has everything you need (code completion, python shell, ...)
  
 
=== Geany ===
 
=== Geany ===
[http://www.geany.org/ 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.
+
[https://www.geany.org/ Geany] is a nice development Editor. One feature I like is that it will automatically recognise python code and list Symbols in a side bar, allowing to jump quickly in your code.
 +
 
 
Install it and you can start coding !
 
Install it and you can start coding !
  
Note, you can also get [http://wiki.geany.org/howtos/pydocw instant documentation for python modules].
+
Note, you can also get [https://wiki.geany.org/howtos/pydocw instant documentation for python modules].
  
 
=== SPE ===
 
=== SPE ===
[http://pythonide.stani.be/ 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.
+
[http://pythonide.stani.be/ SPE] or Stani's python editor, is a python editor. It is somewhat more powerfull than Eric (quick access to code fragments, extensive search, ...) but can be unstable on some setups. Try it to know.
  
 
=== Scribes ===
 
=== Scribes ===
[http://scribes.sourceforge.net Scribes] is a text editor written in python and Gtk, that uniquely blends simplicity with well researched powerful functions.
+
[http://scribes.sourceforge.net/ Scribes] is a text editor written in python and Gtk, that uniquely blends simplicity with well researched powerful functions.
  
=== Other ===
+
===Kate===
 +
[https://kate-editor.org/ Kate] works well as a general editor for Python. It also recognizes key words of Python and marks them in colours. Kate is a Linux KDE desktop program.  Of course, it also works on gnome installations.
  
[http://kate-editor.org/ Kate] works well as a general editor for Python. It also recognizes 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===
 +
'''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.
  
"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.
+
== Get the source tree ==
 +
To get the source tree, you will need Git. Please read the dedicated tutorial [[Brief introduction to Git]] for details.
  
(If you have a favourite Editor and want to share it : describe how to set it up here.)
+
You can also use a graphical Git tool like "[https://git-scm.com/docs/gitk/ gitk (The Git repository browser)]" or "[https://git-scm.com/docs/git-gui/ git-gui ( A portable graphical interface to Git)]".
  
== Run GRAMPS from the source ==
+
'''This tutorial now assumes you have cloned the Gramps repository into a directory called <code>~/Gramps</code>. If not, you have to change this path when it is used below.'''
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
 
python setup.py build
 
  
For the internationalization piece to work, you need to have the translation tools. You obviously also need subversion and friends. On Debian, just run (as root) - ('''Only if Debian installs Gramps 4.0+ as Gramps version!):
+
{{man warn|Warning:|Let it be clear that the settings directory <code>~/.gramps/</code> is a '''different''' hidden directory in your home-dir. Do not store anything there.''}}
apt-get build-dep gramps
 
  
On Fedora 8 - 10 (Fedora is up to version 17 now so does this still apply?), you will need:
+
== Run Gramps from the source ==
yum install intltool gettext subversion rcs
+
To test that you did all well, you may want to run Gramps from your downloaded Git tree. This is explained in the [[Running a development version of Gramps]]; here are the quick steps:
  
=== Option 1: run from source repo ===
+
For the internationalization code to work, you need to have the translation tools.
Here, we use the code in gramps-trunk to run Gramps. This means that compiled python files will be stored there. This is not ideal, but the easiest way to develop Gramps, as changes are immediately picked up by the code.
 
  
Copy the const.py file created in build to your source directory if you want to use your source directory to work with Gramps:
+
On Debian, just run (as root) - ('''Only if Debian installs Gramps 4.0+ as Gramps version!):
  cp build/lib.linux-x86_64-2.7/gramps/gen/const.py gramps/gen/const.py
+
  apt-get build-dep gramps
python Gramps.py
 
  
That is it. If you installed some dependencies of Gramps in non-default positions, you need to indicate with PYTHONPATH where then can be found, and with LD_LIBRARY_PATH where link libraries can be found. Eg, if you install GTK and spell checking from source too, you will need something like:
+
On Fedora 20+, you will need:
  PYTHONPATH=/usr/local/lib/python2.7/site-packages/ LD_LIBRARY_PATH=/usr/local/lib python Gramps.py
+
yum install intltool gettext git-core rcs
  
=== Option 2: use the build code (SVN)===
+
Build Gramps with:
Here, we use the code build in gramps-trunk/build to run Gramps. For this, do
+
cd ~/Gramps
  cd ~/gramps-trunk/build/lib.linux-x86_64-2.7/
+
python setup.py build
  python -c 'from gramps.grampsapp import main; main()'
 
  
Again, it might be needed to set with PYTHONPATH where dependencies can be found, and with LD_LIBRARY_PATH link libraries, see option 1.
+
To run Gramps, type:
 
+
python Gramps.py
If you point your PYTHONPATH to the build directory, you can actually run Gramps from a random directory. Like this:
 
  
cd
+
Dependencies
PYTHONPATH=~/gramps-trunk/build/lib.linux-x86_64-2.7/ python -c 'from gramps.grampsapp import main; main()'
 
  
So, more general:
+
If you have an "GExiv2 Module Not Loaded" you should install it with
cd
+
  sudo apt install gir1.2-gexiv2-0.10
  PYTHONPATH=~/gramps-trunk/build/lib.linux-x86_64-2.7/:/usr/local/lib/python2.7/site-packages/ LD_LIBRARY_PATH=/usr/local/lib  python -c 'from gramps.grampsapp import main; main()'
+
The same for the "osmGpsMap module not loaded, Geography functionality will not be available"
 
+
  sudo apt install gir1.2-osmgpsmap-1.0
If the build directory is in your PYTHONPATH, you can also just execute the grampsapp.py module. So this will work too:
 
  cd ~/gramps-trunk/build/lib.linux-x86_64-2.7/gramps
 
PYTHONPATH=~/gramps-trunk/build/lib.linux-x86_64-2.7/ python grampsapp.py
 
 
 
or again more generally
 
PYTHONPATH=~/gramps-trunk/build/lib.linux-x86_64-2.7/:/usr/local/lib/python2.7/site-packages/ LD_LIBRARY_PATH=/usr/local/lib python grampsapp.py
 
 
 
'''Note''': at the time of writing, only the last, so using grampsapp.py works, as not all imports in Gramps have been converted to relative or absolute imports. This conversion will be finished by end of 2012 however.
 
  
 
== Correct Translation in development ==
 
== Correct Translation in development ==
  
'''To check if following is still current!'''
+
{{man warn|'''To be checked if following is still current!'''}}
 +
{{stub}}
 
Warning: you will not be able to load translations on /usr/local/share/locale, because you will load /usr/share/locale, which could be translations for stable release (set on grampsapp.py).
 
Warning: you will not be able to load translations on /usr/local/share/locale, because you will load /usr/share/locale, which could be translations for stable release (set on grampsapp.py).
 
You may generate a custom launcher by adding this line:
 
You may generate a custom launcher by adding this line:
Line 178: Line 189:
 
= Browse the source code =
 
= Browse the source code =
  
== data ==
+
* For further information see: [[Gramps 4.x File Organization|Gramps 4.x File Layout Organization]]
You will find here various data files used by gramps : manpages, icons...
 
 
 
== gramps ==
 
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.
 
 
 
=== gramps/gen ===
 
This is Gramps' core. It defines genealogy objects (Person, Place, Note...), database classes, generic plugins, and database access :
 
* '''gramps/gen/db''' : GRAMPS Database Handling
 
* '''gramps/gen/lib''' : The core library of GRAMPS objects
 
* '''gramps/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...
 
* '''gramps/gen/utils''' : Common utilities for GRAMPS code (progess monitor dialog, database utilities, callbacks between UI and database code)
 
 
 
=== other ===
 
 
 
Further information about files can be found in [[GEPS 008: File Organization]]. Please note that GEPS 008 is a change proposal completed for Gramps 4.0 and the wiki page does not reflect the actual source tree.
 
  
 
= Develop =
 
= Develop =
Line 201: Line 195:
 
* [[Programming guidelines]]
 
* [[Programming guidelines]]
 
* [[UI style]]
 
* [[UI style]]
* [[Brief introduction to SVN]]
+
* [[Brief introduction to Git]]
* [[Git|A guide for people who would like to use git rather than subversion (SVN). ]]
 
 
* [[Using database API]]
 
* [[Using database API]]
* [http://www.gramps-project.org/docs/ API Code Documentation] - Gramps v3.3.0
+
* [https://www.gramps-project.org/docs/ API Code Documentation] - Gramps current release.
* [[Devhelp]]
+
* [[Devhelp]] - How to include [https://gramps-project.org/docs/ Gramps API] into the Devhelp index.
 
+
* [[Committing policies]]
  
  
 
[[Category:Developers/Tutorials]]
 
[[Category:Developers/Tutorials]]
[[Category:Developers/General]]
+
[[Category:Developers/General|G]]

Latest revision as of 00:27, 12 September 2023

Tango-Dialog-information.png
The article is about setting up for full-scale development of the Gramps core program

For information about developing on a smaller scale visit:


For how to use the Gramps program or install addons visit:

Gnome-important.png
Warning:

This tutorial is a work in progress. Feel free to help and modify it.

Gramps-notes.png

This article's content is incomplete or a placeholder stub.
Please update or expand this section.


This tutorial aims to help you get started initially with Gramps development and shows you a general overview of what you need to know when working with the Gramps source code. The following will help you setup 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

Linux: Optional : set up a development environment

Gnome-important.png
Warning:It is highly recommended that you do not use your normal/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

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 fully separated environment.

Chroot

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.

Gramps-notes.png

This article's content is incomplete or a placeholder stub.
Please update or expand this section.


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 clone the Git repository 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 install python intltool libglib2.0-dev gedit

Another user

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 ../.gitconfig .

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

Gnome-important.png
You have been warned!

At a minimum:

  • Make a Gramps XML Backup
  • Prefix the name of your test family trees 'a_test' eg:'a_test_FamilyTreeName'. By starting with 'a_test' they will show at the top of the Family Tree manager, and the word test makes it clear what they are created for.

Mac OS X

In order to develop (or even use) Gramps on an Apple Macintosh, you must first install all of the prerequisite libraries and their headers. There are three choices for this:

  1. Gtk-OSX,
  2. MacPorts, or
  3. Fink.

Full instructions for building Gramps for each is provided here:

  1. Mac OS X:Build from source:Application package,
  2. Mac OS X:Build from source:MacPorts, or
  3. Mac OS X:Build from source:fink.

The last only works with X11, which is no longer included in OS X but can be installed separately. MacPorts can be built with/for either X11 or OS X's native Quartz graphics backend, and Gtk-OSX is exclusively for Quartz.

Windows

In order to develop (or even use) Gramps on Windows, you must first install a development environment and all of the prerequisite libraries and their headers. Gramps_for_Windows_with_MSYS2

Full instructions for building Gramps is provided here: Building_Gramps_AIO_cx_freeze-based

Install a text editor

Tango-Dialog-information.png
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.


Choose the text editor you like to work with. If your favourite text Editor is not listed you can add it and describe how to set it up here.

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 > Interpreters > Python Interpreter.
    • Click New... to create a link to your Python executable (for example /usr/bin/python3.5).
  • Next, you have to set up a PyDev project:
    • Go in the menu File > New > Project...;
    • Choose PyDev Project
    • Project name could be Gramps
    • Uncheck Use defaults and choose ~/gramps-master as the project directory.
    • Project type is Python 3.5
    • Interpreter is the one you created at the first step above
    • And then you can press Finish.

You are now ready to start coding!

PyCharm

PyCharm is not Free Software like Eclipse is. But 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 "Gramps/src" directory in my local checked out Git WD, and things work from there.

'Version Control » Update Project' automatically syncs up with the Git repository.

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.

The Eric Python IDE

Eric is a python editor. It has everything you need (code completion, python shell, ...)

Geany

Geany is a nice development Editor. One feature I like is that it will automatically recognise python code and list Symbols in a side bar, allowing to jump quickly in your code.

Install it and you can start coding !

Note, you can also get instant documentation for python modules.

SPE

SPE or Stani's python editor, is a python editor. It is somewhat more powerfull than Eric (quick access to code fragments, extensive search, ...) but can be unstable on some setups. Try it to know.

Scribes

Scribes is a text editor written in python and Gtk, that uniquely blends simplicity with well researched powerful functions.

Kate

Kate works well as a general editor for Python. It also recognizes 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

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.

Get the source tree

To get the source tree, you will need Git. Please read the dedicated tutorial Brief introduction to Git for details.

You can also use a graphical Git tool like "gitk (The Git repository browser)" or "git-gui ( A portable graphical interface to Git)".

This tutorial now assumes you have cloned the Gramps repository into a directory called ~/Gramps. If not, you have to change this path when it is used below.

Gnome-important.png
Warning:

Let it be clear that the settings directory ~/.gramps/ is a different hidden directory in your home-dir. Do not store anything there.

Run Gramps from the source

To test that you did all well, you may want to run Gramps from your downloaded Git tree. This is explained in the Running a development version of Gramps; here are the quick steps:

For the internationalization code to work, you need to have the translation tools.

On Debian, just run (as root) - (Only if Debian installs Gramps 4.0+ as Gramps version!):

apt-get build-dep gramps

On Fedora 20+, you will need:

yum install intltool gettext git-core rcs

Build Gramps with:

cd ~/Gramps
python setup.py build

To run Gramps, type:

python Gramps.py

Dependencies

If you have an "GExiv2 Module Not Loaded" you should install it with

sudo apt install gir1.2-gexiv2-0.10

The same for the "osmGpsMap module not loaded, Geography functionality will not be available"

sudo apt install gir1.2-osmgpsmap-1.0

Correct Translation in development

Gnome-important.png
'To be checked if following is still current!'

Gramps-notes.png

This article's content is incomplete or a placeholder stub.
Please update or expand this section.


Warning: you will not be able to load translations on /usr/local/share/locale, because you will load /usr/share/locale, which could be translations for stable release (set on grampsapp.py). You may generate a custom launcher by adding this line:

export GRAMPSI18N=/usr/local/share/locale

if you want to use an other path, you may add this line:

export GRAMPSI18N=@prefix@/share/locale

on current gramps.sh.in (source file) before installation.

Browse the source code

Develop

Before you start developing, read