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 Terminal.app rather than 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). That probably doesn't matter, since we don't need to run the app, we just need the compilers and software development kit.

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

gtk-osx-setup.sh installed a template customization file for you $HOME/.config/jhbuildrc-custom. Open it in a text editor. TextEdit.app will do if you don't have a programming editor installed. Apple also provides nano and vi that you can run in Terminal. Add the following lines:

 moduleset = "https://raw.githubusercontent.com/gramps-project/gramps/maintenance/gramps52/mac/gramps.modules"
 modules = ["meta-gtk-osx-bootstrap", "gramps"]

Change gramps52 in the first line to whatever release version you want. gramps in the second line will build the latest release tarball in that release series. If you want to build the latest commit use gramps-git instead. If you want to build the master branch (and see below why you might) use

 moduleset = "https://raw.githubusercontent.com/gramps-project/gramps/master/mac/gramps.modules"
 modules = ["meta-gtk-osx-bootstrap", "gramps-git"]
 branches["gramps"] = master

instead.

Save the changes, start Applications:Utilities:Terminal.app and run

   jhbuild build

You may get some build failures for gtk-doc and gtk+-3.0 complaining that the pygments and packaging modules can't be found. If that happens select option 4 Start Shell and at the prompt run

   python3 -mpip install pygments
   python3 -mpip install packaging

Doing both at the gtk-doc error will avoid the gtk+-3.0 error. Use Ctrl D to exit the shell and select option 1 to resume the build. 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/gramps51

To build and install it, you must be in a jhbuild shell to create the correct environment, so first run

 jhbuild shell

Then

 python3 setup.py install

That last line is a bit obsolete, as is jhbuild. At the time of writing python3 setup.py build works and puts gramps where the bundler (see below) expects. It does not create a python wheel. To do that you need Python's build package:

 python3 -mpip install build

Then you can run

 build
 install  

to create the wheel and install the PyPi way.

Use Control D to leave the jhbuild shell when you're finished with it.

More customizations

jhbuild-custom is Python and is loaded into jhbuild during startup. There are lots of ways to customize it, see the JHBuild Manual for comprehensive information.

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).

Webkit

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

Running Gramps

To run your just-built Gramps you need to be in a jhbuild shell, so do

 jhbuild shell

We need to tell dlopen how to find the libraries that GObject-Introspection depends on by setting DYLD_LIBRARY_PATH. That environment variable is protected by Apple's System Integrity Protection so we have to include it on the command line that launches Gramps:

 DYLD_LIBRARY_PATH=$PREFIX/lib gramps

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.

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 Gramps.app on your desktop.

Packaging

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!