Difference between revisions of "MacOS/Quartz"

From GnuCash
Jump to: navigation, search
m (Downloads: Forgot to fix the labels.)
(Updating with Apple's various namings for OSX)
(27 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
==Downloads==
 
==Downloads==
[http://downloads.sourceforge.net/sourceforge/gnucash/Gnucash-Intel-2.6.18-1.dmg Gnucash-Intel-2.6.18] and [http://downloads.sourceforge.net/sourceforge/gnucash/Gnucash-PPC-2.6.18-1.dmg Gnucash-PPC-2.6.18]  are now available as a binary download from the [http://sourceforge.net/projects/gnucash/files/ Gnucash project at Sourceforge].''  
+
* [http://downloads.sourceforge.net/sourceforge/gnucash/Gnucash-Intel-{{MacosPackage}}.dmg Gnucash-Intel-{{Version}}],
'''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.'''
+
* [http://downloads.sourceforge.net/sourceforge/gnucash/Gnucash-Intel-{{MacosFallbackPackage}}.dmg Gnucash-Intel-{{FallbackVersion}}] and
 +
* [http://downloads.sourceforge.net/sourceforge/gnucash/Gnucash-PPC-{{MacosFallbackPackage}}.dmg Gnucash-PPC-{{FallbackVersion}}]  are now available as binary downloads from the [http://sourceforge.net/projects/gnucash/files/ Gnucash project at Sourceforge].''  
 +
;Release notes: are included in the disk-image.  
 +
;Important:GnuCash 2.6.21 is the last version that supports Mac OS X 10.8 (Mountain Lion) and earlier, and so the last version that will run on PowerPC Macs.
 +
:''OS X 10.9 (Mavericks) or higher'' is '''required''' to run Gnucash-3.0 and later.
 +
'''For virtually all users it is more appropriate to download the binary rather than to use the procedure described here.'''
  
 
==Overview==
 
==Overview==
GnuCash can be built to run more or less natively on OSX -- meaning without X11. Better yet, the build is almost automatic.
+
GnuCash can be built to run more or less natively on macOS -- 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.  
+
This page describes the procedure to build GnuCash with the Quartz environment. You can also use MacPorts: The details are described at [[MacOS/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.  
 
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.
+
A build will consume about 5 gigabytes of disk space and typically take several hours to run.  The initial build, which includes pulling down sources from all dependencies, can take days, depending on how often network errors interrupt the process, and how quickly they are noticed.
  
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.
+
This build 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) work as well. A patch to Gtk+ allows copy and paste in the register pages.
  
 
==Support==
 
==Support==
This procedure depends on the [https://wiki.gnome.org/action/show/Projects/GTK+/OSX Gnome Gtk-OSX project]. Support for that is provided via the [https://mail.gnome.org/mailman/listinfo/gtk-osx-users-list gtk-osx-users-list@gnome.org] mailing list. Questions, comments, or suggestions about Gnucash should be directed to the appropriate Gnucash mailing list ([https://lists.gnucash.org/mailman/listinfo/gnucash-devel gnucash-devel] for development versions (2.7.x, git master) or [https://lists.gnucash.org/mailman/listinfo/gnucash-user gnucash-user] for release versions (2.6.x).)
+
This procedure depends on the [https://wiki.gnome.org/action/show/Projects/GTK+/OSX Gnome Gtk-OSX project]. Support for that is provided via the [https://mail.gnome.org/mailman/listinfo/gtk-osx-users-list gtk-osx-users-list@gnome.org] mailing list. Questions, comments, or suggestions about Gnucash should be directed to the appropriate Gnucash mailing list ([https://lists.gnucash.org/mailman/listinfo/gnucash-devel gnucash-devel] for development versions (git master) or [https://lists.gnucash.org/mailman/listinfo/gnucash-user gnucash-user] for release (3.x, git maint).)
  
 
==Preliminaries==
 
==Preliminaries==
Line 21: Line 26:
 
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.
 
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 [https://git.gnome.org/browse/gtk-osx/plain/gtk-osx-build-setup.sh gtk-osx-build-setup.sh] by clicking the link or from the commandline:
+
First download [https://gitlab.gnome.org/GNOME/gtk-osx/raw/master/gtk-osx-build-setup.sh gtk-osx-build-setup.sh] by clicking the link or from the command line:
 
<syntaxhighlight lang="sh">
 
<syntaxhighlight lang="sh">
curl -O -L https://git.gnome.org/browse/gtk-osx/plain/gtk-osx-build-setup.sh
+
curl -O -L https://gitlab.gnome.org/GNOME/gtk-osx/raw/master/gtk-osx-build-setup.sh
 
</syntaxhighlight>
 
</syntaxhighlight>
and run it from the commandline. It will install jhbuild and do some preliminary setup.
+
and run it from the command line. It will install jhbuild and do some preliminary setup. '''Warnings about aclocal, automakers and yelp-tools not being available are normal'''.
  
JHBuild is configured to build GnuCash via [http://github.com/gnucash/gnucash-on-osx/raw/master/.jhbuildrc-custom <code>.jhbuildrc-custom</code>]. Download this file to your home directory either by clicking the link and moving the downloaded file or from the commandline:
+
JHBuild is configured to build GnuCash via [http://github.com/gnucash/gnucash-on-osx/raw/master/.jhbuildrc-custom <code>.jhbuildrc-custom</code>]. Download this file to your home directory either by clicking the link and moving the downloaded file or from the command line:
 
<syntaxhighlight lang="sh">
 
<syntaxhighlight lang="sh">
 
curl -O -L http://github.com/gnucash/gnucash-on-osx/raw/master/.jhbuildrc-custom
 
curl -O -L http://github.com/gnucash/gnucash-on-osx/raw/master/.jhbuildrc-custom
 
</syntaxhighlight>
 
</syntaxhighlight>
  
OS X 10.11 added a security feature called [https://developer.apple.com/library/prerelease/mac/documentation/Security/Conceptual/System_Integrity_Protection_Guide/  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.
+
OS X 10.11 added a security feature called [https://developer.apple.com/library/prerelease/mac/documentation/Security/Conceptual/System_Integrity_Protection_Guide/  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 in the presence of SIP.
 
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 in the presence of SIP.
Line 38: Line 43:
 
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.
 
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)
+
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 automatically enabled on OS X 10.11 (El Capitan) or later.
  skip.remove("bash")
 
in .jhbuildrc-custom before starting the build. Then, when GnuCash's build fails, just edit <tt>$PREFIX/bin/guild</tt> to change the first line to
 
  #!/$PREFIX/bin/bash
 
''substituting the full path for $PREFIX''.
 
  
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 [https://wiki.gnome.org/Projects/GTK%2B/OSX/Building#Building_for_Older_Versions_of_Mac_OS_X 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 <tt>meta-gnucash-stable</tt> to <tt>meta-gnucash-stable-Leopard</tt> in <tt>.jhbuildrc-custom</tt>.
+
Then, when GnuCash's build fails, just edit <tt>&lt;prefix&gt;/bin/guild</tt> to change the first line to
 +
  #!/&lt;prefix&gt;/bin/bash
 +
where &lt;prefix&gt; is the path to your install directory, <tt>~/gnucash-stable/inst</tt> unless you've changed it in <tt>.jhbuildrc-custom</tt>.
  
Make the following changes to <code>.jhbuildrc-custom</code>:
+
You may need to make the following changes to <code>.jhbuildrc-custom</code>:
{| class="wikitable"
 
|-
 
! scope="col"| Operation
 
! scope="col"| Line
 
! scope="col"| Optional?
 
! scope="col"| Details
 
  
|- style="vertical-align:top;"
+
* If you are building for an older version of macOS than the build machine, you can pass arguments to <code>setup_sdk()</code>. There's an example in the comments in <code>.jhbuildrc-custom</code>.
| edit
+
* The GnuCash v2.6.x (i.e. stable) moduleset uses an old version of WebKit that in turn requires an old version of ICU. Add <code>skip.append("icu")</code>.
| <syntaxhighlight lang="python" inline style="white-space:nowrap">setup_sdk()</syntaxhighlight>
 
| yes
 
| Adjust if one needs to support an older system than one is building on. See [[#setup_sdk]].
 
|- style="vertical-align:top;"
 
| add
 
| <syntaxhighlight lang="python" inline style="white-space:nowrap">skip = ["icu"]</syntaxhighlight>
 
| 2.6.x only
 
| Prevents a conflict in ICU versions. 2.6.x and eariler builds only; 2.6.99 and later use the latest ICU.
 
  
|- style="vertical-align:top;"
+
If you like, you can change the directory into which the sources are checked out, build out-of-source, or install to a different directory. See [https://wiki.gnome.org/Projects/GTK%2B/OSX/Building Building Gtk-OSX] and the [https://developer.gnome.org/jhbuild/unstable/config-reference.html.en Jhbuild configuration reference] for more information.  
| edit
 
| <syntaxhighlight lang="python" inline style="white-space:nowrap">prefix = ...</syntaxhighlight>
 
| yes
 
| By default, jhbuild will download, build, and install everything into $HOME/gnucash-stable. You can change that by editing the <code>prefix</code> line to any directory to which you have write privilege. JHBuild will create the prefix directory but its parent directory must already exist. If you insist on using <code>/usr/local</code> (not recommended) you'll need to <code>sudo chmod g+x /usr/local</code> and <code>newgrp wheel</code> beforehand, and you must be logged in as an admin user to do so.
 
|}
 
 
 
Run the following build commands now to avoid problems downstream:
 
{| class="wikitable"
 
|-
 
! scope="col"| Build Command
 
! scope="col"| Details
 
 
 
|- style="vertical-align:top;"
 
| <syntaxhighlight lang="sh" inline style="white-space:nowrap">jhbuild build openssl</syntaxhighlight>
 
| 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 [https://wiki.gnome.org/Projects/GTK%2B/OSX/Building#Quick_Start Building GTK-OSX].
 
 
 
|- style="vertical-align:top;"
 
| <syntaxhighlight lang="sh" inline style="white-space:nowrap">jhbuild build python</syntaxhighlight>
 
| For itstool and its usage of libxml2.
 
|}
 
  
 
Run <code>jhbuild bootstrap</code> to install the tools needed for the rest of the build.
 
Run <code>jhbuild bootstrap</code> to install the tools needed for the rest of the build.
  
===Customizing the Configuration===
+
==== setup_sdk ====
 +
With no arguments (the default) <code>setup_sdk()</code> will configure the build for your system. Unless you're building for distribution we recommend that you do this.
  
To add configure arguments (e.g., --enable-dbi), add a line
+
If you have Xcode 7 (shipped with OS X 10.9 (Mavericks)) or later you can build for any version from 10.6 on with the included SDK by calling (e.g.)
  module_autogenargs["gnucash"]="--enable-dbi"
+
   setup_sdk("10.6", native, ["i386"]); note, however, that some users have noted linkage problems when doing this. It is safest to build GnuCash on the earliest macOS version you intend to support.
 
 
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.) <tt>--disable-aqbanking</tt>. Change <tt>gnucash</tt> to <tt>gnucash-git</tt> if that's what you're building.
 
 
 
==== setup_sdk ====
 
With no arguments (the default) setup_sdk will configure the build for your system. 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"])
 
 
The GnuCash 2.6.x application bundle is built for Mac OS X 10.5 and later. To do likewise, please see [ https://wiki.gnome.org/Projects/GTK+/OSX/Building#Building_for_Older_Versions_of_Mac_OS_X Building for Older Versions of Mac OS X]. You'll use
 
The GnuCash 2.6.x application bundle is built for Mac OS X 10.5 and later. To do likewise, please see [ https://wiki.gnome.org/Projects/GTK+/OSX/Building#Building_for_Older_Versions_of_Mac_OS_X Building for Older Versions of Mac OS X]. You'll use
   setup_sdk("10.5", "10.5", ["i386"])
+
   setup_sdk("10.5", "10.5"["i386"])
  
'''Note:'''The <tt>master</tt> branch is converted to a cmake module which doesn't support customization from <tt>.jhbuildrc-custom</tt>. If you need a customized build do the build manually with the cmake instructions from [[Building]].
+
'''Note:''' GnuCash v3.0 and later have removed support for autotools; only CMake is supported. Jhbuild doesn't have the ability to modify the build parameters from <code>.jhbuildrc-custom</code> for any build system other than autotools.
 +
'''Note:''' As noted above, GnuCash v3.0 and later require OS X 10.9 ("Mavericks") or later. Apple has announced that they'll remove 32-bit runtime support from macOS 10.15, so we recommend building with ```arch x86_64``` unless you're targetting systems earlier than Mac OS X 10.7.  
  
 
==Building==
 
==Building==
Line 118: Line 83:
 
<syntaxhighlight lang="sh">
 
<syntaxhighlight lang="sh">
 
jhbuild shell
 
jhbuild shell
cd $PREFIX/../src/gnucash-2.6.17
+
cd $PREFIX/../src/gnucash-3.2
 
make uninstall
 
make uninstall
 
cd ..
 
cd ..
 
git clone -b maint https://github.com/Gnucash/gnucash.git
 
git clone -b maint https://github.com/Gnucash/gnucash.git
 
cd gnucash.git
 
cd gnucash.git
./autogen.sh && ./configure --prefix=$PREFIX --enable-ofx --enable-aqbanking --enable-binreloc --enable-dbi --with-dbi-dbd-dir=$PREFIX/lib/dbd && make && make install
+
cmake -D CMAKE_INSTALL_PREFIX=$PREFIX -D CMAKE_PREFIX_PATH=$PREFIX -D GMOCK_ROOT=$SRCROOT/googletest/googlemock -D GTEST_ROOT=$SRCROOT/googletest/googlemock .
 
</syntaxhighlight>
 
</syntaxhighlight>
  
To work on the current unstable branch, build <tt>meta-gnucash-git</tt> as explained in the next section. We recommend that you use separate prefixes for stable and unstable because of the substantially different dependencies.
+
To work on the master branch, build <tt>meta-gnucash-git</tt> as explained in the next section.
  
 
===Building Unstable Versions===
 
===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:
 
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 <tt>prefix = os.path.join(os.environ["HOME"], "gnucash-stable") </tt> and uncomment the line <tt>#prefix = os.path.join(os.environ["HOME"], "gnucash-unstable")</tt>  
+
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-gnucash-stable"]
 +
and uncomment the one that you want to build (<code>meta-gnucash-unstable</code> or <code>meta-gnucash-git</code>). <code>meta-gnucash-unstable</code> will build the latest unstable tarball (only applicable during the few months preceding a major release) and <code>meta-gnucash-git</code> will clone the git repository and checkout the <tt>master</tt> branch.
 +
 
 +
===Building with Xcode===
 +
With the move from [[Autotools]] to [[CMake]] it's now possible to build GnuCash using Apple's Xcode IDE. To make it work first do a regular build as above to get all of the dependencies set up.
  
Similarly, comment out the line <tt>modules = ["meta-gtk-osx-bootstrap", "meta-gtk-osx-core", "meta-gnucash-stable"]</tt> and uncomment the one that you want to build (meta-gnucash-unstable or meta-gnucash-git).
+
Now create a new build directory and ```cd``` to it but do *not* start a jhbuild shell, just export the following environment variables to simplify the cmake invocation:
 +
<syntaxhighlight lang="sh">
 +
export PREFIX=/full/path/to/prefix
 +
export PATH=$PATH:$PREFIX/bin
 +
export SRCROOT=$PREFIX/src
 +
</syntaxhighlight>
 +
making any required changes. Now create the xcodeproject with cmake:
 +
<syntaxhighlight lang="sh">
 +
cmake -G Xcode -D CMAKE_INSTALL_PREFIX=$PREFIX -D GTEST_ROOT=$SRCROOT/googletest/googletest -D GMOCK_ROOT=$SRCROOT/googletest/googlemock $SRCROOT/gnucash-git
 +
</syntaxhighlight>
 +
If you're building from a tarball you'll need to change the source directory at the end of the line.
 +
 
 +
This creates a "foreign" build that actually uses make instead of xcodebuild, but it's sufficient for using Xcode tools like the debug window and the static analyzer.
  
 
'''Notes'''  
 
'''Notes'''  
* 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.
+
* Because all current branches of GnuCash use C++ features that don't compile on or for earlier versions, GnuCash master requires OS X 10.9 (Mavericks) or later.
* The dependencies for GnuCash 2.6.99 and later have changed rather dramatically from earlier 2.x releases. The most significant are that GnuCash now requires WebKit2Gtk and that in turn requires that GnuCash switch to Gtk3. We've begun the C++ rewrite of engine are using GoogleTest for new unit tests and the Boost Libraries for several language extensions. The register has been fixed to no longer use the obsolete libgnomecanvas and the small part of libgoffice that the CSV importer required has been copied into GnuCash sources.
+
* The dependencies for GnuCash have changed from the 2.x releases. The most significant are that major Linux distributions have dropped support for WebKit1Gtk, so we had to enable support for WebKit2Gtk and that in turn requires that GnuCash switch to Gtk3. We've begun the C++ rewrite of engine are using [https://github.com/google/googletest/ GoogleTest] for new unit tests and the [https://www.boost.org Boost Libraries] for several language extensions. The register has been fixed to no longer use the obsolete <code>libgnomecanvas</code> and the small part of <code>libgoffice</code> that the CSV importer required has been copied into GnuCash sources.
  
 
Boost is in the moduleset, but jhbuild doesn't know how to build it, so that must be done manually. When the build fails, select <br/><tt>[4] Start Shell</tt> and do the following:  
 
Boost is in the moduleset, but jhbuild doesn't know how to build it, so that must be done manually. When the build fails, select <br/><tt>[4] Start Shell</tt> and do the following:  
 
<syntaxhighlight lang="sh">
 
<syntaxhighlight lang="sh">
 
./bootstrap.sh
 
./bootstrap.sh
./b2 toolset=darwin address-model=32 cxxflags="$CPPFLAGS" cflags="$CPPFLAGS" linkflags="$LDFLAGS" dll-path=$PREFIX/lib --prefix=$PREFIX --builddir=$PREFIX/../build/boost_1_56_0
+
./b2 toolset=darwin address-model=32 cxxflags="$CPPFLAGS" cflags="$CPPFLAGS" linkflags="$LDFLAGS" dll-path=$PREFIX/lib --prefix=$PREFIX --builddir=$PREFIX/../build/boost_1_56_0 install
for i in `ls $PREFIX/lib/libboost*`; do install_name_tool -id $i $i; done  
+
for i in `ls $PREFIX/lib/libboost*.dylib`; 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
 
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
 
</syntaxhighlight>  
 
</syntaxhighlight>  
 
But it's always wise to check [https://github.com/Gnucash/gnucash-on-osx/blob/master/modulesets/gnucash.modules gnucash.modules] for updated instructions. Look out for a comment before the boost module.
 
But it's always wise to check [https://github.com/Gnucash/gnucash-on-osx/blob/master/modulesets/gnucash.modules gnucash.modules] for updated instructions. Look out for a comment before the boost module.
  
Finally hit <tt>ctrl-D</tt> to return to jhbuild and select <tt>2</tt> three times to proceed to the next module.
+
Finally hit <tt>ctrl-D</tt> to return to jhbuild and select <tt>2</tt> three times to proceed to the next module. ''Note: jhbuild has taken to crashing in the install step, so <tt>ctrl-c</tt> quickly to abort that step. If it does crash you can restart with ''<tt>jhbuild build --start-at=googletest</tt>.
 
 
GoogleTest is also in the moduleset and also doesn't build, but in this case we don't want it to: GnuCash tests incorporate the GoogleTest code directly, so when the build fails just select <tt>2 - ignore and continue</tt>.
 
 
 
===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 <tt>mysql</tt> or <tt>pgsql</tt> for <tt>sqlite3</tt>, 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 <tt>libdbdmysql.so</tt> or <tt>libdbdpgsql.so</tt>) to <tt>Gnucash.app/Contents/Resources/lib/dbd</tt>. 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 <tt>pgsql</tt> for <tt>mysql</tt> if that's appropriate and putting in the actual path (which you can see with <tt>otool -L</tt> for <tt>/prefix/path</tt>.
 
  
 
===Documentation===
 
===Documentation===
Line 194: Line 158:
 
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:
 
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 [http://ftp.gnome.org/pub/gnome/sources/gtk-mac-bundler/0.6/gtk-mac-bundler-0.6.1.tar.bz2 the bundler], unpack it, cd into the gtk-mac-bundler directory, and <tt>make install</tt>
+
'''N.B.''' This procedure works ''only'' with GnuCash built according to the above instructions.  
:Download [https://raw.github.com/jralls/gnucash-on-osx/master/gnucash-bundler/gnucash.bundle gnucash.bundle], [https://raw.github.com/jralls/gnucash-on-osx/master/gnucash-bundler/Info.plist Info.plist], [https://raw.github.com/jralls/gnucash-on-osx/master/gnucash-bundler/gnucash.launcher gnucash.launcher], and [https://raw.github.com/jralls/gnucash-on-osx/master/gnucash-bundler/gnucash.icns gnucash.icns] into the same folder. For the rest of the discussion, we'll call that folder <tt>gnucash-bundler</tt>.
 
  
:<tt>cd gnucash-bundler</tt>  
+
:Clone [https://gitlab.gnome.org/GNOME/gtk-mac-bundler.git the bundler], cd into the cloned gtk-mac-bundler directory, and <tt>make install</tt>
:Look through gnucash.launcher and gnucash.bundle and adjust the paths to match your installation.
+
:Create a directory somewhere convienient (we'll call it <tt>gnucash-bundler</tt> from now on), cd to it, and download [https://raw.github.com/Gnucash/gnucash-on-osx/master/gnucash-bundler/gnucash.bundle gnucash.bundle], [https://raw.github.com/Gnucash/gnucash-on-osx/master/gnucash-bundler/Info.plist Info.plist], and [https://raw.github.com/Gnucash/gnucash-on-osx/master/gnucash-bundler/gnucash.icns gnucash.icns] into it.
:make gnucash.launcher executable (<tt>chmod +x gnucash.launcher</tt>)
 
:execute <tt>jhbuild shell</tt> to set up the environment for the bundler
 
:<tt> export PATH=$PREFIX/bin:$PATH </tt> because jhbuild shell doesn't do this for some reason
 
:<tt> gtk-mac-bundler gnucash.bundle</tt>
 
:<tt> exit</tt>
 
  
And your bundle should be ready to go.
+
Look through gnucash.bundle and adjust the paths to match your installation.
Try <tt>GnuCash.app/Contents/MacOSX/GnuCash</tt> from the command-line so that you can see any error messages. If that works, try <tt>open GnuCash.app</tt>. 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 <tt>IGE_DEBUG_LAUNCHER=1 open Gnucash.app</tt> 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 [http://github.com/Gnucash/gnucash-on-osx/raw/master/gnucash-bundler/gnucash-unstable.bundle gnucash-unstable.bundle], [http://github.com/Gnucash/gnucash-on-osx/raw/master/gnucash-bundler/Info-unstable.plist Info-unstable.plist], [http://github.com/Gnucash/gnucash-on-osx/raw/master/gnucash-bundler/gnucash-unstable.launcher gnucash-unstable.launcher], and [http://github.com/Gnucash/gnucash-on-osx/raw/master/gnucash-bundler/gnucash.icns gnucash.icns]. They all need to be in the same directory, and you'll run <tt>gtk-mac-bundler /path/to/gnucash-unstable.bundle.</tt>
 
  
 
'''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  
 
'''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  
Line 240: Line 193:
 
   <data dest="${bundle}/Contents/Resources/ja.lproj/GnuCash Guide/">
 
   <data dest="${bundle}/Contents/Resources/ja.lproj/GnuCash Guide/">
 
     ${prefix}/share/gnome/help/gnucash/ja_JP/gnucash-guide/
 
     ${prefix}/share/gnome/help/gnucash/ja_JP/gnucash-guide/
 +
  <data dest="${bundle}/Contents/Resources/pt.lproj/GnuCash Help/">
 +
    ${prefix}/share/doc/gnucash-docs/pt/gnucash-help/
 +
  </data>
 +
 +
  <data dest="${bundle}/Contents/Resources/pt.lproj/GnuCash Guide/">
 +
    ${prefix}/share/doc/gnucash-docs/pt/gnucash-guide/
 +
  </data>
 +
 
 +
  <data dest="${bundle}/Contents/Resources/ru.lproj/GnuCash Guide/">
 +
    ${prefix}/share/doc/gnucash-docs/ru/gnucash-guide/
 
   </data>
 
   </data>
 
</syntaxhighlight>
 
</syntaxhighlight>
 
To comment out XML code, surround it like so: <pre><!-- stuff to be commented out --></pre> Note that comments cannot contain "--".
 
To comment out XML code, surround it like so: <pre><!-- stuff to be commented out --></pre> Note that comments cannot contain "--".
 +
 +
You're ready to make your bundle:
 +
<SyntaxHighlight lang="sh">
 +
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                          #quit the jhbuild shell
 +
</SyntaxHighlight>
 +
 +
And your bundle should be ready to go.
 +
Try <tt>GnuCash.app/Contents/MacOS/GnuCash</tt> from the command-line so that you can see any error messages. If that works, try <tt>open GnuCash.app</tt>. If that works, then you can move GnuCash.app to your Applications folder and it's ready to use.
 +
 +
=== Bundling Oldstable ===
 +
 +
To bundle GnuCash version 2.6 and earlier you need [https://raw.github.com/Gnucash/gnucash-on-osx/master/gnucash-bundler/gnucash-oldstable.bundle gnucash-oldstable.bundle], [https://raw.github.com/Gnucash/gnucash-on-osx/master/gnucash-bundler/Info-oldstable.plist Info-oldstable.plist] instead of the corresponding ones listed above as well as
 +
[https://raw.github.com/Gnucash/gnucash-on-osx/master/gnucash-bundler/gnucash.launcher gnucash.launcher]. Older versions don't have the Portuguese or Russian Guide translations. Otherwise the procedure is the same.
 +
 +
=== Bundling from a Git Clone ===
 +
At present there are two active git branches, 'maint' and 'master'. Both use the primary bundling procedure above.
  
 
=== Making a distribution ===
 
=== 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 [http://git.gnome.org/browse/gtk-mac-bundler gtk-mac-bundler] and [http://github.com/Gnucash/gnucash-on-osx  gnucash-on-osx].  
+
* 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 [http://gitlab.gnome.org/GNOME/gtk-mac-bundler gtk-mac-bundler] and [http://github.com/Gnucash/gnucash-on-osx  gnucash-on-osx].  
 
* Edit the version numbers and, if necessary, the copyright dates in Info.plist (or Info-unstable.plist).
 
* Edit the version numbers and, if necessary, the copyright dates in Info.plist (or Info-unstable.plist).
 +
* make sure that $APPLICATION_CERT is set correctly with your Apple Developer Program certificate ID. gtk-mac-bundler uses the value of that environment variable to codesign the app bundle.
 
* Make a bundle as described above. Test it.
 
* 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.
 
* 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.
+
* Copy the scriptlet "FinanceQuote Update.app" 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).  
+
* Copy AUTHORS, DOCUMENTORS, LICENSE, NEWS, and README from the GnuCash source directory to the distribution folder. Rename each file with a ".txt" suffix so that Finder will recognize it and enable QuickLook.
* 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.
+
* 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 (<tt>Gnucash-Intel-X.Y-Z.dmg</tt> where X.Y is the GnuCash version and Z is the serial number of dmgs for that release, beginning with 1.)
 +
* codesign the dmg with your Apple Developer Program certificate.
 +
* Get the SHA-256 hash of the .dmg with
 +
  shasum -a 256 Gnucash-Intel-X.Y-Z.dmg
 +
:and paste the result into the SourceForge README.txt, the Github release notes, the news article in <tt>gnucash-htdocs</tt>, and the release announcement email.
 +
* 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.
 
* Upload the .dmg to the release on Github.
 
* Update the appropriate links on the Gnucash webpage.
 
* 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 <tt>make distcheck</tt>. 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.
 
  
 
==Accessibility==
 
==Accessibility==
Line 272: Line 252:
  
  
[[Category: MacOSX]]
+
[[Category: MacOS]]

Revision as of 09:54, 27 June 2019

Downloads

Release notes
are included in the disk-image.
Important
GnuCash 2.6.21 is the last version that supports Mac OS X 10.8 (Mountain Lion) and earlier, and so the last version that will run on PowerPC Macs.
OS X 10.9 (Mavericks) or higher is required to run Gnucash-3.0 and later.

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 macOS -- 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 MacOS/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. The initial build, which includes pulling down sources from all dependencies, can take days, depending on how often network errors interrupt the process, and how quickly they are noticed.

This build 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) work as well. A patch to Gtk+ 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 (git master) or gnucash-user for release (3.x, git maint).)

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 command line:

curl -O -L https://gitlab.gnome.org/GNOME/gtk-osx/raw/master/gtk-osx-build-setup.sh

and run it from the command line. It will install jhbuild and do some preliminary setup. Warnings about aclocal, automakers and yelp-tools not being available are normal.

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 command line:

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

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 in the presence of SIP.

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 automatically enabled on OS X 10.11 (El Capitan) or later.

Then, when GnuCash's build fails, just edit <prefix>/bin/guild to change the first line to

 #!/<prefix>/bin/bash

where <prefix> is the path to your install directory, ~/gnucash-stable/inst unless you've changed it in .jhbuildrc-custom.

You may need to make the following changes to .jhbuildrc-custom:

  • If you are building for an older version of macOS than the build machine, you can pass arguments to setup_sdk(). There's an example in the comments in .jhbuildrc-custom.
  • The GnuCash v2.6.x (i.e. stable) moduleset uses an old version of WebKit that in turn requires an old version of ICU. Add skip.append("icu").

If you like, you can change the directory into which the sources are checked out, build out-of-source, or install to a different directory. See Building Gtk-OSX and the Jhbuild configuration reference for more information.

Run jhbuild bootstrap to install the tools needed for the rest of the build.

setup_sdk

With no arguments (the default) setup_sdk() will configure the build for your system. Unless you're building for distribution we recommend that you do this.

If you have Xcode 7 (shipped with OS X 10.9 (Mavericks)) 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, however, that some users have noted linkage problems when doing this. It is safest to build GnuCash on the earliest macOS version you intend to support.

The GnuCash 2.6.x application bundle is built for Mac OS X 10.5 and later. To do likewise, please see [ https://wiki.gnome.org/Projects/GTK+/OSX/Building#Building_for_Older_Versions_of_Mac_OS_X Building for Older Versions of Mac OS X]. You'll use

 setup_sdk("10.5", "10.5"["i386"])

Note: GnuCash v3.0 and later have removed support for autotools; only CMake is supported. Jhbuild doesn't have the ability to modify the build parameters from .jhbuildrc-custom for any build system other than autotools. Note: As noted above, GnuCash v3.0 and later require OS X 10.9 ("Mavericks") or later. Apple has announced that they'll remove 32-bit runtime support from macOS 10.15, so we recommend building with ```arch x86_64``` unless you're targetting systems earlier than Mac OS X 10.7.

Building

Once all of the preliminaries are complete, run:

 $> jhbuild build

Building for Development

Please see Development for general guidelines and lots of helpful links.

If you intend to contribute your work to the GnuCash project please subscribe to the gnucash-devel list and coordinate your work with the core developers before starting.

You'll need to work with the appropriate source code repository rather than the release tarball from the procedure so far. Git provides details on our repository and has some help for developers who aren't yet familiar with the git version control system. If you're going to work on the current release, check out the maint branch. It's simplest to just build it manually in a jhbuild shell. The following assumes that one hasn't changed .jhbuildrc-custom to build out-of-source, and one must make the obvious version edit:

jhbuild shell
cd $PREFIX/../src/gnucash-3.2
make uninstall
cd ..
git clone -b maint https://github.com/Gnucash/gnucash.git
cd gnucash.git
cmake -D CMAKE_INSTALL_PREFIX=$PREFIX -D CMAKE_PREFIX_PATH=$PREFIX -D GMOCK_ROOT=$SRCROOT/googletest/googlemock -D GTEST_ROOT=$SRCROOT/googletest/googlemock .

To work on the master branch, build meta-gnucash-git as explained in the next section.

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-gnucash-stable"]

and uncomment the one that you want to build (meta-gnucash-unstable or meta-gnucash-git). meta-gnucash-unstable will build the latest unstable tarball (only applicable during the few months preceding a major release) and meta-gnucash-git will clone the git repository and checkout the master branch.

Building with Xcode

With the move from Autotools to CMake it's now possible to build GnuCash using Apple's Xcode IDE. To make it work first do a regular build as above to get all of the dependencies set up.

Now create a new build directory and ```cd``` to it but do *not* start a jhbuild shell, just export the following environment variables to simplify the cmake invocation:

export PREFIX=/full/path/to/prefix
export PATH=$PATH:$PREFIX/bin
export SRCROOT=$PREFIX/src

making any required changes. Now create the xcodeproject with cmake:

cmake -G Xcode -D CMAKE_INSTALL_PREFIX=$PREFIX -D GTEST_ROOT=$SRCROOT/googletest/googletest -D GMOCK_ROOT=$SRCROOT/googletest/googlemock $SRCROOT/gnucash-git

If you're building from a tarball you'll need to change the source directory at the end of the line.

This creates a "foreign" build that actually uses make instead of xcodebuild, but it's sufficient for using Xcode tools like the debug window and the static analyzer.

Notes

  • Because all current branches of GnuCash use C++ features that don't compile on or for earlier versions, GnuCash master requires OS X 10.9 (Mavericks) or later.
  • The dependencies for GnuCash have changed from the 2.x releases. The most significant are that major Linux distributions have dropped support for WebKit1Gtk, so we had to enable support for WebKit2Gtk and that in turn requires that GnuCash switch to Gtk3. We've begun the C++ rewrite of engine are using GoogleTest for new unit tests and the Boost Libraries for several language extensions. The register has been fixed to no longer use the obsolete libgnomecanvas and the small part of libgoffice that the CSV importer required has been copied into GnuCash sources.

Boost is in the moduleset, but jhbuild doesn't know how to build it, so that must be done manually. When the build fails, select
[4] Start Shell and do the following:

./bootstrap.sh
./b2 toolset=darwin address-model=32 cxxflags="$CPPFLAGS" cflags="$CPPFLAGS" linkflags="$LDFLAGS" dll-path=$PREFIX/lib --prefix=$PREFIX --builddir=$PREFIX/../build/boost_1_56_0 install
for i in `ls $PREFIX/lib/libboost*.dylib`; 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. Note: jhbuild has taken to crashing in the install step, so ctrl-c quickly to abort that step. If it does crash you can restart with jhbuild build --start-at=googletest.

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:

N.B. This procedure works only with GnuCash built according to the above instructions.

Clone the bundler, cd into the cloned gtk-mac-bundler directory, and make install
Create a directory somewhere convienient (we'll call it gnucash-bundler from now on), cd to it, and download gnucash.bundle, Info.plist, and gnucash.icns into it.

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

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 dest="${bundle}/Contents/Resources/pt.lproj/GnuCash Help/">
    ${prefix}/share/doc/gnucash-docs/pt/gnucash-help/
  </data>

  <data dest="${bundle}/Contents/Resources/pt.lproj/GnuCash Guide/">
    ${prefix}/share/doc/gnucash-docs/pt/gnucash-guide/
  </data>
  
  <data dest="${bundle}/Contents/Resources/ru.lproj/GnuCash Guide/">
    ${prefix}/share/doc/gnucash-docs/ru/gnucash-guide/
  </data>
To comment out XML code, surround it like so:
<!-- stuff to be commented out -->
Note that comments cannot contain "--".

You're ready to make your bundle:

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                          #quit the jhbuild shell

And your bundle should be ready to go. Try GnuCash.app/Contents/MacOS/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.

Bundling Oldstable

To bundle GnuCash version 2.6 and earlier you need gnucash-oldstable.bundle, Info-oldstable.plist instead of the corresponding ones listed above as well as gnucash.launcher. Older versions don't have the Portuguese or Russian Guide translations. Otherwise the procedure is the same.

Bundling from a Git Clone

At present there are two active git branches, 'maint' and 'master'. Both use the primary bundling procedure above.

Making a distribution

  • 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 sure that $APPLICATION_CERT is set correctly with your Apple Developer Program certificate ID. gtk-mac-bundler uses the value of that environment variable to codesign the app bundle.
  • Make a bundle as described above. Test it.
  • Make a directory named for the version that you're going to distribute and move the new bundle into it.
  • Copy the scriptlet "FinanceQuote Update.app" from the previous version .dmg to the new distribution folder.
  • Copy AUTHORS, DOCUMENTORS, LICENSE, NEWS, and README from the GnuCash source directory to the distribution folder. Rename each file with a ".txt" suffix so that Finder will recognize it and enable QuickLook.
  • 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 (Gnucash-Intel-X.Y-Z.dmg where X.Y is the GnuCash version and Z is the serial number of dmgs for that release, beginning with 1.)
  • codesign the dmg with your Apple Developer Program certificate.
  • Get the SHA-256 hash of the .dmg with
 shasum -a 256 Gnucash-Intel-X.Y-Z.dmg
and paste the result into the SourceForge README.txt, the Github release notes, the news article in gnucash-htdocs, and the release announcement email.
  • 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.

Accessibility

Gtk has its own accessibility library, atk. It doesn't use or support the Mac's accessibility functions; in particular, one must use theOrca screen reader. This isn't provided in the application bundle as as far as we know there is no ready-made Mac build of it.

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-devel mailing list to coordinate your work with others.