MacOS/Quartz

Downloads

Gnucash-Intel-2.6.17 and Gnucash-PPC-2.6.17 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.

This page describes the procedure to build GnuCash with the Quartz environment. You can also use 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.

A build will consume about 5 gigabytes of disk space and typically take several hours to run.

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.

Support

This procedure depends on the Gnome Gtk-OSX project. Support for that is provided via the gtk-osx-users-list@gnome.org mailing list. Questions, comments, or suggestions about Gnucash should be directed to the appropriate Gnucash mailing list (gnucash-devel for development versions (2.7.x, git master) or gnucash-user for release versions (2.6.x).)

Preliminaries

Read Building Gtk-OSX and scan the jhbuild docs. This procedure is based on both. Note well the warnings about Homebrew, MacPorts, and Fink! Creating a separate user for building and packaging GnuCash is the easiest work-around if you've used any of those systems in your regular userid.

First download gtk-osx-build-setup.sh by clicking the link or from the commandline:

curl -O -L https://git.gnome.org/browse/gtk-osx/plain/gtk-osx-build-setup.sh

and run it from the commandline. It will install jhbuild and do some preliminary setup.

JHBuild is configured to build GnuCash via .jhbuildrc-custom. Download this file to your home directory either by clicking the link and moving the downloaded file or from the commandline:

curl -O -L http://github.com/gnucash/gnucash-on-osx/raw/master/.jhbuildrc-custom

It's possible to build GnuCash 2.6.x and earlier on MacOS X versions 10.5 (Leopard) through 10.8 (Mountain Lion), but it's not easy. If you need to do so see Building for Older Versions of Mac OS X. The rest of this article assumes that you're running Mac OS X 10.9 (Mavericks) or later. * 10.5 and 10.6 (Leopard and Snow Leopard) won't build WebKit-1.10, so there are alternate gnucash metamodules to build WebKit-1.6 instead. If you need to build on/for either, change meta-gnucash-stable to meta-gnucash-stable-Leopard in .jhbuildrc-custom.

Make the following changes to .jhbuildrc-custom:

Operation	Line	Optional?	Details
edit	setup_sdk("10.5", "10.5",["i386"])	no	For example, if building on macOS Sierra, this line would become setup_sdk("10.12", "10.12",["i386"]). See further details below on setup_sdk.
add	skip = ["icu"]	no	This avoids a conflict with different versions of icu that different modules want to bring in. Note that this step may only be required if building gnucash-stable.
add	nice_build = False	no	Some modules make use of builtin shell commands. JHBuild will fail for these if nice_build is True. We override this default behavior.
edit	prefix = ...	yes	By default, jhbuild will download, build, and install everything into $HOME/gtk. You can change that by editing the prefix<code> line to any directory to which you have write privilege. jhbiuild will create the prefix directory but its parent directory must already exist. If you insist on using <code>/usr/local (not recommended) you'll need to sudo chmod g+x /usr/local and newgrp wheel beforehand, and you must be logged in as an admin user to do so. Run the following build commands now to avoid problems downstream: Build Command Details jhbuild build icu55 Harfbuzz requires icu in general but webkit 1 requires a specific version. Here we bring in the version webkit needs, harfbuzz will find it and use it. Note that this step may only be required if building gnucash-stable. jhbuild build openssl Module itstool needs libxml2 which won't be found unless we pre-build python, which won't work unless we pre-build openssl. If openssl build fails for you see tips on Building GTK-OSX. jhbuild build python For itstool and its usage of libxml2. Run jhbuild bootstrap to install the tools needed for the rest of the build. Building Once all of the preliminaries are complete, run: $> jhbuild build Building Unstable Versions By default, the .jhbuildrc-custom file will build the current stable release of Gnucash into ~/gnucash-stable. If you want to build unstable or git master 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", "meta-gnucash-stable"] and uncomment the one that you want to build (meta-gnucash-unstable or meta-gnucash-git). Notes Because of code in WebkitGTK, GnuCash stable requires Leopard (Mac OS X 10.5) or later to build. Because GnuCash master uses C++ fetaures that don't compile on or for earlier versions, GnuCash master requires Mavericks (MacOS X 10.9) or later. Boost is now a required dependency for the master branch. It's in the moduleset, but jhbuild doesn't know how to build it, so it must be done manually. Select [4] Start Shell to build and install boost. At the time of this writing the commands are ./bootstrap.sh ./b2 toolset=darwin address-model=32 cxxflags="$CPPFLAGS" cflags="$CPPFLAGS" linkflags="$LDFLAGS" dll-path=$PREFIX/lib -\-prefix=$PREFIX -\-build-dir=$PREFIX/../build/boost_1_56_0 for i in `ls $PREFIX/lib/libboost*`; do install_name_tool -id $i $i; done for i in `ls $PREFIX/lib/libboost*.dylib`; do for j in `ls $PREFIX/lib/libboost*.dylib`; do install_name_tool -change `basename $i` $i $j; done; done But it's always wise to check gnucash.modules for updated instructions. Look out for a comment before the boost module. Finally hit ctrl-D to return to jhbuild and select 2 three times to proceed to the next module. 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-git if that's what you're building. Note that unless you are running MacOSX 10.5 or 10.6, you will need to change both instances of "10.5" to your MacOSX version in the line setup_sdk("10.5", "10.5", ["i386"]) at the top of .jhbuildrc.custom. Note that if you have Xcode 7 (shipped with MacOS X 10.9) or later you can build for any version from 10.6 on with the included SDK by calling (e.g.) setup_sdk("10.6", native, ["i386"]) Note:The master branch is converted to a cmake module which doesn't support customization from .jhbuildrc-custom. If you need a customized build do the build manually with the cmake instructions from Building. OS X 10.11 El Capitan and Later OS X 10.11 added a security feature called System Integrity Protection or SIP. One "feature" is that it strips linker environment variables (the ones starting with LD_ and DYLD_) from the environment when a "system" program does a fork/exec. For our purposes "system program" means one installed in /bin or /usr/bin, in particular /bin/sh. The Guile compiler, guiled, is a shell script that as written uses /bin/sh to set the prefix then execs guile to run a compilation script. That fails on El Cap and presumably will on later versions too. One can get around this by disabling SIP, but that's a whole-system change that requires a reboot, and SIP clearly has significant security benefits. Don't do that. The other workaround is to use a shell that isn't in /bin or /usr/bin. One can just copy /bin/bash to one's user directory. Gtk OSX also provides a bash build in the gtk-osx-bootstrap moduleset which is skipped by default. To enable it, uncomment (or add if you're using an older version of .jhbuildrc-custom) skip.remove("bash") in .jhbuildrc-custom before starting the build. Then, when GnuCash's build fails, just edit $PREFIX/bin/guild to change the first line to #!/$PREFIX/bin/bash substituting the full path for $PREFIX. 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 You'll need the MySql or Postgresql client library and headers installed on your system. Next, add the following to your .jhbuildrc-custom: module_autogenargs['libdbi-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. Make sure this line precedes any lines adding other arguments for libdbi-drivers, like append_autogenargs("libdbi-drivers","--with-dbi-incdir=" + prefix + "/include --with-dbi-libdir=" + prefix + "/lib") 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: install_name_tool -change /prefix/path/lib/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-git. 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, unpack it, cd into the gtk-mac-bundler directory, and make install Download gnucash.bundle, Info.plist, gnucash.launcher, and gnucash.icns into the same folder. For the rest of the discussion, we'll call that folder gnucash-bundler. 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 gtk-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.) Bundling Unstable and Git Similarly, the bundle, Info.plist, and launcher scripts change frequently, so you'll need to either clone git://github.com/Gnucash/gnucash-on-osx.git or download gnucash-unstable.bundle, Info-unstable.plist, gnucash-unstable.launcher, and gnucash.icns. They all need to be in the same directory, and you'll run gtk-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 <data dest="${bundle}/Contents/Resources/en.lproj/GnuCash Help/"> ${prefix}/share/gnome/help/gnucash/C/gnucash-help </data> <data dest="${bundle}/Contents/Resources/en.lproj/GnuCash Guide/"> ${prefix}/share/gnome/help/gnucash/C/gnucash-guide/ </data> <data dest="${bundle}/Contents/Resources/de.lproj/GnuCash Help/"> ${prefix}/share/gnome/help/gnucash/de_DE/gnucash-help </data> <data dest="${bundle}/Contents/Resources/de.lproj/GnuCash Guide/"> ${prefix}/share/gnome/help/gnucash/de_DE/gnucash-guide/ </data> <data dest="${bundle}/Contents/Resources/it.lproj/GnuCash Help/"> ${prefix}/share/gnome/help/gnucash/it_IT/gnucash-help </data> <data dest="${bundle}/Contents/Resources/it.lproj/GnuCash Guide/"> ${prefix}/share/gnome/help/gnucash/it_IT/gnucash-guide/ </data> <data dest="${bundle}/Contents/Resources/ja.lproj/GnuCash Guide/"> ${prefix}/share/gnome/help/gnucash/ja_JP/gnucash-guide/ </data> To comment out XML code, surround it like so: <!-- stuff to be commented out --> 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 for gtk-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. 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). Upload both the resulting .dmg to the correct version directory of Gnucash's file manager area on Sourceforge. 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. Upload the .dmg to the release on Github. Update the appropriate links on the Gnucash webpage. Make Distcheck If you're going to create the tarballs to upload for a release, you run make distcheck. There are a couple of Mac quirks to work around, so use mkdir tmp DISTCHECK_CONFIGURE_FLAGS=--disable-error-on-warning TMPDIR="`pwd`/tmp" make distcheck The first variable lets configure correctly find GLib's gettext bindings (the GLIB_GETTEXT m4 macro issues a compiler warning). The second overrides $TMPDIR, which by default points to a folder in /var/folders and contains characters which choke GConf. Known Issues 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. At launch, Gnucash will find the old instance and kill it before starting a new one, but that means that you'll have a stale instance running most of the time. This will get in the way if you want to replace or remove Gnucash.app, so you'll have to kill it from 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. There is no theme engine in the bundle, so customizations are not supported. Gtk-OSX does not yet support Universal Access. 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.