Revision as of 02:05, 30 September 2018

Building GnuCash on Linux from the Source Code

This page and the linked pages contains generic instructions for building on many Linux distributions. Some Linux distributions may vary in specific details like:

• the package manager they use to install software from the distribution repositories;
• the names of libraries and header files for compiling libraries in their repositories;
• locations in which libraries and programs are commonly installed.

Where information on these differences is known it will be listed in distribution specific sections for some common distributions in use in the GnuCash community. This information can be used to translate these instructions to those specific distributions. In most cases translation generally involves substituting a package managers name for "apt" which is used in the following and the names of the library files in the repositories of the distributions. The distribution specific sections will contain some information on how you might determine library names on that distribution. The instructions in the following are usually directly applicable directly to Debian/Ubuntu distributions and direct derivatives (although not necessarily all of them). Where such information is not available here, you may need to consult the distribution documentation for the required information. Please feel free to add distribution specific information relevant to these instructions for distribuitions that are not currently listed.

Most distributions have a package manager tool (some have several) that is for installing and removing software from the shell. Many also include a GUI software manager interface which can serve the same function. These are used to install the build tools and dependencies (libraries and development headers) needed to build GnuCash. Some package managers will have a different syntax from that shown for apt (e.g option switches instead of a <command> <target>. If you are not familiar with the command syntax consult the man pages for the package manager on your system to translate the commands from the apt syntax. A table of the names of the package manager front ends on some Linux systems is given here. In some cases the libraries may have slightly different names from those given here as may the development header files. Your package manager will have a command for searching its software repository. Again consultyour distributions documentation. Instructions for installing software will be given here using apt which is the preferred front end on Ubuntu based system.

Setting up to Build GNuCash on Linux

To build GnuCash on a Linux system you will first have to have completed the following steps. Detailed instructions for each step are given on the linked pages.

1. Installing the Build Tools;
2. Getting the GnuCash sources;
3. Installing Google Test;
4. Installing Dependencies.

Building and Installing the GnuCash Program

It is generally a good idea to uninstall any previous versions of GnuCash that you may have installed in the location into which you intend to install your new build. This will remove any unused files and may prevent intererence by any previously installed GnuCash files and libraries. See #Uninstalling Gnucash.

Best practice with CMake requires use of a separate build directory. This may be placed either:

1. inside the top level source directory,
2. at the same level in the parent directory as the top level source directory (gnucash-3.<x>) or
3. at any other suitable location within your home directory.

Note: Some problems have been experienced with some libraries (not currently used in GnuCash but used in the documentation) when the build directory is placed within the top level "gnucash" or gnucash-3.x" source directory.

The cmake command syntax is cmake -D<install-target> <build-options> <build-source>. For further information see Cmake Build Directory Structure Options and Addressing.

1. <install-target> is the location to which you wish to install gnucash on your system (this is actually a build option but has been specified separately for clarity). The format is CMAKE_INSTALL_PREFIX=<value> where <value> is a path specification to an install location. Common locations are:
   1. /usr/local - this location is commonly used for installing locally built versions of applications that should be available to all users on the system. Some distributions may install the version of their software to this location instead of to /usr. If using this location, precede make install with sudo for admin privileges.
   2. /opt - this location is frequently used for user built software. (see comment for /usr/local regarding use of this location).
   3. $HOME/.local - in your home directory. Requires adding $HOME/.local/bin to $PATH environment variable. Use export PATH=$PATH:$HOME/.local/bin at a shell prompt to set PATH for that shell. To make the changes to PATH permanent, you can add this command to the file .profile or the file .bashrc in your home directory. $HOME is usually defined by default as /home/<user> where <user> is the logged in user name. If not enter export HOME=/home/<user> in the shell or add this command to /home/<user>/.profile (or .bashrc) to make it permanent.
2. <build-options> are 0 or more CMake option choices, blank separated, of the form -D <option> =<value> where <option> is one of the Gnucash Build Options for CMake. Currently the default GnuCash build includes all optional features except the Python bindings. Other options enable features like debugging information etc.
3. <build-source> is either an absolute reference to the top level gnucash-3.<x> directory or a relative reference to it from the build directory, where ever that is located. For the case illustrated below, <build-source> = ../gnucash-3.<x>;

Open a shell and change directory to the directory into which you extracted the GnuCash sources (gnucash-3.x) or cloned the github repository (gnucash), i.e. the parent directory of gnucash-3.<x> or gnucash.

Build using Cmake and Make

mkdir build-gnucash-3.<x>                 # create the build directory - Note: Named to identify the source since it is not within the source directory.
cd build-gnucash-3.<x>                    # change into the build directory
cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local -DCMAKE_PREFIX_PATH=$HOME/.local ../gnucash-3.<x>     # As shown this will install in the .local directory in /home/<user>.  
make                                      # builds the program and associated libraries
make install                              # prefix with sudo if you do install to /usr/local or /opt as admin privileges are required.

Build using CMake and Ninja

mkdir build-gnucash-3.<x>                # create the build directory - Note: Named to identify the source since it is not within the source directory.
cd build-gnucash-3.<x>                   # change into the build directory
cmake -GNinja -DCMAKE_INSTALL_PREFIX=$HOME/.local ../gnucash-3.<x>     # As shown this will install in the .local directory in /home/<user>.  
ninja                                    # builds the program and associated libraries
ninja install                            # prefix with sudo if you do install to /usr/local or /opt as admin privileges are required.

Both ninja and make support a number of targets supplied as an argument to the command. Some of the more useful are:

Configuration_Locations

For information on directories where configuration information for GnuCash is located for Linux, Windows and MacOSX follow the link in the heading.

Running GnuCash

Installed in /home/<user>/.local

To run GnuCash type in a shell

/home/<user>/.local/bin/gnucash

Alternatively you could use one of the following:

$HOME/.local/bin/gnucash       # HOME environment variable is usually defined on Linux systems.
~/.local/bin/gnucash           # "~" translates to /home/<user> on Linux systems. Note not portable on all systems and may not always be expanded

One could also define an alias for the path to the GnuCash executable to reduce the typing burden, e.g.:

alias gnucash='$HOME/.local/bin/gnucash"

Another alternative is to add the directory containing the GnuCash executable to the PATH environment variable. Edit "/home/<user>/.profile" with a text editor and add :

PATH=$PATH:$HOME/.local/bin      # RHS does not need to be quoted. As PATH is defined export is not required to change the value

Another alternative is to use your system's menu editor to add a launcher for gnucash. This typically involves entering or selecting the path to the executable and providing a path to a suitable icon for display. The GnuCash icon is found at $HOME/.local/share/icons/hicolor/16x16/apps/gnucash-icon.png.

Uninstalling GnuCash

If you built GnuCash and you have retained the source directory and the build directory on your system, use the first set of instructions in Uninstall Gnucash Linux. The other sections list other methods for removing GnuCash depending upon how it was originally installed.

Distribution Specific Issues