Jump to: navigation, search

Mac OS X:Application package

No change in size, 14:00, 30 July 2009
GRAMPS (great work, congratulations)
'''Warning:''' this page describes the [ GTK-OSX] port of Gramps 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!
The GTK-OSX port of Gramps 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.
At the moment (July 27 2009) Mac Gramps GRAMPS is only available built for Intel Macs. It should build happily on PPC Macs, but has not been tried. 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. 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.
== How to Download and run the binary gramps GRAMPS application for Mac ==
If there is an existing Gramps GRAMPS database, it is wise to create a backup archive of an existing Gramps GRAMPS database before trying a new program, as described in the note on backups below. Gramps GRAMPS for Mac is still new and untested. Take care!
To run the binary application, visit the [ download page] and click on the latest download. The download name specifies the version of Gramps 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. '''Sorry,''' only Intel is available yet. The 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 GRAMPS with a pretty family tree icon) then double-clicking it should turn it into grampsGRAMPS. It can be dragged to the Desktop for comvenienceconvenience, or stored in the Applications folder.
Double-clicking on the gramps GRAMPS application should launch GrampsGRAMPS. It Should Just Work.
The gramps 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 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 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.
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 GRAMPS doesn't use the X11 Mac package. It's useful to install [ OpenOffice] and [ Graphviz] to produce reports, but they are both straightforward.
== A Note on Backups ==
The first binary Gramps GRAMPS is built from gramps-3.1.2. If this reads an existing database from an earlier version of gramps 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 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 GRAMPS database in case anything goes badly wrong. Unfortunately, the gramps 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
ln -s .gramps gramps_user_directory
which should create a directory, gramps_user_directory, showing the gramps 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 GRAMPS data! Instead, you can type
cp -r .gramps gramps_backup
It is ''unfortunate'' that the current Macports gramps GRAMPS crashes if it is used to produce a backup archive.
Known bugs in the application (as of the mac13 version) include:
* The export-archive wizard window refuses to close when it has finished. In fact, the archive should be perfect, it's just the window that won't close. A workaround is to exit gramps GRAMPS and restart it.* Using the Apple conventional menu (the one at the top left of the screen, not the one attached to the Gramps GRAMPS main window) to try to exit gramps GRAMPS by picking gramps-close does not work. Clicking the red button at the top left of the Gramps GRAMPS main window does work.* Gramps GRAMPS crashes in Hebrew. A workaround is to avoid using Hebrew.* Gramps GRAMPS produces strange mixtures of languages if the first entry on the list of preferred languages is a dialect of English for which Gramps GRAMPS has no translation and the second is a language for which gramps GRAMPS does have a translation. A workaround is to list English (as opposed to a regional version of English) immediately after the dialect in the language preference table with System Preferences - International. For example, a sensible choice for a language preference list might be "British English" - "English" - "Francais". Gramps GRAMPS is written in a highly international version of English so this should inconvenience nooneno one!
* Dropping a jpeg file from the Desktop onto an empty media gallery doesn't work. A workaround is to use the "+" button of the media gallery to add it instead. Once the media gallery has at least one entry, dropping a jpeg (etc) onto it should create a new media object present in the gallery.
* Dropping a jpeg (etc) file with spaces in the pathname (and other strange characters too) onto a media gallery doesn't work. A workaround is to use the "+" button of the media gallery to add it instead.
* Dragging and dropping images quickly and carelessly around a media gallery page can crash grampsGRAMPS. Exactly how this happens is obscure. A workaround is to restart gramps GRAMPS if it crashes. Dragging and dropping with care at a reasonable speed is suggested.
Gramps GRAMPS stores all its internal data in ~/gramps_user_directory. So, to upgrade a binary Gramps 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 GRAMPS binary applications are labelled 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 ==
The application called gramps GRAMPS on the desktop is actually a complete directory hierarchy called 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.
Gramps 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 GRAMPS Python code in, 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 GRAMPS to use it next time it is started. It won't change a Gramps 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 GRAMPS application contains not only the gramps 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 GRAMPS application. This is intended to fix a major issue with earlier Gramps 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 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 GrampsGRAMPS, 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 GRAMPS application on the Desktop)
cd / ; ~/Desktop/
and that should run Gramps GRAMPS and produce any messages with no delay. The file ~/Desktop/ is a shell script, as is ~/Desktop/ which it calls. gramps-bin calls the Python 2.6.2 interpreter ~/Desktop/ to run the gramps GRAMPS code which is stored in ~/Desktop/ Local translations are stored in ~/Desktop/ Standard python code is in ~/Desktop/, and the compiled C libraries are in ~/Desktop/*.dylib. Only the Gramps GRAMPS Python source is shipped in the binary application. If other sources are needed, the gramps GRAMPS build environment must be used.
Should Gramps 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 GRAMPS users or developers mailing list, or post a bug. These tedious issues are usually easy to fix. Packaging Gramps 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 GRAMPS code developed with such effort by the Gramps GRAMPS developers, so it's clear just how much work has gone into the whole thing.
==Building Gramps GRAMPS from Scratch==
Building Gramps 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 GRAMPS uses, like gtk.
To build gramps GRAMPS from scratch, click on an entry from the [ download page] like 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 GRAMPS (provided Apple Xcode tools are installed).
build_gramps uses the [ 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 GRAMPS from scratch: no sudo.
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 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 GRAMPS itself, to avoid relying on jhbuild's own instructions, which might change with time and change a build of Gramps GRAMPS unexpectedly. The intent is that each major release of Gramps GRAMPS ported to Mac will see this gramps.modules file revisited to update build instructions for libraries to the latest stable releases.
The application ~gtk/inst/bin/gramps can run Gramps 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 GRAMPS will not work, in this build, with the standard Apple 2.5.1 Python. jhbuild constructs a 2.6.2 Python for Gramps GRAMPS to use.
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.

Navigation menu