Building Gramps from Scratch

Building Gramps from scratch is useful to produce a version not currently available as a binary (for example, a PPC 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 process. It's not too difficult, but you'll be using Terminal.app, not XCode. Unfortunately, Gtk has so far resisted efforts to get it to successfully cross-compile PPC on Intel or vice-versa, so the whole process must be repeated on machines of each architecture. N.B. This procedure has not been tested against OS X 10.4 Tiger. Some packages may not be compatible with that very old version of OS X.

If you're not familiar with using the unix command line, you might find the frequent use of "~" 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 XCode, Apple's development environment. There's a copy on your OS X distribution DVD, or you can download the latest version from Apple, though you must register as a Mac developer. For Lion/Mountain Lion users, XCode is 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, as of January 2017, running Mac OS X 10.11 El Capitan it is probably best to use Xcode 7 (e.g. Xcode 7.3.1).

Earlier version of Xcode were delivered as an installer in a disk image (.dmg). Xcode should be installed in the usual way by double clicking on the installer and following the instructions.

Later versions of Xcode are delivered as an Application (.app) in a disk image, with instructions to copy this to your Applications folder. You probably need to run the Application to get it to install everything - if you don't, when you go on to the next step it will complain that you haven't agreed to the Xcode licence agreement.

Step 2: Install jhbuild

It's important that jhbuild is not confused by any existing 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 either of those installed.

Download and run the gtk-osx-build-install.sh script, which will set up jhbuild for you. (It is assumed here that you have downloaded gtk-osx-build-install.sh into your home directory, and that you run the following command from there).

This shows you have Python 2.7. As described in the build instructions for Gtk-OSX, if you have a version of Python earlier than 2.5, you have to follow the special instructions to build a Python 2.7 module.

Now type:

jhbuild bootstrap

Step 3: Install Gramps dependencies and Gramps

Gramps 3.4.x

Next, you need a copy of the moduleset file. You *could* just pass the url to jhbuild, but it's easier to download it:

jhbuild by default puts everything it is building in ~/gtk (controlled by the hidden files ~/.jhbuildrc and ~/.jhbuildrc-custom ). ~/gtk/source contains the downloaded sources, and ~/gtk/inst contains the built libraries and applications.
Not everything that this procedure builds will be included in the Gramps application bundle; there are some intermediate dependencies and build tools that are necessary for building everything but not required at runtime. ```That doesn't mean that some modules can be skipped.```

At this point, you can do

jhbuild shell
gramps

at the command line and run gramps. Most everything will work (see the note about spelling dictionaries above).

Once you've done this once, you can generally get away with just running

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.

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:

.jhbuildrc-custom

It's annoying 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 beware that defining new global variables will elicit a warning from jhbuild so be sure to prefix any top-level variables with '_'.

Gramps 3.x and EXIF Editing

Gramps 3.3.0 introduced a new module, EXIF Editing, which has two tricky dependencies that JHBuild doesn't know how to handle. Thanks to Gtk+-3, these have been replaced in Gramps-4.0 (and master) with a module that JHBuild can build, so these instructions apply only to Gramps-3.4.x. In order to evade the persnickityness of jhbuild's dependencies, they're given as "soft" dependencies -- you have to add them to your modules list. If you don't, Gramps will still build fine, you'll just get a warning notice about Exiv2 not being installed.

Warning:Boost-python will not successfully build with either the 10.6 (Snow Leopard) or 10.7 (Lion) SDKs. With 10.7 it won't build at all; with 10.6, it will build but will crash Python on import. Consequently you can't build EXIF editing using Lion or later, since earlier SDKs are not available.

The first is Boost-python, a python interface for C++ provided as part of Boost. It uses its own build system, bjam. Since jhbuild doesn't know how to use bjam, it will download the package for you, then error out. Select item 4, "start a shell", and do the following:

Once that's done, quit the shell and select "2" (ignore error) twice to move on to the next library, PyExiv2, which also uses a different build system, SCons. The SCons folks are bright enough to use distutils, which JHBuild can handle, so that gets built and installed for you. JHBuild will stop again after downloading and extracting PyExiv for you, so once again select "4" to start a shell and run the following:

Quit the shell and pick "2" a few more times to move on to the next module.

Webkit

Gramps has an optional dependency on WebKit, which is used for the html-renderer add-on. If for some reason you want to use this add-on, add WebKit to your list of dependencies but be aware that it take a long time to build.
WebKit will not build on 10.4 (Tiger) or earlier systems, nor will it build against a 10.4 SDK. You must be running 10.5 (Leopard) or newer for this procedure to succeed!

Bundling

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.

Packaging

To make an uploadable disk image, create a folder named "Gramps-arch-version", replacing "arch" with either Intel or PPC and "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 it's 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.