MacOS/Quartz

Downloads

Gnucash-Intel-2.4.0 and Gnucash-PPC-2.4.0 are now available as a binary download from the Gnucash project at Sourceforge. Release notes are included in the disk-image. MacOSX 10.5 (Leopard) or higher is required to run Gnucash. For virtually all users it is more appropriate to download the binary rather than to use the procedure described here.

Overview

GnuCash can be built to run more or less natively on OSX -- meaning without X11. Better yet, the build is almost automatic.

You can do this also with MacPorts: The details are described at MacOSX/MacPortsDetail. If you already have MacPorts installed, you should use that procedure, as gtk-osx doesn't work well with a MacPorts installation.

If you want to have a clickable GnuCash.app to put in your Applications folder, this is the solution to use. If you want to be able to easily customize your installation, this is also the solution for you. Don't want all of the extra stuff that MacPorts drags in? Well, this might be a bit better... but GnuCash is notorious for its huge list of dependencies. Want to keep up with the latest work from the Gnome developers? You can set up this solution to get many of its packages directly from source-code-control. That's a double-edged sword, of course, because if a build gets broken, you're pretty well stuck until the developers for that package fix it.

This build now integrates Gnucash menus with the mac menubar at the top of the screen. About, Preferences, and Quit are in the "GnuCash" menu (it's named "gnucash-bin" when you run from the command line) in standard Mac style. Standard accelerator keys like Command-Q (quit), Command-S (save), and Command-O (Open) now work as well. A patch to Gtk+ now allows copy and paste in the register pages.

The build scripts have been tested on Leopard running on Intel and Tiger running on PowerPC.

Support

This procedure is related to the GTK-OSX project at SourceForge, http://gtk-osx.sourceforge.net/ There is a forum, a users mailing list, and a tracker for bugs, patches, and enhancement requests. If you have problems or suggestions, that's the place to go. Questions, comments, or suggestions about Gnucash should be directed to the appropriate Gnucash mailing list (gnucash-devel for development versions (2.5.x) or gnucash-user for release versions (2.2.x or 2.4.x).)

Preliminaries

Leopard or newer is required for Gnucash. Gtk-osx will build for Tiger, but Gnucash uses WebKitGtk which won't build on Tiger.

This procedure uses GTK-OSX, which in turn uses a program called jhbuild.

Download .jhbuildrc-custom into your home directory. It reconfigures jhbuild for building gnucash.

Note that by default, jhbuild will put everything into your home directory. If you prefer to build and install into /usr/local, you can do so by editing the prefix line at the top of .jhbuildrc-custom. You can change it to whatever you like -- or leave it as it is. If you use the /usr/local/gtk and /usr/local/src/gnome settings, you will need to create them and chmod them with sudo before you can use them, of course.

Go to the GTK-OSX Build Instructions and follow the instructions up through running jhbuild bootstrap.

You also need to $> mkdir $PREFIX/tmp

Building

Once all of the preliminaries are complete, run:

$> jhbuild build

Building Unstable Versions

By default, the .jhbuildrc-custom file will build the stable release of Gnucash into ~/gnucash-stable. If you want to build unstable or svn trunk versions of Gnucash, edit .jhbuildrc-custom as follows:

Comment out the line prefix = os.path.join(os.environ["HOME"], "gnucash-stable") and uncomment the line #prefix = os.path.join(os.environ["HOME"], "gnucash-unstable")

Similarly, comment out the line modules = ["meta-gtk-osx-bootstrap", "meta-gtk-osx-core", "gnucash"] and uncomment the one that you want to build (gnucash-unstable or gnucash-svn).

jhbuild build as before.

Note: Because of code in WebkitGTK, Gnucash requires Leopard (OSX 10.5) or Snow Leopard (10.6) to build. To get around this, you'll have to clone the gnucash-on-osx repository, edit gnucash.modules so that gnucash-unstable and gnucash-svn use the same dependencies as gnucash and to use --with-html-engine="gtkhtml", change the moduleset line in .jhbuildrc-custom to point to your local version, and then build. If that sounds too daunting then it probably is.

Customizing the Configuration

To add configure arguments (e.g., --enable-dbi), add a line

module_autogenargs["gnucash"]="--enable-dbi"

with whatever arguments you want to supply. Note that in order to turn off something that's on by default, you can use (e.g.) --disable-aqbanking. Change gnucash to gnucash-svn if that's what you're building.

Building Libdbi Drivers

Even though libdbi supports other databases, each one requires custom initialization code in Gnucash, and Gnucash has that code only for Sqlite3, MySql, and Postgresql.

The distributed bundles don't include libdbi-drivers for MySql or Postgresql. If all you need to do is add a driver, instead of

 jhbuild build

you can

 jhbuild build libdbi-drivers

First, though, you need to add the following to your .jhbuildrc-custom:

 module_autogenargs['libdbd-drivers']='--with-sqlite3 --disable-docs --with-sqlite3-incdir="/usr/include" --with-sqlite3-libdir="/usr/lib"'

substituting mysql or pgsql for sqlite3, and using the correct paths to the include and library files for the DBMS you want to use.

This is theoretically possible without gtk-osx using the already-installed libtool, autoconf, and automake, but there are some problems with glibtool provided by Apple, so it's much easier to just use gtk-osx.

You can copy the driver file (which will be named libdbdmysql.so or libdbdpgsql.so) to Gnucash.app/Contents/Resources/lib/dbd. There's one last task:

 installed_name_tool -change /prefix/path/lib/dbd/libdbi.0.dylib  @executable_path/../Resources/lib/libdbi.0.dylib Gnucash.app/Contents/Resources/lib/dbd/libdbdmysql.so 

substituting pgsql for mysql if that's appropriate and putting in the actual path (which you can see with otool -L for /prefix/path.

Documentation

The gnucash documentation is online, of course, but if you want a local copy, you can build the modules gnucash-docs or gnucash-docs-svn. Just add whichever one you want to your "modules" argument.

Debugging

To get a debugging build, add the line setup_debug() to .jhbuildrc-custom. Beware, though, that WebKit doesn't build with debugging enabled. I usually build everything first without debugging enabled, then enable it and rebuild (jhbuild buildone --force --clean) the packages I want to debug. Most of the time you can get by with just glib and gnucash, but depending on what you're working on, you might also want gtk+, gwenhywfar, aqbanking, or libdbi.

Running from the commandline

Now you're ready to try it out:

$ $PREFIX/bin/gnucash

($PREFIX is the path to where you've built gtk; you can fill it in yourself or use jhbuild shell to set it for you.)

Making a Bundle

So far so good, but you don't really want to have to open a Terminal window every time you want to use GnuCash, now do you? Of course not. You want a nice icon in your Applications folder (and maybe in the Dock) to click on when you run GnuCash. Here's how to do this:

Download the bundler from http://downloads.sourceforge.net/sourceforge/gtk-osx/ige-mac-bundler-0.5.2.tar.gz, unpack it, cd into the ige-mac-bundler directory, and make install

Download http://downloads.sourceforge.net/sourceforge/gtk-osx/gnucash-bundler-1.0.3.tar.gz and unpack it.

cd gnucash-bundler

Look through gnucash-launcher and gnucash.bundle and adjust the paths to match your installation.

make gnucash-launcher executable (chmod +x gnucash-launcher)

execute jhbuild shell to set up the environment for the bundler

export PATH=$PREFIX/bin:$PATH because jhbuild shell doesn't do this for some reason

ige-mac-bundler gnucash.bundle

exit

And your bundle should be ready to go. Try GnuCash.app/Contents/MacOSX/GnuCash from the command-line so that you can see any error messages. If that works, try open GnuCash.app. If that works, then you can move GnuCash.app to your Applications folder and it's ready to use. (If it doesn't, error messages are written to the console log. You can run IGE_DEBUG_LAUNCHER=1 open Gnucash.app to see what the launcher script is doing wrong.) Don't move or remove the installation directory (~/gtk/inst by default): Both dbus and GnuCash have links pointing into it which can't at present be changed.

Bundling Unstable and Svn

Similarly, the bundle, Info.plist, and launcher scripts change frequently, so you'll need to either clone git://github.com/jralls/gnucash-on-osx.git or download gnucash-unstable.bundle, Info-unstable.plist, and gnucash-unstable.launcher. They all need to be in the same directory, and you'll run ige-mac-bundler /path/to/gnucash-unstable.bundle.

Documentation: The bundle includes documentation. If you've built it, great, no problem. You need to have it installed for the Help menu items to work. If you didn't build it and you don't want to, then comment out or remove the lines

 
   ${prefix}/share/gnome/help/gnucash/C/gnucash-help
 

 
   ${prefix}/share/gnome/help/gnucash/C/gnucash-guide/
 

  
   ${prefix}/share/gnome/help/gnucash/de_DE/gnucash-help
 

 
   ${prefix}/share/gnome/help/gnucash/de_DE/gnucash-guide/
 

 
   ${prefix}/share/gnome/help/gnucash/it_IT/gnucash-help
 

 
   ${prefix}/share/gnome/help/gnucash/it_IT/gnucash-guide/
 

 
   ${prefix}/share/gnome/help/gnucash/ja_JP/gnucash-guide/
 

To comment out XML code, surround it like so: Note that comments cannot contain "--".

Making a distribution

• On both an Intel and a PowerPC mac, make a clean build including the documentation, making sure that you're not building any libraries with debugging. With all of the dependencies, the package is huge enough without it. Make sure that you're using the latest git masters from git://github.com/jralls for ige-mac-bundler and gnucash-on-osx.
• Edit the version numbers and, if necessary, the copyright dates in Info.plist (or Info-unstable.plist).
• Make a bundle as described above. Test it.
• Download the previous version's .dmg; it has two scripts that you'll need, along with the files License.txt and Sources.txt.
• Make a directory named for the version that you're going to distribute and move the new bundle into it.
• Copy the scriptlets "FinanceQuote Update.app" and "Update Dirs.app" along with the files "License.txt" and "Sources.txt" from the previous version .dmg to the new distribution folder.
• Go to the wiki and copy the previous version's release note (e.g., MacOSX/Readme/2.3.14) to a new one titled with the new version. Edit it as appropriate and save it. Select the "Printable Version" link on the menu on the left side and print that as a pdf to "Gnucash OSX Readme.pdf" in your distribution directory, then save it as a text file somewhere convenient.
• Open /Applications/Utilities/Disk Utility.app and select File>New>Disk Image from Folder in the menu. Select your installation directory in the first chooser and name it appropriately in the second (if you named the folder correctly, you won't have to change anything).
• Edit the text version of the Readme to remove the cruft that the wiki software sticks at the bottom and the link tags in the table of contents at the top.
• Upload both the resulting .dmg and the text version of the Readme to the correct version directory of Gnucash's file manager area on Sourceforge. Set the Readme to being a Release note, and set the .dmg to use it as one. If this is a stable release, check the "Mac" box on the options panel so that users viewing the project page with a mac will see the new release in the big green button.
• Update the appropriate links on the Gnucash webpage.

Known Issues

• Copying to the clipboard doesn't work in register pages; i.e., if you put a number in the wrong column and you want to cut it and paste it into a different one, it will cut fine but won't paste.
• Context Help doesn't work. Gnucash Help and the Gnucash Guide are included in the application bundle, in Contents/Resources/English.lproj, but the linkage to the help menu or to help buttons in dialogs doesn't work.
• An instance of dbus is started by the application startup script, but dbus isn't designed to be run that way, so it doesn't shut down when you close the application. There's also no way at present for a new run of Gnucash to find already-running instances of dbus. This doesn't cause any real problems, but it is a resource leak. You can periodically clean out the running dbus-daemons by either issuing "killall dbus-daemon" at a command line or by telling it to quit from /Applications/Utilities/Activity Monitor.
• The conversion of Macintosh default locale to Gtk+ is a bit primitive, and while the gnucash translation files are included, you may encounter messages from other libraries which aren't translated.
• The placement of dialog boxes which are displayed before the main window is a bit strange. The "Tip of the Day" dialog box will appear behind and a bit offset from the splash screen, and will be warped off the screen when the main window opens. The "Since last run" dialog box, used by Scheduled Transactions, will display in the center of the screen and then be hidden behind the main window. Use Exposé to find it.
• There is no theme engine in the bundle, so customizations are not supported.
• Gtk-OSX does not yet support Universal Access.
• The Dock icon is not integrated, so that attempting to quit from its context menu doesn't work.

Note that Gnucash demands a few things that Finance::Quote doesn't in order to get quotes. Run the perl program Gnucash.app/Contents/Resources/bin/gnc-fq-check to diagnose any quote problems.

Helping Out

If you can work on one of these items, please pitch in! Some are Gnucash issues, some are issues with the Quartz implementation of Gtk, and some are integration issues. Join the gtk-osx-devs mailing list to coordinate your work with others.