4,191
edits
Changes
→None of above
{{man tip|The article is about developing for the Gramps program|If you are looking 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.}}
This tutorial aims to help you in your first [http://en.wikipedia.org/wiki/Hacker_%28programmer_subculture%29 hacking] get started initially with Gramps development and shows you a general overview of what you need to know when working with the Grampssource code. It The following will help you setting up 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 ==
{{man warn|Warning:|I It is highly recommend 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.
=== VirtualBox ===
[httphttps://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 ===
=== Another user ===
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. 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 is what the cloning looks like in my <code>/etc/passwd</code>:
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 ''<code>.gramps</code>''! Something like (inside <code>~vassilii/pub</code>):
ln -s ../.bashrc ../.mozilla ../.ratpoisonrc ../.gitconfig .
=== None of above ===
{{man warn|You have been warned! |At a minimum :* [[How to make a backup|Make a Gramps XML Backup]]* Prefix the name of your test family trees 'a_test_name<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 family tree {{man label|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 :# [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]].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.
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]].
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 ==
=== Eclipse + pydev PyDev ===[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 ''';** Then choose "Pydev"-'''PyDev > Interpreters >"Python Interpreter - Python"'''.** Click '''New... With "new", you can ''' to create a link to "your Python executable (for example ''/usr/bin/python2python3.5". there you are'').
* Next, you have to set up a pydev PyDev project. :** Go in the menu "'''File" -> "New" -> "Project", and choose a Pydev projet. ..''';** Choose '''PyDev Project'''** Project name could be "''Gramps trunk", uncheck "''** Uncheck '''Use defaults" ''' and choose "'''~/gramps-trunk" master''' as the project directory. ** Project type is "'''Python 23.6", and 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 !
You are now ready to start coding! === pycharm PyCharm ===[httphttps://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 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.
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 ===[httphttps://eric-ide.python-projects.org/index.html Eric4Eric] is a python editor. It has everything you need (code completion, python shell, ...)
=== Geany ===
[httphttps://www.geany.org/ Geany] is a nice development Editor. One feature I like is that it will automaticly 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 [httphttps://wiki.geany.org/howtos/pydocw instant documentation for python modules].
=== SPE ===
[http://pythonide.stani.be/ SPE] or Stani's python editor, is a python editor. It is somewhat more powerfull than Erik4 Eric (quick access to code fragments, extensive search, ...) but can be unstable on some setups. Try it to know.
=== Scribes ===
[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=== [httphttps://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.
== Get the source tree ==
To get the source tree, you will need Git. Please have a look at read the dedicated tutorial [[Brief introduction to Git]] for details.
You can also use a graphical Git tool like "gitk" or "git-gui".
'''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.'''
{{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.''}}
== Run Gramps from the source ==
apt-get build-dep gramps
On Fedora 8 - 10 (Fedora is up to version 17 now so does this still apply?)20+, you will need:
yum install intltool gettext git-core rcs
== Correct Translation in development ==
{{man warn|'''To check 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).
You may generate a custom launcher by adding this line:
* [[Brief introduction to Git]]
* [[Using database API]]
* [httphttps://www.gramps-project.org/docs/ API Code Documentation] - Gramps mastercurrent release.
* [[Devhelp]]
* [[Committing policies]]
