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

From Gramps
(How the binary application works)
 
m (→‎If something seems to go wrong)
 
(118 intermediate revisions by 13 users not shown)
Line 1: Line 1:
−
'''Warning:''' this page describes the GTK-OSX port of Gramps to Mac, which is still under test. This page too is stil under construction. The program described may not work as expected. Or even work. Use it on precious data at your own risk!
+
[[File:macos_200x200.png|128px|right|link=Download#Mac_OS_X]]
 +
Installation of the ready-to-run Gramps application for [https://en.wikipedia.org/wiki/MacOS macOS] (originally Mac OS X, previously shortened as 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 macOS instead of X11.
  
−
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.
+
== Before installation ==
  
−
At the moment (July 27 2009) Mac 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.
+
{{man tip|Apple ''macOS versions'' |*Gramps 5.0 requires Mac OS X 10.9 (Mavericks) and later.
 +
*Gramps 5.1 requires Mac OS X 10.10 (Yosemite) and later.
 +
*Gramps 6.0 requires macOS 11.0 (Big Sur) and later.
 +
<br>
 +
(5-year support window for the macOS dependencies)}}
  
−
To run the binary application, visit the [http://www.gramps-project.org/apple/ download page] and click on the latest download. The download name specifies the version of Gramps from which the build was made, and a final "macnn" version which changes whenever a minor bug fix is made to the Apple binary. 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. Gramps doesn't use the X11 Mac package. It's useful to install [http://www.openoffice.org/ OpenOffice] and <that graph-drawing thing> to produce reports, but they are both straightforward.
+
;'''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 <code>Library/Application Support/gramps/grampsdb</code>. (Right click/option click and select "Make a copy" from the menu. It will be named <code>grampsdb(2)</code>.
  
−
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 comvenience, or stored in the Applications folder.
+
;'''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 <code>Library/Application Support/gramps</code> 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 "<code>.gramps</code>". Select a Finder window and select Go>Go to Folder from the menu. Type "<code>/Users/yourname/.gramps</code>" 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 <code>Library/Application Support</code> (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.
  
−
Double-clicking on the gramps application should launch Gramps. It Should Just Work.
+
{{man note|''Migrating to [https://en.wikipedia.org/wiki/Mac_transition_to_Apple_silicon Apple Silicon]?''|Make an [[How_to_make_a_backup|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.}}
  
−
The first binary gramps is version 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, 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
+
== Installing Gramps ==
−
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 create an explicit backup, gramps_user_directory copy. [Does this actually work with a symbolic link? I'm not at a Mac to try it!] It is ''unfortunate'' that the current Macports gramps crashes if it is used to produce a backup archive.
 
  
−
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 - Dutch - 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. As of July 2009, there is a bug if the Desktop is set to British English or any other subdialect. A safe workaround is to use System Preferences to list English as the preferred language straight after British (etc) English. As of July 2009, there is a bug in the Hebrew version. It crashes. All other existing versions seem to work.
+
From the '''[[Download#macos]]''' 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.
  
−
Known bugs in the application (as of the mac13 version) include:
+
'''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.
−
* 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 and restart it.
 
−
* Using the Apple conventional menu (the one at the top left of the screen, not the one attached to the Gramps main window) to try to exit gramps by picking gramps-close does not work. Clicking the red button at the top left of the Gramps main window does work.
 
−
* Gramps crashes in Hebrew. A workaround is to avoid using Hebrew.
 
−
* Gramps produces strange mixtures of languages if the first entry on the list of preferred languages is a dialect of English for which Gramps has no translation and the second is a language for which 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. Gramps is written in a highly international version of English so this should inconvenience noone!
 
−
* 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 gramps. Exactly how this happens is obscure. A workaround is to restart gramps if it crashes. Dragging and dropping with care at a reasonable speed is suggested.
 
  
−
The plugins directory of the .gramps user directory should be visible in Finder using the gramps_user_directory described above for backup. Placing plugins in there should work for most existing plugins, and can be done with the Finder straight from a download.
+
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.
  
−
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 shold 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.
+
== 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 <code>/Users/<username>/Library/Application Support/gramps/grampsdb</code>
 +
* Setting files (ini-files) are found here: <code>/Users/<username>/Library/Application Support/gramps/gramps51</code>
 +
* 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 <code>Contents/MacOS/Gramps</code>.
  
−
== How the Apple binary application works ==
+
== Advanced setup ==
−
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 View 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 is a Python interpreted application and changing the program requires no build step. It's possible to change the downloaded binary application by choosing View Package COntents in Finder, navigating to the gramps Python code in gramps.app/Contents/Reources/share/gramps in Finder, 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.
+
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.
  
−
The binary gramps application contains not only the gramps Python sources and all their internationalised trasnlations, 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 applciation. 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 implementation, where the program depended on so many different distributions that were always changing that determining what change introduced what bug was very hard.
+
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.  
  
−
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 applciation. This can cause gramps crashes, or sometimes just cause some program features to be missing. Crashes of the packaged applciation usually produce messages on the console, which can be seem (even after the crash has finished) by choosing Finder-Utilities-Console [Is that System Console? I'm not at a Mac] There is a delay of perhaps up to a minute between the crash occurring and the messages appearing on the console.
+
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
  
−
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-Utilities-Terminal, and type (for a gramps application on the Desktop)
+
The settings are stored in ~/Library/Preferences/org.gramps-project.gramps.plist
−
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.
 
  
−
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.
+
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  [https://en.wikipedia.org/wiki/MySpell 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://archive.services.openoffice.org/pub/mirror/OpenOffice.org/contrib/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).
 +
 
 +
== Bugs ==
 +
 
 +
=== If something seems to go wrong ===
 +
 
 +
You'll find error messages in the console log, which you can view with <code>/Applications/Utilities/Console.app</code>
 +
 
 +
All of the known bugs in previous version have been corrected in Gramps {{Version_Mac}} and later. There will no doubt be new ones; report them in the usual way on [https://gramps-project.org/bugs/my_view_page.php MantisBT] ([[Using the bug tracker]] instructions). When reporting what you're sure is an macOS 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 <code>~/Library/Application Support</code>. 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.
 +
 
 +
[[Category:Developers/Packaging]]
 +
[[Category:Documentation]]

Latest revision as of 07:46, 23 September 2025

Macos 200x200.png

Installation of the ready-to-run Gramps application for macOS (originally Mac OS X, previously shortened as 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 macOS instead of X11.

Before installation

Tango-Dialog-information.png
Apple macOS versions
  • Gramps 5.0 requires Mac OS X 10.9 (Mavericks) and later.
  • Gramps 5.1 requires Mac OS X 10.10 (Yosemite) and later.
  • Gramps 6.0 requires macOS 11.0 (Big Sur) and later.


(5-year support window for the macOS dependencies)


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#macos 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 6.0.8 and later. There will no doubt be new ones; report them in the usual way on MantisBT (Using the bug tracker instructions). When reporting what you're sure is an macOS 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.

Retrieved from "https://ftp.gramps-project.org/wiki/index.php?title=Mac_OS_X:Application_package&oldid=124432"