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

From Gramps
Jump to: navigation, search
m
(Rewrote build, bundle, and package instructions)
Line 1: Line 1:
 
[[Category:Developers/Packaging]]
 
[[Category:Developers/Packaging]]
  
'''Warning:''' this page describes the [http://gtk-osx.sourceforge.net/ GTK-OSX] port of GRAMPS to Mac, which is still under test. This page too is still under construction. The program described may not work as expected. Or even work. Use it on precious data at your own risk!
+
'''Notice:''' this page describes the [http://gtk-osx.sourceforge.net/ GTK-OSX] port of GRAMPS to Mac, which has not been thoroughly tested. Everything should work just as it does on Linux, but you are encouraged to make backups to protect your data. Time Machine will do very nicely.
  
'''Note:''' There was missing files from the installer below.
+
'''Notice:''' This page is in transition at the moment; a new set of binaries for 3.2.4 will be available shortly. The build instructions will be changed first, as they will enable you to build your own 3.2.4 bundle from sources. Most of issues below apply only to the 3.1.2 build and have been corrected for 3.2.4.
 +
 
 +
'''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].
 
#''_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].
 
#''keysyms.py''. You can get the file from  [http://www.gramps-project.org/bugs/view.php?id=3157 here].
  
The GTK-OSX port of GRAMPS for Mac is expected to supersede the Macports and Fink versions. It is closer to a native Mac application and should rely less on other programs, so should be easier to use and maintain.
+
The GTK-OSX port of GRAMPS for Mac is a single, stand-alone bundle which uses the native quartz windowing system instead of X11.
  
Mac GRAMPS is available for both Intel and PPC Macs.  The distribution page carries both a binary application that should work as soon as it is downloaded, and also a build environment which should allow a Mac with the Apple Xcode tools to build the whole thing from scratch. The binary application was built for OS X 10.5.7 but should (in theory) work on OS X 10.4. The PPC binary is known definitely ''not'' to work on OS X 10.3.9. To discover what OS and processor is in a Mac, choose About This Mac from the Apple menu in the top left of the Desktop screen.
+
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.  
  
 
== How to Download and run the binary GRAMPS application for Mac ==
 
== How to Download and run the binary GRAMPS application for Mac ==
  
If there is an existing GRAMPS database, it is wise to create a backup archive of an existing GRAMPS database before trying a new program, as described in the note on backups below. GRAMPS for Mac is still new and untested. Take care!
+
'''Back up your databases:''' Unless you've changed the location in Preferences, they're in a hidden folder in your home directory called ".gramps". If you already know about such things, great, just copy the "grampsdb" subdirectory somewhere else before starting. If you've never heard of hidden folders, here's how to back it up: 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".) A new Finder window will open, and you can option-drag the grampsdb folder somewhere else for safety.
 +
 
 +
'''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. In this case, open the .gramps folder just like above, but 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 run the binary application, visit the [http://www.gramps-project.org/apple/ download page] and click on the latest download. The download name gramps-x.y.z-macnn-Intel.zip specifies the version of GRAMPS from which the build was made, and a "mac''nn''" version which changes whenever a minor bug fix is made to the Apple binary, and the processor (Intel or PPC) on which the program will run. The gramps-x.y.z-macnn-builder.zip files are the build environments to build each version from scratch, which can be ignored if only the binary application is needed. It's possible to download and run the binary application to a Mac without any Mac admin privileges, and with a Mac using only the programs supplied straight out of the box.  
 
To run the binary application, visit the [http://www.gramps-project.org/apple/ download page] and click on the latest download. The download name gramps-x.y.z-macnn-Intel.zip specifies the version of GRAMPS from which the build was made, and a "mac''nn''" version which changes whenever a minor bug fix is made to the Apple binary, and the processor (Intel or PPC) on which the program will run. The gramps-x.y.z-macnn-builder.zip files are the build environments to build each version from scratch, which can be ignored if only the binary application is needed. It's possible to download and run the binary application to a Mac without any Mac admin privileges, and with a Mac using only the programs supplied straight out of the box.  
  
Any browser on the Mac will download the binary application, and depending on how it's configured, uncompress it and store it, usually in the Downloads stack. If it doesn't uncompress (it's still called .zip instead of GRAMPS with a pretty family tree icon) then double-clicking it should turn it into GRAMPS. It can be dragged to the Desktop for convenience, or stored in the Applications folder.
+
Any browser on the Mac will download the binary application, and depending on how it's configured, uncompress it and store it, usually in the Downloads stack. If it doesn't uncompress (it's still called .zip instead of GRAMPS with a pretty family tree icon) then double-clicking it should turn it into GRAMPS. Like any  app bundle, it can be dragged anywhere you like (or even left in your downloads folder).
 +
If you drag it to the Dock, it won't move the actual bundle, but you'll always have it available to launch.
  
Double-clicking on the GRAMPS application should launch GRAMPS. It Should Just Work.
+
The GRAMPS application takes its working language from the System Preferences - International (Languages & Text in Snow Leopard) settings. It will search the list in order and select the first one for which there is a Gramps translation.
 
 
The GRAMPS application takes its working language from the System Preferences - International settings for the Desktop. If the list of desired languages there shows Esperanto - Russian - French - English then GRAMPS should work in Esperanto. If that translation isn't available for a particular phrase, it should produce Russian. If that's not available for a particular phrase (in the place completion tool, for example) then GRAMPS should produce French, and then eventually English.
 
  
 
The plugins directory of the .gramps user directory should be visible in Finder using the gramps_user_directory described below for backup. Placing plugins in there should work for most existing plugins, and can be done with the Finder straight from a download.
 
The plugins directory of the .gramps user directory should be visible in Finder using the gramps_user_directory described below for backup. Placing plugins in there should work for most existing plugins, and can be done with the Finder straight from a download.
Line 27: Line 30:
 
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.
 
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.openoffice.org/ OpenOffice] and [http://www.graphviz.org/ Graphviz] to produce reports, but they are both straightforward.
+
GRAMPS doesn't use the X11 Mac package. It's useful to install [http://www.openoffice.org/ OpenOffice] (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.
  
 
== A Note on Backups ==
 
== A Note on Backups ==
  
The first binary GRAMPS is built from gramps-3.1.2. If this reads an existing database from an earlier version of GRAMPS (like Macports) it will demand to do a database conversion, and there is no way to reverse this step. It is thus good practice when installing this binary GRAMPS on a system with an existing gramps database, first, to use Apple Time Machine to create backups, and second, to set aside a specific backup of an old GRAMPS database in case anything goes badly wrong. Unfortunately, the GRAMPS database is in a hidden directory which Finder doesn't show. One way to fix this is to create a link to the database in a non-hidden file. To do this, open a unix terminal with Finder-Applications-Utilities-Terminal, and at the prompt there type
+
The first binary GRAMPS is built from gramps-3.1.2. If this reads an existing database from an earlier version of GRAMPS (like Macports) it will demand to do a database conversion, and there is no way to reverse this step. It is thus good practice when installing this binary GRAMPS on a system with an existing gramps database, first, to use Apple Time Machine to create backups, and second, to set aside a specific backup of an old GRAMPS database in case anything goes badly wrong. See the note at the top of the page for instructions.
ln -s .gramps gramps_user_directory
 
which should create a directory, gramps_user_directory, showing the GRAMPS database in Finder. (That's dot-gramps in that command!) Hitting Copy then Paste on this directory in finder will '''''not''''' create an explicit backup, it will only create a second link pointing at the original GRAMPS data! Instead, you can type
 
cp -r .gramps gramps_backup
 
It is ''unfortunate'' that the current Macports GRAMPS crashes if it is used to produce a backup archive.
 
  
 
==Bugs==
 
==Bugs==
  
Known bugs in the application are described at [[Mac gtk-osx port bugs]] and it is a good idea to look there for workaraounds. In particular, Macs with a dialect of English (like British English) as their first choice language need a tweak to keep Gramps talking English!
+
Known bugs in the 3.1.2 port are described at [[Mac gtk-osx port bugs]] and it is a good idea to look there for workaraunds. In particular, Macs with a dialect of English (like British English) as their first choice language need a tweak to keep Gramps talking English!
  
 
==Updates==
 
==Updates==
Line 45: Line 44:
 
GRAMPS stores all its internal data in ~/gramps_user_directory. So, to upgrade a binary GRAMPS application to a newer version, just throw the old application in the Trash. Everything in ~/gramps_user_directory will still be there. Download the new version of the application and just use it. It will use all the old data still stored in ~/gramps_user_directory. 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. GRAMPS binary applications are labeled with a version string, -macnn, which can be seen by selecting the application package and choosing Get Info from the context (right-click) menu.
 
GRAMPS stores all its internal data in ~/gramps_user_directory. So, to upgrade a binary GRAMPS application to a newer version, just throw the old application in the Trash. Everything in ~/gramps_user_directory will still be there. Download the new version of the application and just use it. It will use all the old data still stored in ~/gramps_user_directory. 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. GRAMPS binary applications are labeled with a version string, -macnn, which can be seen by selecting the application package and choosing Get Info from the context (right-click) menu.
  
== How the Apple binary application works ==
+
== How the Apple application bundle works ==
The application called GRAMPS on the desktop is actually a complete directory hierarchy called gramps.app stored in the directory ~/Desktop, where ~ is the home directory of the logged-in user. The contents of the application directory hierarchy can be seen in finder by selecting the application and choosing Show Package Contents from the context (right-click) menu. Using cd and ls in a shell at a unix terminal, the "hidden" contents of the package are actually always visible and not hidden at all.
+
What looks like a single file called Gramps (or Gramps.app if you have extensions turned on in Finder preferences) is really a special folder called a bundle. Inside this folder is everything Gramps needs which isn't provided by OSX. The contents of the application directory hierarchy can be seen in finder by selecting the application and choosing Show Package Contents from the context (right/control-click) menu. The contents are only hidden in Finder. If you're comfortable with the terminal command line, you likely already know that application bundles show up as directories when you list them.
  
 
GRAMPS is a Python interpreted application and changing the program requires no build step. It's possible to change the downloaded binary application by choosing Show Package Contents in Finder, navigating in Finder to the GRAMPS Python code in gramps.app/Contents/Resources/share/gramps, and choosing Open With... TextEdit for the .py file to change. (There seems to be a bug in the Mac implementation of the Python runtime editor "Idle". Opening the .py file with that doesn't work.) Editing the .py file and saving the new version will cause GRAMPS to use it next time it is started. It won't change a GRAMPS which is currently running. There are .pyc files also stored in the application, compiled Python byte-code, which can be ignored.
 
GRAMPS is a Python interpreted application and changing the program requires no build step. It's possible to change the downloaded binary application by choosing Show Package Contents in Finder, navigating in Finder to the GRAMPS Python code in gramps.app/Contents/Resources/share/gramps, and choosing Open With... TextEdit for the .py file to change. (There seems to be a bug in the Mac implementation of the Python runtime editor "Idle". Opening the .py file with that doesn't work.) Editing the .py file and saving the new version will cause GRAMPS to use it next time it is started. It won't change a GRAMPS which is currently running. There are .pyc files also stored in the application, compiled Python byte-code, which can be ignored.
Line 64: Line 63:
 
==Building GRAMPS from Scratch==
 
==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.
+
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.
 +
 
 +
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])
 +
(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 you're 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 gtk-osx-build project from the Gtk-OSX git repository:
 +
<tt>git clone git://github.com/jralls/gtk-osx-build.git</tt>
 +
That will make a current copy of 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
 +
  jhbuild build gettext-fw
 +
  jhbuild --moduleset=gtk-osx-build/projects/gramps/gramps.modules build berkeleydb
 +
  jhbuild build python
 +
  jhbuild --moduleset=gtk-osx-build/projects/gramps/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=gtk-osx-build/projects/gramps/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.
  
To build GRAMPS from scratch, click on an entry from the [http://www.gramps-project.org/apple/ download page] like gramps-3.1.2-mac13-builder.zip. The builder files are build environments. The downloaded builder file when uncompressed will produce a directory called gramps_important_info. This is intended to be saved at ~/gramps_important_info, where ~ is the home directory of the logged-in user. It's possible to download the builder file with any browser and to uncompress it and move it to ~/ and then to execute ~/gramps_important_info/build_gramps (by double-clicking it) entirely from within Finder. build_gramps should download a bunch of stuff (It may hang up if any of the required webservers are down) and build it. build_gramps does everything needed to build GRAMPS (provided Apple Xcode tools are installed).
+
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.
  
build_gramps uses the [http://library.gnome.org/devel/jhbuild/unstable/ jhbuild] system to fetch code and compile it. 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, without admin privilege, and log in to that account to fetch and run build_gramps. Admin access is not required to build GRAMPS from scratch: no sudo.
+
== 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.
  
jhbuild is installed in ~/Source, and produces a binary which appears in ~/bin. jhbuild then puts everything it is building in ~/gtk (controlled by the .jhbuildrc hidden file). ~/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. jhbuild gets its instructions on how to build things from the file ~/gramps_important_info/gramps.modules. This large file includes all the instructions to build all the libraries as well as GRAMPS itself, to avoid relying on jhbuild's own instructions, which might change with time and change a build of GRAMPS unexpectedly. The intent is that each major release of GRAMPS ported to Mac will see this gramps.modules file revisited to update build instructions for libraries to the latest stable releases.
+
You may need to edit <tt>gtk-osx-build/projects/gramps/Info.plist</tt> to update the version number and copyright information.
  
The application
+
Now open a jhbuild shell and run the bundler:
~gtk/inst/bin/gramps  
+
  jhbuild shell
can run GRAMPS straight from the build directory without any OS X packaging, provided that PATH searches ~gtk/inst/bin first to pick up the right Python. GRAMPS will not work, in this build, with the standard Apple 2.5.1 Python. jhbuild constructs a 2.6.2 Python for GRAMPS to use.
+
  ige-mac-bundler gtk-osx-build/projects/gramps/gramps.bundle
 +
  
build_gramps goes on to produce an application package on the desktop. It does this just by copying the relevant files, and creating some symbolic links in the target. The files come either from ~/gtk/inst, or from ~/gramps_important_info. It's a fairly ad hoc procedure. It's possible some critical Python file or compiled C library is missed out of the application and will only be discovered later. This is to reduce the download size.
+
You'll have an application bundle named Gramps.app on your desktop.
  
Finally, build_gramps creates a pair of zipped files, the zipped packaged application for download, and the zipped gramps_important_info directory for building.
+
== 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.
  
The version macnn which is given to the files (and to the file info for the packaged application) is taken from the file ~/gramps_important_info/built_version. To create a different built version (version 0 for testing, perhaps) invoke build_gramps from a command line with a single argument:
+
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.
* build_gramps 0
 
  
 
Good Luck!
 
Good Luck!

Revision as of 19:52, 16 October 2010


Notice: this page describes the GTK-OSX port of GRAMPS to Mac, which has not been thoroughly tested. Everything should work just as it does on Linux, but you are encouraged to make backups to protect your data. Time Machine will do very nicely.

Notice: This page is in transition at the moment; a new set of binaries for 3.2.4 will be available shortly. The build instructions will be changed first, as they will enable you to build your own 3.2.4 bundle from sources. Most of issues below apply only to the 3.1.2 build and have been corrected for 3.2.4.

Note: The 3.1.2 installer left out two files:

  1. _strptime.py. You can get the file from here.
  2. keysyms.py. You can get the file from here.

The GTK-OSX port of GRAMPS for Mac is a single, stand-alone bundle which uses the native quartz windowing system instead of X11.

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.

How to Download and run the binary GRAMPS application for Mac

Back up your databases: Unless you've changed the location in Preferences, they're in a hidden folder in your home directory called ".gramps". If you already know about such things, great, just copy the "grampsdb" subdirectory somewhere else before starting. If you've never heard of hidden folders, here's how to back it up: 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".) A new Finder window will open, and you can option-drag the grampsdb folder somewhere else for safety.

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. In this case, open the .gramps folder just like above, but 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 run the binary application, visit the download page and click on the latest download. The download name gramps-x.y.z-macnn-Intel.zip specifies the version of GRAMPS from which the build was made, and a "macnn" version which changes whenever a minor bug fix is made to the Apple binary, and the processor (Intel or PPC) on which the program will run. The gramps-x.y.z-macnn-builder.zip files are the build environments to build each version from scratch, which can be ignored if only the binary application is needed. It's possible to download and run the binary application to a Mac without any Mac admin privileges, and with a Mac using only the programs supplied straight out of the box.

Any browser on the Mac will download the binary application, and depending on how it's configured, uncompress it and store it, usually in the Downloads stack. If it doesn't uncompress (it's still called .zip instead of GRAMPS with a pretty family tree icon) then double-clicking it should turn it into GRAMPS. Like any app bundle, it can be dragged anywhere you like (or even left in your downloads folder). If you drag it to the Dock, it won't move the actual bundle, but you'll always have it available to launch.

The GRAMPS application takes its working language from the System Preferences - International (Languages & Text in Snow Leopard) settings. It will search the list in order and select the first one for which there is a Gramps translation.

The plugins directory of the .gramps user directory should be visible in Finder using the gramps_user_directory described below for backup. Placing plugins in there should work for most existing plugins, and can be done with the Finder straight from a download.

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 OpenOffice (or NeoOffice, a more mac-friendly version) and Graphviz to produce reports, but they are both straightforward.

A Note on Backups

The first binary GRAMPS is built from gramps-3.1.2. If this reads an existing database from an earlier version of GRAMPS (like Macports) it will demand to do a database conversion, and there is no way to reverse this step. It is thus good practice when installing this binary GRAMPS on a system with an existing gramps database, first, to use Apple Time Machine to create backups, and second, to set aside a specific backup of an old GRAMPS database in case anything goes badly wrong. See the note at the top of the page for instructions.

Bugs

Known bugs in the 3.1.2 port are described at Mac gtk-osx port bugs and it is a good idea to look there for workaraunds. In particular, Macs with a dialect of English (like British English) as their first choice language need a tweak to keep Gramps talking English!

Updates

GRAMPS stores all its internal data in ~/gramps_user_directory. So, to upgrade a binary GRAMPS application to a newer version, just throw the old application in the Trash. Everything in ~/gramps_user_directory will still be there. Download the new version of the application and just use it. It will use all the old data still stored in ~/gramps_user_directory. 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. GRAMPS binary applications are labeled with a version string, -macnn, which can be seen by selecting the application package and choosing Get Info from the context (right-click) menu.

How the Apple application bundle works

What looks like a single file called Gramps (or Gramps.app if you have extensions turned on in Finder preferences) is really a special folder called a bundle. Inside this folder is everything Gramps needs which isn't provided by OSX. The contents of the application directory hierarchy can be seen in finder by selecting the application and choosing Show Package Contents from the context (right/control-click) menu. The contents are only hidden in Finder. If you're comfortable with the terminal command line, you likely already know that application bundles show up as directories when you list them.

GRAMPS is a Python interpreted application and changing the program requires no build step. It's possible to change the downloaded binary application by choosing Show Package Contents in Finder, navigating in Finder to the GRAMPS Python code in gramps.app/Contents/Resources/share/gramps, and choosing Open With... TextEdit for the .py file to change. (There seems to be a bug in the Mac implementation of the Python runtime editor "Idle". Opening the .py file with that doesn't work.) Editing the .py file and saving the new version will cause GRAMPS to use it next time it is started. It won't change a GRAMPS which is currently running. There are .pyc files also stored in the application, compiled Python byte-code, which can be ignored.

The binary GRAMPS application contains not only the GRAMPS Python sources and all their internationalised translations, but also a complete Python 2.6.2 interpreter, and the Python code libraries distributed with that, and the compiled C libraries for graphics features like gtk, glade and pango. These are all fixed for a particular version of the distributed binary application. The only way to change them is to download a new distributed binary GRAMPS application. This is intended to fix a major issue with earlier GRAMPS Mac implementations, where the program depended on so many different distributions that were always changing that determining what change introduced what bug was very hard.

One downside of the way that Mac packages work is that, to achieve a reasonable download size, some libraries and programs are missed out of the packaged application. This can cause GRAMPS crashes, or sometimes just cause some program features to be missing. Crashes of the packaged application usually produce messages on the console, which can be seen (even after the crash has finished) by choosing Finder-Applications-Utilities-Console. There is a delay of perhaps up to a minute between the crash occurring and the messages appearing on the console.

A simpler way to see messages from GRAMPS, should any appear, is to start it from a unix terminal. To do this, open a terminal with Finder-Applications-Utilities-Terminal, and type (for a GRAMPS application on the Desktop)

cd / ; ~/Desktop/gramps.app/Contents/MacOS/gramps

and that should run GRAMPS and produce any messages with no delay. The file ~/Desktop/gramps.app/Contents/MacOS/gramps is a shell script, as is ~/Desktop/gramps.app/Contents/MacOS/gramps-bin which it calls. gramps-bin calls the Python 2.6.2 interpreter ~/Desktop/gramps.app/Contents/MacOS/python to run the GRAMPS code which is stored in ~/Desktop/gramps.app/Contents/Resources/share/gramps. Local translations are stored in ~/Desktop/gramps.app/Contents/Resources/share/locale. Standard python code is in ~/Desktop/gramps.app/Contents/Resources/lib/python2.6, and the compiled C libraries are in ~/Desktop/gramps.app/Contents/Resources/lib/*.dylib. Only the GRAMPS Python source is shipped in the binary application. If other sources are needed, the GRAMPS build environment must be used.

Should GRAMPS produce a message indicating that it crashed because it could not find a particular library or source file, then do please post a message on the GRAMPS users or developers mailing list, or post a bug. These tedious issues are usually easy to fix. Packaging GRAMPS like this (as opposed to including everything and the kitchen sink) reduces the download size by more than a factor of three.

The binary application is built by downloading a Whole Pile of programs from various places on the web (about forty programs) and building each of them to produce a utility to help building, or a library, or something. Just one of these applications is the GRAMPS code developed with such effort by the GRAMPS developers, so it's clear just how much work has gone into the whole thing.

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. 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 Apple, though you must register as a Mac developer.

Next, read the build instructions for Gtk-OSX, especially the Prerequisites. Download and run the 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 sdk_setup looks like

 setup_sdk(target="10.5", sdk_version="10.5", 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 you're 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 gtk-osx-build project from the Gtk-OSX git repository: git clone git://github.com/jralls/gtk-osx-build.git That will make a current copy of 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
 jhbuild build gettext-fw
 jhbuild --moduleset=gtk-osx-build/projects/gramps/gramps.modules build berkeleydb
 jhbuild build python
 jhbuild --moduleset=gtk-osx-build/projects/gramps/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=gtk-osx-build/projects/gramps/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.

Bundling

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

You may need to edit gtk-osx-build/projects/gramps/Info.plist to update the version number and copyright information.

Now open a jhbuild shell and run the bundler:

 jhbuild shell
 ige-mac-bundler gtk-osx-build/projects/gramps/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!