Difference between revisions of "Mac OS X:Application package"

From Gramps
Jump to: navigation, search
(Gramps 3.3 and EXIF Editing: Boost-python and Lion)
m (Before installation)
(18 intermediate revisions by 4 users not shown)
Line 1: Line 1:
[[Category:Developers/Packaging]]
+
This page describes the 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.
  
The GTK-OSX port of GRAMPS for Mac is a single, stand-alone bundle which uses the native quartz windowing system instead of X11.
+
== Before installation ==
  
Mac GRAMPS is available for both Intel and PPC Macs.  OS X 10.5 (Leopard) is presently required; WebKitGtk doesn't presently work on earlier versions. The distribution page carries both a binary application that should work as soon as it is downloaded.  
+
'''Mac OS X versions''' The current version of the application ({{Version_Mac}}) should run on Mac OS X 10.5 (Leopard) on both Intel and PPC computers, Mac OS X 10.6 (Snow Leopard) and 10.7 (Lion).
=== OSX 10.7 Lion ===
+
  
'''Gramps is not currently stable on Lion.''' Besides an easily-fixed issue with libiconv and with undecorated windows which can be patched by retrieving the attachments from this [http://bugzilla.gnome.org/show_bug.cgi?id=655059 Gnucash Bug Report] and installing them in Gramps.app/Contents/Resources/lib, resizing windows works rather oddly and will eventually [http://bugzilla.gnome.org/show_bug.cgi?id=655122 crash].
+
The pre-built Gramps application doesn't work on earlier versions of Mac OS X, because it needs WebKitGtk, and that doesn't work on earlier operating systems. Versions of Gramps before 3.3.1 didn't work on Lion, except for a special beta package provided as an interim measure. All Lion users should upgrade to {{Version_Mac}} as soon as practical.
  
I've uploaded a new DMG to Sourceforge, [http://sourceforge.net/projects/gramps/files/Stable/3.3.0/Gramps-3.3.0.Lion-Beta.dmg/download Gramps-3.3.0-Lion-Beta.dmg]. The Gtk-quartz maintainers haven't firmly decided on the fixes to the various bugs, but we're pretty close, and the fixes seem to work.  
+
'''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).
  
In my preliminary testing I found one database that opened fine and another which had a BerkeleyDB Environment error, so I advise that anyone who can still use a previous version of Gramps to backup all of his/her databases to Gramps XML as a precaution before trying the Gramps Lion Beta.
+
'''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, subsitute 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.
  
== How to Download and run the binary GRAMPS application for Mac ==
+
== Installing Gramps ==
 +
 
 +
'''Download:''' Select one of [http://sourceforge.net/projects/gramps/files/Stable/ Intel] or
 +
[http://sourceforge.net/projects/gramps/files/Stable/ PPC]. You'll get a download window. Once it's downloaded, you can open the dmg (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 similar program, 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 [http://www.documentfoundation.org/download/ LibreOffice], [http://www.calligra-suite.org/ Calligra] (or [http://www.neooffice.org/ 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):<br>
 
'''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):<br>
Line 19: Line 27:
 
* 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.
 
* 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.
  
'''Download:''' Select one of [http://sourceforge.net/projects/gramps/files/Stable/ Intel] or
+
== Advanced setup ==
[http://sourceforge.net/projects/gramps/files/Stable/ PPC]. You'll get a download window. Once it's downloaded (it may take a while, they're 38M each), you can open the dmg (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.
+
  
'''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).
+
Usually, the default settings will be correct, but occasionally you may need to set things up differently.
  
'''New Version Notice:''' The new (3.2.4 and later) builds will default to using your Library/Application Support/gramps folder, which, if you want to keep your old database and settings, you'll need to create. Unless you've changed the location in Preferences, they're 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, subsitute 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.
+
'''Language:''' Normally, GRAMPS sets up languages and formats from system preferences (Language and Text on Snow Leopard and Lion; International on Leopard). There are three main settings:
 
+
* On the first pane (Language(s)) is a list of languages. GRAMPS will go down the list and select the first one for which it has a translation to select the '''language in which all menus, labels, and messages''' are presented.
'''Language:''' Normally, GRAMPS sets up languages and formats from system preferences (Language and Text on Snow Leopard and Lion; Internationalization on Leopard). There are three main settings: On the first pane (Languages) is a list of languages. GRAMPS will go down the list and select the first one for which it has a translation to select the language in which all menus, labels, and messages are presented. On the right side of that pane at the bottom is an "Order for Sorted Lists" listbox which sets the way that lists are alphabetically sorted. Finally, in the third pane (Formats) one can select a country which determines things like month and day names, whether a comma, dot, or space is used to separate thousands or decimal fractions, and so on.
+
* On the right side of that pane at the bottom is an "Order for sorted lists" listbox which sets the way that '''lists are alphabetically sorted'''.
 +
* Finally, in the third pane (second pane in Leopard) (Formats) one can select a country/Region which determines things like '''month and day names, whether a comma, dot, or space is used to separate thousands or decimal fractions, and so on'''.
  
 
If you want to run GRAMPS with different language or locale settings than you use for your system settings, you can use the "defaults" program from Terminal.app (Applications:Utilities:Terminal.app):
 
If you want to run GRAMPS with different language or locale settings than you use for your system settings, you can use the "defaults" program from Terminal.app (Applications:Utilities:Terminal.app):
Line 32: Line 40:
 
   defaults write -app Gramps AppleLocale "de_DE"
 
   defaults write -app Gramps AppleLocale "de_DE"
 
   defaults write -app Gramps AppleCollationOrder "de"
 
   defaults write -app Gramps AppleCollationOrder "de"
AppleLanguages corresponds to the language list, AppleLocale to the Format country, and AppleCollationOrder selects the way that lists are sorted. You need not set them all.
+
AppleLanguages corresponds to the language list, AppleLocale to the Format country/Region, and AppleCollationOrder selects the way that lists are sorted. You need not set them all.
  
 
To remove the special settings  
 
To remove the special settings  
 
   defaults delete -app Gramps AppleLanguages (or AppleLocale or AppleCollation).
 
   defaults delete -app Gramps AppleLanguages (or AppleLocale or AppleCollation).
 
   
 
   
[[Howto:Change the language of reports]] has more information on language features in Gramps. When reading it, remember that AppleLanugages (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.
+
[[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.
  
'''Links with other programs:''' Double clicking an image in the media reference editor should bring up Apple Preview, or a similar program, 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.
+
'''Dictionaries:''' The spelling checker uses  MySpell dictionaries -- the same ones that [http://www.documentfoundation.org/download/ LibreOffice] and NeoOffice use. Unfortunately, they bury them in their application bundles, so you can download them [http://wiki.services.openoffice.org/wiki/Dictionaries 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).
  
GRAMPS doesn't use the X11 Mac package. It's useful to install [http://www.documentfoundation.org/download/ LibreOffice], [http://www.calligra-suite.org/ Calligra] (or [http://www.neoffice.org NeoOffice], a more mac-friendly version) and [http://www.graphviz.org/ Graphviz] to produce reports, but they are both straightforward.
+
== Bugs ==
 
+
'''Dictionaries:''' The spelling checker uses  MySpell dictionaries -- the same ones that [http://www.documentfoundation.org/download/ LibreOffice] and NeoOffice use. Unfortunately, they bury them in their application bundles, so you can find them to [http://wiki.services.openoffice.org/wiki/Dictionaries download 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).
+
  
 
=== If something seems to go wrong ===
 
=== If something seems to go wrong ===
 +
 
You'll find error messages in the console log, which you can view with /Applications/Utilities/Console.app
 
You'll find error messages in the console log, which you can view with /Applications/Utilities/Console.app
  
==Bugs==
+
All of the known bugs in 3.1.2 have been corrected in 3.2.4 and later. There will no doubt be new ones; report them in the usual way on [http://www.gramps-project.org/bugs/my_view_page.php 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.  
All of the known bugs in 3.1.2 have been corrected in 3.2.4 and later. There will no doubt be new ones; report them in the usual way on [http://www.gramps-project.org/bugs/my_view_page.php Mantis] ([http://gramps-project.org/wiki/index.php?title=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.  
+
The 3.1.2 bugs are described at [[Mac OS X:Build from source:gtk-osx:bugs]].
The 3.1.2 bugs are described at [[Mac gtk-osx port bugs]].
+
  
==Updates==
+
== 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.
 
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.
  
==Building GRAMPS from Scratch==
+
[[Category:Developers/Packaging]]
 
+
[[Category:Documentation]]
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. '''''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!'''''
+
+
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 [http://developer.apple.com/technologies/xcode.html Apple], though you must register as a Mac developer. For Lion users, XCode is available for free from the App Store.
+
 
+
Next, read [https://sourceforge.net/apps/trac/gtk-osx/wiki/Build the build instructions for Gtk-OSX], '''''especially the Prerequisites'''''. Download and run the [http://downloads.sourceforge.net/sourceforge/gtk-osx/gtk-osx-build-setup.sh gtk-osx-build-install.sh] script, which will set up jhbuild for you.
+
 
+
''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 are building for distribution, especially if you are running Snow Leopard on a 64-bit capable machine (Core2Duo, Core i5 or i7, or any Xeon) you should edit the file ~/.jhbuildrc-custom so that the call to <tt>sdk_setup</tt> looks like
+
  setup_sdk(target="10.5", sdk_version="10.5", architectures=["i386"])
+
Lion doesn't support SDKs older than 10.6, so in that case the line should be:
+
  setup_sdk(target="10.5", sdk_version="10.6", architectures=["i386"])
+
(If you're building on a PPC, you don't need to worry about this.)
+
 
+
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.
+
 
+
jhbuild is installed in ~/.local/Source, and produces a binary which appears in ~/.local/bin. You'll want to add ~/.local/bin to your path:
+
  export PATH=~/.local/bin:$PATH
+
 
+
Next, you'll need to get a local copy of the gramps mac configuration stuff from svn (if you already have a gramps svn sandbox, then skip this step and substitute the path to it where appropriate below):
+
  svn co https://gramps.svn.sourceforge.net/svnroot/gramps/trunk/mac gramps-mac
+
That will make a current copy from the repository in your current directory, which we'll assume to be ~.
+
 
+
The Gtk-OSX build instructions are very straightforward, but we need to deviate from them a bit to keep from doing things more than once. Run the following commands from the terminal:
+
 
+
  jhbuild bootstrap
+
Now we need to build berkeleydb:
+
  jhbuild --moduleset=~/gramps-mac/gramps.modules build berkeleydb
+
And rebuild python to include the bsddb module (it will notice that we have berkeleydb and do it automatically)
+
  jhbuild --moduleset=bootstrap.modules buildone --force python
+
Now we're ready to build everything else:
+
  jhbuild --moduleset=~/gramps-mac/gramps.modules build meta-gtk-osx-bootstrap meta-gtk-osx-core meta-gtk-osx-python gramps
+
 
+
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. More is built than is needed in the final Gramps application - for example, the build tools are themselves built.
+
 
+
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
+
  jhbuild --moduleset=~/gramps-mac/gramps.modules build meta-gtk-osx-bootstrap meta-gtk-osx-core meta-gtk-osx-python gramps
+
to update everything that has been changed since the previous build. Most of the time nothing will have changed except gramps itself.
+
 
+
If you want to build the svn trunk, you can substitute "gramps-svn" for "gramps". If you want to have both installed, you'll need to set up separate prefixes in .jhbuildrc-custom; gramps doesn't version its installations, so the most recent will overwrite the previous build.
+
 
+
==== Gramps 3.3 and EXIF Editing ====
+
 
+
Gramps 3.3.0 introduced a new module, EXIF Editing, which has two tricky dependencies, which JHBuild doesn't know how to handle yet. 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, since earlier SDKs are not available.
+
 
+
The first is [http://www.boost.org/libs/python/doc/ Boost-python], a python interface for C++ provided as part of [http://www.boost.org/ 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:
+
  cd tools/build/v2
+
  ./bootstrap.sh --with-toolset=darwin
+
  ./bjam --prefix="$PREFIX" install
+
  cd ../../..
+
  bjam toolset=darwin address-model=32 --prefix=$PREFIX --with-python --cmd-or-prefix=$PYTHON cxxflags="$CXXFLAGS" cflags="$CFLAGS" linkflags="$LDFLAGS" install
+
 
+
Once that's done, quit the shell and select "2" (ignore error) twice to move on to the next library, [http://tilloy.net/dev/pyexiv2/ PyExiv2], which also uses a different build system, [http://www.scons.org/ 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:
+
  export CXXFLAGS="$CXXFLAGS -I$PREFIX/include"
+
  export CFLAGS="$CFLAGS -I$PREFIX/include"
+
  export LDFLAGS="$LDFLAGS -lpython2.7"
+
  scons
+
  scons install
+
  ln $PREFIX/lib/python2.7/site-packages/libexiv2python.dylib $PREFIX/lib/python2.7/site-packages/libexiv2python.so
+
  install_name_tool -id python2.7/site-packages/libexiv2python.dylib $PREFIX/lib/python2.7/site-packages/libexiv2python.dylib
+
Quit the shell and pick "2" a few more times to move on to the next module.
+
 
+
== Bundling ==
+
The next step is to create an application bundle. You'll need ige-mac-bundler, so follow the instructions in the [https://sourceforge.net/apps/trac/gtk-osx/wiki/Bundle Gtk-OSX Wiki] to download and install it.
+
 
+
You may need to edit <tt>~/gramps-mac/Info.plist</tt> to update the version number and copyright information.
+
 
+
Now open a jhbuild shell and run the bundler:
+
  jhbuild shell
+
  chmod +w $PREFIX/lib/libpython2.6.dylib
+
  ige-mac-bundler ~/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-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.
+
 
+
Good Luck!
+
 
+
'''Note:''' The 3.1.2 installer left out two files:
+
#''_strptime.py''. You can get the file from  [http://www.gramps-project.org/bugs/view.php?id=3177 here].
+
#''keysyms.py''. You can get the file from  [http://www.gramps-project.org/bugs/view.php?id=3157 here].
+

Revision as of 23:38, 24 August 2012

This page describes the 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

Mac OS X versions The current version of the application (4.1.2) should run on Mac OS X 10.5 (Leopard) on both Intel and PPC computers, Mac OS X 10.6 (Snow Leopard) and 10.7 (Lion).

The pre-built Gramps application doesn't work on earlier versions of Mac OS X, because it needs WebKitGtk, and that doesn't work on earlier operating systems. Versions of Gramps before 3.3.1 didn't work on Lion, except for a special beta package provided as an interim measure. All Lion users should upgrade to 4.1.2 as soon as practical.

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, subsitute 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.

Installing Gramps

Download: Select one of Intel or PPC. You'll get a download window. Once it's downloaded, you can open the dmg (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 similar program, 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/gramps32
  • 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

Usually, the default settings will be correct, but occasionally you may need to set things up differently.

Language: Normally, GRAMPS sets up languages and formats from system preferences (Language and Text on Snow Leopard and Lion; International on Leopard). There are three main settings:

  • On the first pane (Language(s)) is a list of languages. GRAMPS will go down the list and select the first one for which it has a translation to select the language in which all menus, labels, and messages are presented.
  • On the right side of that pane at the bottom is an "Order for sorted lists" listbox which sets the way that lists are alphabetically sorted.
  • Finally, in the third pane (second pane in Leopard) (Formats) one can select a country/Region which determines things like month and day names, whether a comma, dot, or space is used to separate thousands or decimal fractions, and so on.

If you want to run GRAMPS with different language or 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 AppleLanguages "(de, en)"
  defaults write -app Gramps AppleLocale "de_DE"
  defaults write -app Gramps AppleCollationOrder "de"

AppleLanguages corresponds to the language list, AppleLocale to the Format country/Region, and AppleCollationOrder selects the way that lists are sorted. You need not set them all.

To remove the special settings

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

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 3.1.2 have been corrected in 3.2.4 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. The 3.1.2 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.