View source for MacOS/Quartz

==Downloads==
* [http://downloads.sourceforge.net/sourceforge/gnucash/Gnucash-Intel-{{MacosPackage}}.dmg Gnucash-Intel-{{Version}}],
* [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==
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 [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==
Read [https://wiki.gnome.org/Projects/GTK%2B/OSX/Building Building Gtk-OSX] and scan the [https://developer.gnome.org/jhbuild/stable/ 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 [https://gitlab.gnome.org/GNOME/gtk-osx/raw/master/gtk-osx-setup.sh gtk-osx-setup.sh] by clicking the link or from the command line:
<syntaxhighlight lang="sh">
curl -O -L https://gitlab.gnome.org/GNOME/gtk-osx/raw/master/gtk-osx-setup.sh
</syntaxhighlight>
and run it from the command line. Gtk now requires Python3 to build and Apple provides Python3 only on MacOS 10.15 Catalina, so it will first set up a Python3 virtual environment, then install jhbuild and configure what it needs to run. It will ask if you want to install CPython. You do.

It defaults to installing everything in <tt>$HOME/.new_local</tt>. If you prefer to install somewhere else, set the environment variables <tt>DEVPREFIX</tt> and <tt>PYTHONUSERBASE</tt> to that directory before running <tt>gtk-osx-setup.sh</tt>. One way to do that is inline with the command, e.g.
<syntaxhighlight lang="sh">
DEVPREFIX=$HOME/.jhbuild_root PYTHONUSERBASE=$HOME/.jhbuild_root ./gtk-osx-setup.sh
</syntaxhighlight>
There are some other directory customizing environment variables, see the list in <tt>gtk-osx-setup.sh</tt>
Default or not, you'll want to add the install location's <tt>bin</tt> directory to <tt>$PATH</tt>.

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">
curl -O -L https://github.com/gnucash/gnucash-on-osx/raw/master/jhbuildrc-custom
</syntaxhighlight>
and place it in <tt>$HOME/.config</tt>--unless you've set something different in <tt>$XDG_CONFIG_HOME</tt>, in which case put it there.

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.

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, and <tt>gtk-osx-setup.sh</tt> does that for you.


You may need to make the following changes to <code>jhbuildrc-custom</code>:

* 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>.

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. 

==== 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.

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 bundles were 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 <syntaxhighlight lang="sh">
setup_sdk("10.5", "10.5"["i386"])
</syntaxhighlight>
;Notes:
:* GnuCash v2.7.x and later have removed support for autotools; only CMake is supported.
:* GnuCash v2.7.x and later requires MacOS X 10.9 ("Mavericks") or later.
:* GnuCash v3.900 and later requires MacOS 10.13 ("High Sierra") or later to build because it requires a C++17-capable compiler. It may still be possible to get it to run on earlier systems, this hasn't been tested.
:* Apple has removed 32-bit runtime support from macOS 10.15, so we recommend building with ```arch x86_64``` unless you're targeting systems earlier than Mac OS X 10.7.

==Building==

Once all of the preliminaries are complete, run:
<syntaxhighlight lang="sh">
jhbuild bootstrap-gtk-osx
jhbuild build
</syntaxhighlight>

===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 [https://wiki.gnucash.org/wiki/Mailing_Lists#Mailing_Lists_for_Development_Topics 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 [http://git-scm.com/ git] version control system. Open <tt>jhbuildrc-custom</tt> in your text editor and find the section
<syntaxhighlight lang="Python">
#Select which modules to build. The only difference is which gnucash
#module (and all of the dependencies, see above) get built. "
modules = ["meta-gtk-osx-bootstrap", "meta-gnucash-stable"]
#modules = ["meta-gtk-osx-bootstrap", "gnucash-unstable"]
#modules = ["meta-gtk-osx-bootstrap", "gnucash-git"]
#branches["gnucash-git"] = (None, "maint")
</syntaxhighlight>
and change it to
<syntaxhighlight lang="Python">
#Select which modules to build. The only difference is which gnucash
#module (and all of the dependencies, see above) get built. "
#modules = ["meta-gtk-osx-bootstrap", "meta-gnucash-stable"]
#modules = ["meta-gtk-osx-bootstrap", "gnucash-unstable"]
modules = ["meta-gtk-osx-bootstrap", "gnucash-git"]
branches["gnucash-git"] = (None, "maint")
</syntaxhighlight>
:;Note the <tt>branches</tt> line: It will build the current ''stable'' branch; to build the ''development'' branch, the one leading to the next major release, change <tt>maint</tt> to <tt>master</tt>. You may also want to change the prefix directory in the line above that block.

====Command-line builds====
Once you have your initial build finished you'll start editing sources (they'll be in <tt>$HOME/gnucash-stable/src/gnucash-git</tt> unless you changed the <tt>prefix</tt> in <tt>jhbuilrc-custom</tt>) and you'll want to build and run the unit tests. Start a <tt>jhbuild</tt> shell and change directory to the build directory:
<syntaxhighlight lang="sh">
jhbuild shell
cd %PREFIX/../build/gnucash-git
</syntaxhighlight>
From there you can run the usual shell commands like <tt>cmake</tt> and <tt>ninja</tt>.

===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:
<syntaxhighlight lang="sh">
export PREFIX=/full/path/to/prefix
export PATH=$PATH:$PREFIX/bin
export SRCROOT=$PREFIX/../src
</syntaxhighlight>
making any required changes. '''Be sure to make different build directories for the maint and the master branches'''.

Now create the xcodeproject with cmake:

<syntaxhighlight lang="sh">
cmake -G Xcode -D CMAKE_INSTALL_PREFIX=$PREFIX -D GTEST_ROOT=$SRCROOT/googletest $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.

For some newer versions of Xcode cmake seems unable to determine the C compiler and tries to use ```ld```. If you encounter errors during Cmake or building saying that `ld` doesn't accept some option try adding
<syntaxhighlight lang="sh">
  -D CMAKE_C_COMPILER=/Applications/Xcode.app/Contents/Developer/Toolchains/Xcodetoolchain.default/usr/bin/clang
</syntaxhighlight>
to the cmake command line. Adjust the path as needed if the Xcode you're using isn't <code>/Applications/Xcode.app</code>.

;Notes:
:* Because all current branches of GnuCash use C++ features that don't compile on or for earlier versions, GnuCash <tt>maint</tt> requires MacOS X 10.9 (Mavericks) and GnuCash <tt>master</tt> requires MacOS 10.13 (High Sierra) 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 rewritten several modules in C++ and 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.

===Documentation===
The gnucash documentation is [http://www.gnucash.org/docs.phtml online], of course, but if you want a local copy, you can build the modules <tt>gnucash-docs</tt> or <tt>gnucash-docs-git</tt>. Just add whichever one you want to your "modules" argument. If you're using <tt>gnucash-docs-git</tt> you might also want to select the branch by adding a line
<syntaxhighlight lang="Python">
branches["gnucash-docs-git"] = (None, "maint")
</syntaxhighlight>
setting <tt>"maint"</tt> or <tt>"master"</tt> as you prefer.

===Debugging===
To get a debugging build, add the line
<tt>setup_debug()</tt> 
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 (<tt>jhbuild buildone --force --clean</tt>) 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: <syntaxhighlight lang="sh">
$PREFIX/bin/gnucash
</syntaxhighlight>
$PREFIX is the path to where you've built gtk; you can fill it in yourself or use <tt>jhbuild shell</tt> 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 [https://gitlab.gnome.org/GNOME/gtk-mac-bundler.git the bundler], cd into the cloned gtk-mac-bundler directory, and <tt>make install</tt>
: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.

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 <syntaxhighlight lang="xml">
  <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>
</syntaxhighlight> 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 ===

* 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).
* 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 (<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.
* 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 the [https://wiki.gnome.org/Projects/Orca Orca] 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 [https://mail.gnome.org/mailman/listinfo/gtk-osx-devel-list gtk-osx-devel mailing list]  to coordinate your work with others.


[[Category: MacOS]]