Mac OS X:Application package

From Gramps
Macos 200x200.png

Installation of the ready-to-run Gramps application for Mac OS X. This is also known as the GTK-OSX port of Gramps for Mac. It is a single, stand-alone bundle which uses the native quartz windowing system of Mac OS X instead of X11.

Before installation

MacOS versions Gramps 5.0 requires Mac OS X 10.9 (Mavericks) and later. Gramps 5.1 requires at least Mac OS X 10.10 (Yosemite).

Back up your databases:
If you're using Time Machine, that's already taken care of. (You do test your Time Machine backups periodically, right?) But it doesn't hurt to have a spare copy set aside before starting up a new version. If you've been using the Gtk-OSX build, version 3.2.4 or later, just copy Library/Application Support/gramps/grampsdb. (Right click/option click and select "Make a copy" from the menu. It will be named grampsdb(2).
New Version Notice:
If you are upgrading from the pre-built Gramps Application version 3.2.3 or earlier (or a build from source version) and you want to keep your old database and settings, you'll need to create a Library/Application Support/gramps folder with your existing data in it. Unless you've changed the location in Preferences, the data is in a hidden folder in your home directory called ".gramps". Select a Finder window and select Go>Go to Folder from the menu. Type "/Users/yourname/.gramps" in the dialog box that opens up, and click on "Go". (Yes, substitute your userid for "yourname".) The hidden folder will appear, highlighted and open. Option-drag the whole thing to Library/Application Support (the one in your home folder, not the one in your boot drive's "root" directory). Slow-double-click on the new copy so that you can edit the name and delete the '.' at the beginning to unhide it.
Gramps-notes.png
Migrating to Apple Silicon?

Make an XML backup of your databases on your Intel Mac and copy them to your Apple Silicon Mac and restore them there after installing Gramps. There seems to be a binary object incompatibility in SQLite3 databases, even when running an Intel binary using Rosetta2.

Installing Gramps

From the Download#Mac_OS_X page download the dmg. Once it's downloaded, you can open the file (just double click on it in Finder if your browser doesn't open it automatically) and drag the Gramps application wherever you like. Once installed on your computer, it opens like any other application.

Links with other programs: Double clicking an image in the media reference editor should bring up Apple Preview (or a whatever program you've set as the default to edit that kind of image) to view the image. Clicking the view button in an internet reference should bring up the URL in the default browser. Clicking the Google Maps button in the Places display should bring up the map in the browser.

Gramps doesn't use the X11 Mac package. It's useful to install LibreOffice, Calligra (or NeoOffice, a more mac-friendly version) to work on your reports after saving them from Gramps.

What goes where

File structure: Gramps database and settings files can be found at the following places in the Mac file system (Gramps Version 3.2.5 and later):

  • The Gramps database with the user's genealogical information is stored under /Users/<username>/Library/Application Support/gramps/grampsdb
  • Setting files (ini-files) are found here: /Users/<username>/Library/Application Support/gramps/gramps51
  • Start-up settings for Gramps (for e. g. the environment variable LANG) can be accessed through Gramps.app (generally in /Applications): Right click on "Gramps.app", select "Show Package Content" from the menu, the start-up settings are found in the file Contents/MacOS/Gramps.

Advanced setup

If Gramps has the appropriate translation, calendar, etc. it will honor the settings in System Preferences>Language and Region provided that the combination results in a locale that exists in /usr/share/locale. It will always fall back to English if it can't figure out your Language & Region settings. Some examples: French and France, Belgium, or Canada work fine, as do German and Germany or Switzerland and Dutch and Netherlands or Belgium. German and France doesn't work, nor does Dutch and Switzerland.

If you want to run Gramps with different locale settings than you use for your system settings, you can use the "defaults" program from Terminal.app (Applications:Utilities:Terminal.app):

  defaults write -app Gramps AppleLocale "de_DE"

to set Gramps to operate in German with German calendar and formatting.

To read the setting use:

  defaults read -app Gramps

this gave "Can't determine domain name for application Gramps; defaults unchanged" for me; if you have problems you can use

  defaults read  org.gramps-project.gramps

The settings are stored in ~/Library/Preferences/org.gramps-project.gramps.plist

To remove the special settings

  defaults delete -app Gramps AppleLanguages (or AppleLocale or AppleCollation).

Note that you will need to run Gramps at least once before the defaults system will recognize its existence; before that trying to use defaults will produce an error about there being no Gramps application.

Howto:Change the language of reports has more information on language features in Gramps. When reading it, remember that AppleLanguages (which corresponds to the language list on the Languages & Text system preference pane) sets the LANGUAGE environment variable and AppleLocale (Formats in the Languages & Test pane) sets the LANG variable.

Dictionaries

The spelling checker uses MySpell dictionaries -- the same ones that LibreOffice and NeoOffice use. Unfortunately, they bury them in their application bundles, so you can download them here. You need to install them in /Library/Dictionaries, and you'll need to authenticate as an administrator to do so. If you have one of them installed and know how to make symbolic links from the command line, you'll find them in Contents/share/uno_packages/cache/uno_packages, scattered about in the hash-named directories. You'll need to link both the aff and dic files (e.g., en_US.aff and en_US.dic).

Bugs

If something seems to go wrong

You'll find error messages in the console log, which you can view with /Applications/Utilities/Console.app

All of the known bugs in previous version have been corrected in Gramps 5.2.3 and later. There will no doubt be new ones; report them in the usual way on Mantis (Using the bug tracker instructions). When reporting what you're sure is an OSX specific bug, please set the Platform field to "mac" (no quotes, caps, or spaces!) so that I can find it easily.

Previous Gramps version 3.2.4, bugs are described at Mac OS X:Build from source:gtk-osx:bugs.

Updates

Gramps stores all its internal data in ~/Library/Application Support. So, to upgrade a Gramps application bundle to a newer version, just throw the old application in the Trash. Make a backup copy of your data, just in case, then download the new version of the application and just use it. If you don't like the new version and want the old one back, throw the new version in the Trash and fetch the old one back from the Trash. The Gramps version is shown in Finder if you use column view; otherwise right click on it and select Get Info.