rjshaver / gnucash-on-windows Goto Github PK

These scripts will provide a build environment to build GnuCash on Windows.
The scripts will take care of building/installing all the dependencies needed
to build an run GnuCash on Windows.

Note: this build system depends on the mingw project which provides the gcc compiler 
      in a Windows environment. You can read more about mingw on its homepage:
      http://www.mingw.org/

These scripts support two ways to build a Windows/mingw32 version of GnuCash:
- directly on a Windows PC
- via cross-compilation on Linux (Note 2014-05-07: the scripts have been under
  heavy modification recently. The cross-compilation may no longer work.)

-----------------------------------------
1. Build GnuCash directly on a Windows PC
-----------------------------------------

Building GnuCash directly on a Windows PC requires you to enter commands
directly on a command line. Several command line interfaces exist. To
build GnuCash you will need to use two:

1. The Windows built-in command prompt (cmd.exe)
2. The Msys shell (will be installed automatically)

This is mentioned here because both command lines have a completely different
set of commands available so it will matter which command line to start from
for certain steps. In principle the instruction below will always specify
which command line to use.

Some notes on path names to begin:
----------------------------------
* Avoid using paths with spaces. Some parts of the build system don't cope well
  with spaces. So don't install in c:\Program Files. The build system by
  default assumes c:\gcdev as base directory called $GLOBAL_DIR from now on).

* Windows and mingw/msys use a slightly different notation for paths. When
  working in an msys shell window you are advised to always use the msys notation.
  Outside the msys shell window you should use the Windows notation. Here is an
  example to show the difference:
  Windows: c:\gcdev\gnucash-on-windows.git
  Msys   : /c/gcdev/gnucash-on-windows.git
  The difference is in the direction of the slashes and that c: is replaced with /c
  Note for completeness that in msys you can also use the Windows notation. However
  msys interprets a '\' as an escape character. So to use back slashes you will have
  to escape them. So the below will also work in msys:
  Msys (alternate): c:\\gcdev\\gnucash-on-windows.git


The steps
---------
On to building GnuCash now. The scripts have been set up to require as little
manual actions as possible. The following should get you going:

a. Download bootstrap_win_dev.vbs from the gnucash-on-windows
   repository on Github. Direct url:
   https://raw.githubusercontent.com/Gnucash/gnucash-on-windows/master/bootstrap_win_dev.vbs

b. Run this script by double-clicking it and follow the instructions.
   If the script's output window closes before you get to a "Happy hacking"
   message then something went wrong. To figure out what you can instead
   open a Windows command prompt (cmd.exe) and run the script as
   cscript.exe <path\to>\bootstrap_win_dev.vbs
   Be sure to replace <path\to> with the correct path.

Note: by default everything will be installed inside c:\gcdev\
      You could alter this location by passing some parameters
      to bootstrap_win_dev.vbs. There are a couple of other parameters
      you can set to influence what is installed where. Please read the
      bootstrap script to learn which ones. If you want to pass
      parameters you will have to run the script from the command line
      of course instead of double-clicking it.

Note: if you intend to use the buildserver scripts (see separate directory)
      to have a fully automated build that runs at regular intervals
      there are some restrictions to the paths you can/should alter.
      For more detail please check README.txt in the buildserver directory.

You are now ready to build gnucash for the first time. The build is
fully parameterized.  That means which versions of libraries and tools
to install, where to install them, which branch to build and so on can
all be defined. If not set explicitly some default values will be
used. If you're already familiar with the Windows build you may want
to customize some of these parameters. If not sure - don't. The build
should run just fine without it.

The default values will all be found in 'defaults.sh'. You can
override any of these in 'custom.sh'. The boostrap script you ran in
step b. already created an initial version of this file.

c. Open an Msys shell window. You do this by running
   c:\gcdev\mingw\msys\1.0\msys.bat
   Unless you chose to install mingw/msys in another directory of course.
   Let the automated build begin by:

   cd /c/gcdev/gnucash-on-windows.git
   ./install.sh

   If you chose to set up the build environment in a different location adjust
   the path accordingly.

d. To generate a self-installing setup.exe file that contains *everything* run
   the following command after install.sh has completed:

   ./dist.sh


And next ?
----------
If you got here without errors then congratulations ! You have just completed
your first successful GnuCash Build. To use this version you can launch the
Windows GnuCash Installer you just built in step d. You can find this installer
in c:\gcdev\gnucash\. It works just like any other installer for a piece of
Windows software: you double-click it and follow the instructions that are
displayed.

At some point you may want to build GnuCash again to get updates. To do so you
should start with updating the GnuCash source files as well as the scripts
used to build GnuCash on Windows.

The former are stored in c:\gcdev\gnucash.git
The latter in c:\gcdev\gnucash-on-windows.git

As the name suggests both are managed by a tool called git. Below is only a
minimal explanation on how to update these directories.
- Open a Windows Explorer
- Right-click on the gnucash-on-windows.git directory
- Select Git Bash. This will open a command prompt.
- Enter one command: git pull
- Close the command prompt again
This example shows how to update gnucash-on-windows.git but the same steps
apply as well for gnucash.git.

If you want to do more advanced things such as modifying code or building
from a git branch other than the default 'master' branch you will need to
familiarize yourself with git more intimately. A good starting point is
http://wiki.gnucash.org/wiki/Git

In general more information with regards to building GnuCash on Windows is
collected on http://wiki.gnucash.org/wiki/Windows/Development

At the time of this writing it should still be adapted to the new build
scripts (2014-05-07).

Known Issues/Things to improve
------------------------------

* It appears that installing html help on Windows systems more recent
  than Windows XP can fail. It looks like the installer triggers a
  Windows authorization dialog. For some reason this dialog can't be
  displayed when the installer is started from an msys shell.

  The workaround is a bit awkward currently and consists of

  1. install html help directly by double-clicking it. Remember to
     install it where the gnucash build scripts expect it ! That is
     c:\gcdev\hh by default.
  2. Inside your msys shell window enter
     these commands:

     pushd /c/gcdev/hh
     _HHCTRL_OCX=$(which hhctrl.ocx || true)
     [ "$_HHCTRL_OCX" ] || die "Did not find hhctrl.ocx"
     pexports -h include/htmlhelp.h $_HHCTRL_OCX > lib/htmlhelp.def
     pushd lib
         dlltool -k -d htmlhelp.def -l libhtmlhelp.a
         mv htmlhelp.lib htmlhelp.lib.bak
     popd
     popd

  3. You can now rerun install.sh which should get past the html help
     installation step

  (Reference: http://lists.gnucash.org/pipermail/gnucash-devel/2014-May/037561.html
   and following messages)

* Error: unrecognized “l” format
  This seems to happen on more recent Windows systems as well, perhaps only
  on 64-bit systems. The cause seems to be that mingw is using a very old
  version of msvcrt.dll which doen't know about the %lld modifier to print
  64-bit integers.
  To work around this you can add a line in custom.sh:
  EXTRA_CFLAGS=" -D__USE_MINGW_ANSI_STDIO"

  The same list message mentioned a couple of additional flags to set
  but these were not explained. For completeness the complete line
  was:

  EXTRA_CFLAGS=" -Wall -Werror -fno-builtin-dgettext -fno-builtin-towupper -fno-builtin-iswlower -ggdb3 -D__USE_MINGW_ANSI_STDIO"
  Adjust as you see fit.

  (Reference: http://lists.gnucash.org/pipermail/gnucash-devel/2014-May/037561.html
   and following messages)

--------------------------------------------
2. Cross-compile GnuCash/win32 on a linux PC
--------------------------------------------
Cross-compiling a Windows/mingw32 executable of GnuCash on a Linux
host system.

Note: as mentioned earlier this part is probably no longer accurate due to
      the heavy changes to the build system in April 2014. It is kept here
      as a reminder to update it and fix any issues encountered.

These steps need to be performed:

1. Look at defaults.sh and create a file named custom.sh to specify adapted
   directory variables.  If you want verbose output of any script
   step, add "set -x" to that file. Particularly for cross-compiling,
   set these variables:
   * cross_compile: should be set to yes
   * GLOBAL_DIR: the base directory for all other directory definitions,
     unless you explicitly override it for some directories.
   * MINGW_DIR: set this to your preferred prefix of the mingw32 gcc/binutils
     on your Linux installation.
     (It is strongly recommended to choose a prefix different
      from your normal compiler tool chain in order to distinguish
      your native vs. cross compiler more easily.)

2. Then run the script create_cross_mingw.sh - it will
   download, compile, and install a mingw32 tool chain.

3. Download a binary windows packages for "guile" e.g. from
   http://www.tu-harburg.de/~et2cs/gnc/ and unpack it into the
   directory $GUILE_DIR as given in defaults.sh. (This is done because
   the build system for guile doesn't support cross-compiling.)

4. Call install.sh, which will read the directory settings from
   defaults.sh/custom.sh. It should download, compile, and install everything
   automatically. Eventually the windows gnucash is installed into
   $GNUCASH_DIR.

5. The content of $GNUCASH_DIR (as well as all the other binary
   packages) should then be copied to a windows machine. The paths
   in $GNUCASH_DIR/bin/gnucash and/or $GNUCASH_DIR/bin/gnucash.cmd
   need to be adjusted for the installation location on the
   windows machine.

Good luck!