Open main menu

Gramps β

Mac OS X:Build from source:Application package


Building Gramps from Scratch

Being able to building Gramps from scratch (from the fundamental Python scripts) is useful to produce a version not currently available as a binary for your particular OS platform or version. Or, to produce a complete environment for debugging and further development, including debugging of all the C libraries Gramps uses... like GTK.

This is a "command line interface" process. It's not too difficult, but you'll be using and, not the XCode integrated development environment.

If you're not familiar with using the unix command line, you might find the frequent use of "~" (tilde) below puzzling. It refers to the user's home directory (mine is /Users/john; if your name is John, then yours probably is too.) You can use it that way in commands if your current directory is somewhere else.

Step 1: Install Xcode

You'll need a compiler. Apple provides two ways to install one: "Command Line Tools" installs just the command-line build environment and puts most of the header files in /usr/include. Simply trying to run a program that requires it like gcc or git should produce a dialog box offering to install them, but if that doesn't work you can run sudo xcode-select --install. Apple also has a full-featured integrated development environment called Xcode. It's available for free from the App Store.

If you try to download Xcode, Apple will probably offer you the latest version of Xcode, irrespective of whether it runs on the version of Mac OS X you are using (Apple probably expects you to upgrade everything to the very latest). You may need to search for an earlier version. For example, if you're running Mac OS X 10.11 El Capitan, then it is probably best to use Xcode 7 (e.g. Xcode 7.3.1). Older versions of Xcode are available from Apple's developer site; you'll need to register your AppleID for development.

Step 2: Install jhbuild

Next, read the build instructions for Gtk-OSX, especially the Prerequisites.

It's important that jhbuild is not confused by any existing Homebrew, MacPorts, or Fink installation. For this reason, it can be convenient to create a new Mac User account and log in to that account if you have any of those installed.

Then follow the steps under Procedure

Step 3: Install Gramps dependencies and Gramps

 curl -o gramps.modules


 curl -o gramps.modules
 jhbuild --moduleset=~/gramps.modules build meta-gtk-osx-bootstrap gramps

If you want to build the latest release tarball rather than the latest check-in, use gramps instead of gramps-git for the last module--but note that since we don't release from the master branch, gramps.modules doesn't have a gramps module in master.

If you're planning to work on several branches, a single checkout will work: Start with master. Gramps is pure python, so once you've got everything built you need repeat this only to update the dependencies. You can quickly switch branches in your git repo with:

 git clean -fdx
 git checkout maintenance/gramps40
 python build


It's tedious and error-prone to type the long list of modules every time you want to build gramps. So you may want to modify ~/.jhbuildrc-custom to declare the moduleset and modules variables. Note that .jhbuildrc-custom is a Python file that is loaded and executed by jhbuild, so you can make it quite complex.

Do be aware that defining new global variables will elicit a warning from jhbuild so be careful to prefix any top-level variables with '_' (underscore).


Gramps has an optional dependency on WebKit, which is used for the html-renderer addon. If for some reason you want to use this addon, add WebKit to your list of dependencies but be aware that it may take a long time to build.


The next step is to create an application bundle. You'll need gtk-mac-bundler, so follow the instructions in the Gtk-OSX Wiki to download and install it.

Assuming that your local repository wound up in ~/gtk/src/gramps: You may need to edit ~/gtk/src/gramps/mac/Info.plist to update the version number and copyright information.

Now open a jhbuild shell and run the bundler:

 jhbuild shell
 gtk-mac-bundler ~/gtk/src/gramps/mac/gramps.bundle

You'll have an application bundle named on your desktop.


To make an uploadable disk image, create a folder named "Gramps-version", replacing "version" with the current version number. Drag your app bundle to this directory. Open your build directory and copy (option-drag) the files "FAQ", "COPYING", "README", and "NEWS" to the Gramps folder you just made. Rename each to have a ".txt" extension so that they're readable with QuickLook. You might also rename COPYING to License.txt so that its meaning is more clear to users who aren't familiar with the GPL.

Now open Applications>Utilities>Disk Utility and select File>New Image From Folder and select your folder, then approve the name and location. You'll have a dmg ready for distribution.

Good Luck!