Building on Windows

Development on Microsoft Windows isn't really encouraged. The build environment isn't really conducive to development and many of the unit tests don't work. However, if you must...

GnuCash 3.0 and Later

The build system for GnuCash 2.7 and later supports Windows 7 and later. The procedure is a bit simpler that for GnuCash 2.6 and earlier and provides a somewhat easier to use development environment. That doesn't mean that we recommend that you use Windows for development: GnuCash is very much a Unix program and development is much easier in a Unix environment like Linux, BSD, or MacOS.

First download and run setup-mingw64.ps1. Depending on where you want to put the development tree you may need to run PowerShell as an administrator. Depending on your security settings you may need to enable running scripts on your computer:

set-executionpolicy unrestricted

Once you've downloaded the script start PowerShell. You can review the script's parameters with

help \path\to\setup-mingw64.ps1

For convenience they're

• target_dir: The root directory where the build environment will be installed. The default is c:\gcdev64, but you can put it anywhere you have write privilege.
• download_dir: Defaults to target_dir\downloads. There's no requirement to have it in target_dir.
• x86_64: Set this to $true if you want to build 64-bit binaries. The default is $false.

Once setup-mingw64.ps1 is complete you will have an MSYS2 environment with all of the GnuCash dependencies that don't need to be built from source installed in it.

WARNING: The Mingw-w64 folks routinely upgrade ICU without also upgrading WebKitGtk3 so that the latter can't resolve its ICU dependency because ICU versions their library names. Add the following to c:\gcdev64\msys2\etc\pacman.conf, creating it if necessary, to protect your build environment from breaking this way:

 IgnorePkg   = mingw-w64-i686-icu 
 IgnorePkg   = mingw-w64-i686-boost
 IgnorePkg   = mingw-w64-i686-harfbuzz
 IgnorePkg   = mingw-w64-i686-webkitgtk3

Changing i686 to x86_64 if appropriate. For a new build environment do this BEFORE running any of the powershell scripts or pacman -Su!

When setting up a new build environment or if you get an upgrade that breaks the build, you can recover as follows:

• Visit MSYS2's download site, select the i686 or x86_64 directory, and find the latest tarball for webkitgtk3. Note its date.
• Find the ICU tarballs and note the dates of the tarballs before and after the webkitgtk3 date.
• Download the earlier ICU tarball.
• Download the Boost and Harfbuzz tarballs whose dates are between the two ICU dates.
• Install each tarball with pacman -U, e.g.:

 pacman -U /path/to/mingw-w64-i686-icu-61.1-1-any.pkg.tar.xz

Next open the Start menu and navigate to MSYS2 64Bit or MSYS2 32Bit; which you want will depend upon the bitness of your Windows version. If you specified x86_64 $true to setup-mingw64.ps1 you'll want to start the mingw64 shell, otherwise the mingw32 shell. In that shell window navigate to the gnucash-on-windows.git directory in the target directory to specified to setup-mingw64.ps1. We'll use the default for the following examples.

  cd /c/gcdev64/src/gnucash-on-windows.git
  TARGET=gnucash-unstable jhbuild -f jhbuildrc build

One of the things setup-mingw64.ps1 did was checkout the rest of the gnucash-on-windows repository in target_dir/src/gnucash-on-windows.git. That contains a customization (python) script and a jhbuild moduleset. The customization script selects one of the three GnuCash branches to build based on the value of $TARGET; the possibilities are gnucash-master (the default), gnucash-unstable (the unstable release git branch) and gnucash-releases, which builds GnuCash from the tarball specified in gnucash.modules instead of from a git branch. When we release GnuCash 2.8.0 gnucash-unstable will be replaced with gnucash-maint. The first time jhbuild build command will build GnuCash, GnuCash Docs, and all of the dependencies that Mingw-w64 doesn't provide. After that it only builds modules that need rebuilding unless you tell it otherwise; see the jhbuild manual for details on controlling jhbuild.

You can start a subshell with the paths to hand-compile or run GnuCash from the command line with

TARGET=gnucash-unstable jhbuild -f jhbuildrc shell

This is convenient for development as one can navigate to the gnucash build directory and re-run CMake and make as necessary while developing. N.B. Be sure to use a programming editor that preserves line ending style; git can get really unhappy if you put the wrong kind of line endings into a file. To build a package for installation there's a PowerShell script called gnucash-on-windows.git\bundle-gnucash.ps1 and an automation script, gnucash-on-windows.git\buildserver\build_package.ps1 suitable for use with the Task Scheduler for periodic builds. Each includes documentation accessible with PowerShell's help command, e.g.

help bundle-gnucash.ps1

.

Note that build_package.ps1 also takes care of updating the gnucash-on-windows repository and that jhbuild build will update the gnucash repository; you can do so manually with git from within the Mingw shell. SSH works, just set up your ~/.ssh directory with the necessary keys and config file.

You may find the MSys2 Wiki and Mingw-w64 Documentation helpful.

GnuCash 2.6 and Earlier

GnuCash 2.6 is no longer being developed. This procedure is archival. Don't use it without good reason.

First read the README for the Windows Build Environment. You'll need to download and run bootstrap_win_dev.vbs, then adjust gnucash-on-windows.git/custom.sh to build what you want the way you want, and run

 gnucash-on-windows.sh/install.sh

to build the program.

You'll find a shell file, devrc.sh in gnucash-on-windows.git. Sourcing, not running, this file

 . gnucash-on-windows.git/devrc.sh

will set the necessary environment variables so that you can re-run the build script as usual in gnucash/build and run GnuCash from gnucash/inst/bin