Difference between revisions of "Building On Linux"

From GnuCash
Jump to: navigation, search
(→‎Uninstalling GnuCash)
m (Abstract: Move Debian before its derivate Ubuntu)
 
(105 intermediate revisions by 12 users not shown)
Line 1: Line 1:
 +
[[Category:Building]] [[Category:Linux]]
 +
{| class="wikitable" style="margin: auto;"
 +
! scope="row"|Languages
 +
| [[de/{{PAGENAME:Gnucash}}|Deutsch]]
 +
| [[He/{{PAGENAME:בניה בלינוקס}}|עִברִית]]
 +
|}
 +
This page and the linked pages contains generic instructions for building on Linux distributions and perhaps similar OSes.
 +
 +
A page named [[Debian]] includes similar background, installation procedures and building suggestions for Debian and its derivative distributions like Ubuntu. A separate page, [[Building On Ubuntu]], describes Ubuntu and Ubuntu-based distributions (such as Linux Mint) including step-by-step instructions and known issues.
 +
 
= Building GnuCash on Linux from the Source Code =
 
= 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:
+
Some Linux distributions may vary in specific details like:
−
* the package manager they use to install software from the distribution repositories;  
+
* the [[Package_Managers|package manager]] used to install software;  
−
* the names of libraries and header files for compiling libraries in their repositories;
+
* the names of libraries and header files for compiling libraries;
 
* locations in which libraries and programs are commonly installed.
 
* 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 [[Package_Managers | 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.
+
The instructions here use commands common to many (but not necessarily all) Debian/Ubuntu distributions. For other distributions, consult that distribution's documentation for the required information. For a list of package managers for common distributions and examples of their commands, see the [[Package_Managers|Package Managers]] page.
−
== 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 instructios for each step are given on the linked pages.
+
Many distributions have a GUI software manager interfaces which can be used to manage installation. These are used to install the build tools and dependencies (libraries and development headers) needed to build GnuCash. If you are not familiar with the command syntax of your distribution's package manager, consult the man pages. See the [[Package_Managers|Package Managers page]] for a listing of front ends on some Linux systems.  
 +
 
 +
== 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.
 
#[[Install_Build_Tools |Installing the Build Tools]];
 
#[[Install_Build_Tools |Installing the Build Tools]];
 
#[[GnuCash_Sources | Getting the GnuCash sources]];
 
#[[GnuCash_Sources | Getting the GnuCash sources]];
Line 15: Line 27:
  
 
== Building and Installing the GnuCash Program ==
 
== 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]].
+
 
 +
The easy way to install most of GnuCash's dependencies is to use your package manager's '''build dependencies feature''' as root:
 +
<Syntaxhighlight lang="sh">
 +
apt-get build-dep gnucash        # Debian based
 +
yum-builddep gnucash              # RedHat based, but
 +
dnf builddep gnucash              # Fedora (recent)
 +
zypper source-install -d gnucash  # Opensuse
 +
</Syntaxhighlight>
 +
You can do the same for <tt>gnucash-docs</tt>.
 +
;Note: This will install the dependencies of your distributions version. If it is not from the {{MainVersion}}.x branch, there may be a few changed dependencies which you will still have to resolve.
 +
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 interference 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:
 
Best practice with CMake requires use of a separate build directory. This may be placed either:
 
# inside the top level source directory,  
 
# inside the top level source directory,  
−
# at the same level in the parent directory as the top level source directory (gnucash-3.<x>) or  
+
# at the same level in the parent directory as the top level source directory (gnucash-4.<x>) or  
 
# at any other suitable location within your home directory.  
 
# 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.
+
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-4.x" source directory.
 +
 
 +
=== Locations to which GnuCash may be installed ===
 +
The choosen path is stored as '''${PREFIX}''' in the build environment.
 +
==== System wide multiuser installation locations ====
 +
Installation for system wide use by all users requires that the user doing the installation has an account with administrator privileges on the system (requires use of the sudo or su command to grant privileges). Locally installed software is normally installed with /usr/local as the base directory on Linux systems under the [https://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.pdf Linux File System Hierarchy]. Software from the distribution software repository will normally install in this location so that it is unaffected by changes/updates to the system software which is normally located with /usr as the base directory. Usually software built on the system will be located under /opt as its base dircectory and packages installed in this location must have a directory labelled with the package name (or a registered provider name). (Some distributions may differ from this - if so consult the distribution documentation.)
 +
{| class= "wikitable"
 +
|+ Common Linux system install locations
 +
! Location
 +
!Comment
 +
|-
 +
|'''/usr'''
 +
| style="color:red"| Commonly used for software installed from distribution software repositories. Should never be used for user installed software -including '''/usr/bin, /usr/etc, /usr/lib, /usr/share'''. These locations may be overwritten during system updates.
 +
|-
 +
|'''/usr/local'''
 +
| Used by system administrator (you on single user systems) to install packages. It can be used to install GnuCash from a build '''/usr/local''' has '''bin, etc, lib''' and '''share''' subdirectories. GnuCash components are installed into these sub-directories.
 +
;Suggestion: Run <tt>sudo make uninstall</tt> ''before'' you build a new version.
 +
|-
 +
|'''/opt'''
 +
| Preferred location for user built software available to the system. Requires installation under a ''directory with the packagename'' e.g. '''/opt/gnucash''' which will contain directories '''/opt/gnucash/bin, /opt/gnucash/etc, /opt/gnucash/lib''' and '''/opt/gnucash/share'''.
 +
;Note: The GnuCash build process handles this requirement if you choose '''/opt''' as the '''CMAKE_INSTALL_PREFIX''' location. Software installed in this location can be initiated by creating a symlink from '''/usr/bin''' or '''/usr/local/bin''' to the executable or by defining an alias which includes the path to the executable.
 +
;See also: [https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch03s13.html File Hierarchy Standard 3.0 about /opt]
 +
|-
 +
|}
 +
 
 +
==== Installation in a User's Home Directory for a Single User ====
 +
Installation under the user's home directory is necessary for users who
 +
:do not have admin privileges and
 +
:cannot get a system administrator to install software for them.
 +
 
 +
The Linux File System Hierarchy does not specify any standard structures for users home directories. The Free Desktop Software Foundation maintains the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG standard] however this does not specify a location for local installation of software. Previously we have suggested installing GnuCash under the users '''.local''' hidden directory, '''/home/<user>/.local'''. This however conflicts with the use of '''/home/<user>/.local/share/gnucash''' to store user preference and customization data as the build also creates a '''gnucash''' directory in this location. For clarity we will use and recommend '''/home/<user>/opt''' in the following to parallel the '''/opt''' system location. This is the location recommended for inexperienced users with no or litle software building and installation experience on Linux systems. More experienced users may use any directory they like under their home directory.
 +
 
 +
Substitute '''<user>''' in the above and the following with the user's '''''username''''' on the computer on which GnuCash being installed. On most Linux systems the environmental variable '''HOME''' is defined as '''/home/<user>''' and can be used in commands in the terminal by prefixing it with '''$''', i.e. using '''$HOME''' in a command will substitute '''/home/<user>''' into the command.
 +
{| class ="wikitable"
 +
|+ Recommended Single User Location in User's Home Directory
 +
! Location
 +
! Comment
 +
|-
 +
|$HOME/.local
 +
| Recommended location to install ''stable releases'' of gnucash as a single user application.
 +
|-
 +
|$HOME/opt
 +
| Recommended location to install gnucash for tests ''while developing''.
 +
|-
 +
|}
  
 
The cmake command syntax is '''cmake -D<install-target> <build-options> <build-source>'''. For further information see [[CMake Addressing | Cmake Build Directory Structure Options and Addressing.]]
 
The cmake command syntax is '''cmake -D<install-target> <build-options> <build-source>'''. For further information see [[CMake Addressing | Cmake Build Directory Structure Options and Addressing.]]
Line 28: Line 94:
 
## '''/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.
 
## '''/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.
 
## '''/opt'''            - this location is frequently used for user built software. (see comment for /usr/local regarding use of this location).
 
## '''/opt'''            - this location is frequently used for user built software. (see comment for /usr/local regarding use of this location).
−
## '''$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 <code>export HOME=/home/<user></code> in the shell or add  this command to /home/<user>/.profile (or .bashrc) to make it permanent.
+
## '''$HOME/opt/gnucash'''    - in your home directory. Requires adding $HOME/opt/gnucash/bin to $PATH environment variable. Use export PATH=$PATH:$HOME/opt/gnucash/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 (Note Other distributions may use different files for this purpose. Consult recommendations for your Linux distribution). $HOME is usually defined by default as /home/<user> where <user> is the logged in user name. If not enter <code>export HOME=/home/<user></code> in the shell or add  this command to /home/<user>/.profile (or .bashrc) to make it permanent.
 
# '''<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.
 
# '''<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.
−
# '''<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>;
+
# '''<build-source>''' is either an absolute reference to the top level gnucash-4.<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-4.<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.
+
Open a shell and change directory to the directory into which you extracted the GnuCash sources (gnucash-4.x) or cloned the github repository (gnucash), i.e. the parent directory of gnucash-4.<x> or gnucash.
 +
 
 
=== Build using Cmake and Make ===
 
=== Build using Cmake and Make ===
−
<SyntaxHighlight lang="sh">
+
<SyntaxHighlight lang="bash">
−
mkdir build-gnucash-3.<x>                # create the build directory - Note: Named to identify the source since it is not within the source directory.
+
mkdir build-gnucash-4.<x>                # create the build directory - Note: Named to identify the source since it is not necessarily within the source directory.
−
cd build-gnucash-3.<x>                    # change into the build directory
+
cd build-gnucash-4.<x>                    # change into the build directory
−
cmake -D CMAKE_INSTALL_PREFIX=$HOME/.local ../gnucash-3.<x>    # As shown this will install in the .local directory in /home/<user>.   
+
cmake -DCMAKE_INSTALL_PREFIX=$HOME/opt  ../gnucash-4.<x>    # As shown this will install in the opt directory in /home/<user>.   
 
make                                      # builds the program and associated libraries
 
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.
 
make install                              # prefix with sudo if you do install to /usr/local or /opt as admin privileges are required.
 
</SyntaxHighlight>
 
</SyntaxHighlight>
 +
 
=== Build using CMake and Ninja ===
 
=== Build using CMake and Ninja ===
−
<SyntaxHighlight lang="sh">
+
<SyntaxHighlight lang="bash">
−
mkdir build-gnucash-3.<x>                # create the build directory - Note: Named to identify the source since it is not within the source directory.
+
mkdir build-gnucash-4.<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
+
cd build-gnucash-4.<x>                  # change into the build directory
−
cmake -GNinja -D CMAKE_INSTALL_PREFIX=$HOME/.local ../gnucash-3.<x>    # As shown this will install in the .local directory in /home/<user>.   
+
cmake -GNinja -DCMAKE_INSTALL_PREFIX=$HOME/opt ../gnucash-4.<x>    # As shown this will install in the opt directory in /home/<user>.   
 
ninja                                    # builds the program and associated libraries
 
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.
 
ninja install                            # prefix with sudo if you do install to /usr/local or /opt as admin privileges are required.
 
</SyntaxHighlight>
 
</SyntaxHighlight>
 +
 +
Both ninja and make support a number of targets supplied as an argument to the command. Some of the more useful are:
 +
 +
{|class = "wikitable"
 +
! Target
 +
! Description
 +
|-
 +
|all
 +
| build all libraries and the program
 +
|-
 +
|install
 +
|install the program and libraries
 +
|-
 +
|install/strip
 +
|remove debugging information - useful for release
 +
|-
 +
|install/local
 +
|install in  /usr/local  (requires admin privileges - prefix with sudo)
 +
|-
 +
|check
 +
|build and run the unit tests
 +
|-
 +
|clean
 +
|remove all files produced by the build (compiled object
 +
|-
 +
|help
 +
|list all build targets
 +
|-
 +
|}
 +
 +
'''Note:''' Information on current build issues with Linux distributions is available from [[#Distribution Specific Issues]].
 +
 +
=== [[Configuration_Locations]] ===
 +
For information on directories where configuration information for GnuCash is located for Linux, Windows and macOS follow the link in the heading.
  
 
== Running GnuCash ==
 
== Running GnuCash ==
 +
=== Installed in /home/<user>/opt ===
 +
To run GnuCash type in a shell
 +
<syntaxhighlight lang="bash">
 +
/home/<user>/opt/bin/gnucash
 +
</syntaxhighlight>
 +
Alternatively you could use one of the following:
 +
<syntaxhighlight lang="bash">
 +
$HOME/opt/bin/gnucash      # HOME environment variable is usually defined on Linux systems.
 +
~/opt/bin/gnucash          # "~" translates to /home/<user> on Linux systems. Note not portable on all systems and may not always be expanded
 +
</syntaxhighlight>
 +
One could also define an alias for the path to the GnuCash executable to reduce the typing burden, e.g.:
 +
<syntaxhighlight lang="bash">
 +
alias gnucash="$HOME/opt/bin/gnucash"
 +
</syntaxhighlight>
 +
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 one of the following:
 +
<syntaxhighlight lang="bash">
 +
PATH=$PATH:$HOME/opt/bin      # your home directory will be searched after the system directories
 +
PATH=$HOME/opt/bin:$PATH      # this will search your home directory before the system directories
 +
</syntaxhighlight>
 +
Note: The right hand side in the above does not need to be quoted and "~" is not used because it may not expand correctly
 +
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/opt/share/icons/hicolor/<nn>x<nn>/apps/gnucash-icon.png. Here <nn> is a 2 digit number giving the icon size (<nn> ={16,22,24,32,48,64,96,128,256}. There is also a scalable icon image in a scalable directory in addition to the <nn>x<nn> labelled directories.
 +
 +
=== Installed in /usr/local ===
 +
<tt>/usr/local/bin</tt> is normally included in the <tt>PATH</tt> environment variable on most Linux systems. Type
 +
<syntaxhighlight lang="bash">
 +
echo $PATH
 +
</syntaxhighlight> at a shell prompt to check this.
 +
You can type the following at a shell prompt to execute GnuCash
 +
<syntaxhighlight lang="bash">
 +
gnucash
 +
</syntaxhighlight>.
 +
A menu launcher can besetup using your system's menu editor. Here you will only have to enter "gnucash" and not the full path. In this case the icon can be found at <tt>/usr/local/share/icons/hicolor/<nn>x<nn>/apps/gnucash-icon.png</tt> with <nn> = {16, 22, 24, 32, 48, 64, 96, 128, 256} as above.
 +
 +
=== Installed in /opt ===
 +
 +
In this case /opt is not normally included in the PATH environment variable. Often software installed  here may be installed within a self named parent directory, e.g.
 +
*/opt/gnucash
 +
with subdirectories:
 +
*/opt/gnucash/bin
 +
*/opt/gnucash/lib
 +
*/opt/gnucash/etc
 +
*/opt/gnucash/share
 +
into which the program components are stored.
 +
As described above in the $HOME/.local installation the program can be executed using the full path to the executable in a shell by typing:
 +
<syntaxhighlight lang="bash">
 +
/opt/gnucash/bin/gnucash
 +
</syntaxhighlight>.
 +
Again one can add the path to the executable to the PATH environment variable by adding:
 +
<syntaxhighlight lang="bash">
 +
PATH=$PATH:/opt/gnucash/bin  # search system paths first then /opt/gnucash/bin
 +
PATH=/opt/gnucash/bin:$PATH  # search /opt/gnucash/bin before system paths
 +
</syntaxhighlight>
 +
 +
and then simply type <code>gnucash</code> at the prompt.
 +
 +
You may also setup a menu launcher using the menu editing process for the executable and an add icon as described above. Here the icons will be located in /opt/gnucash/share/icons/hicolor/<nn>x<nn>/apps/gnucash-icon.png
 +
 
== Uninstalling GnuCash ==
 
== Uninstalling GnuCash ==
−
If you built GnuCash and you have retained the source directory and the build directory on your system, use the following command issued in a shell opened in the build directory from which you installed 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.
−
<SyntaxHighlight lang="sh">
 
−
make uninstall            # prefix with sudo if you installed in system locations like /usr/local or /opt.
 
−
</SyntaxHighlight>
 
−
'''Note:'''Both the source directory and the build directory are necessary as the uninstall target runs a check of the build system integrity which checks files in the source directories.
 
−
If you no longer have the source and  build directories you installed from or your previous version was a distribution version see [[Uninstall Gnucash Ubuntu]] for other options.
 
−
 
 
−
==Distribution Specific Issues ==
 

Latest revision as of 18:05, 29 December 2023

Languages Deutsch עִברִית

This page and the linked pages contains generic instructions for building on Linux distributions and perhaps similar OSes.

A page named Debian includes similar background, installation procedures and building suggestions for Debian and its derivative distributions like Ubuntu. A separate page, Building On Ubuntu, describes Ubuntu and Ubuntu-based distributions (such as Linux Mint) including step-by-step instructions and known issues.

Building GnuCash on Linux from the Source Code

Some Linux distributions may vary in specific details like:

  • the package manager used to install software;
  • the names of libraries and header files for compiling libraries;
  • locations in which libraries and programs are commonly installed.

The instructions here use commands common to many (but not necessarily all) Debian/Ubuntu distributions. For other distributions, consult that distribution's documentation for the required information. For a list of package managers for common distributions and examples of their commands, see the Package Managers page.

Many distributions have a GUI software manager interfaces which can be used to manage installation. These are used to install the build tools and dependencies (libraries and development headers) needed to build GnuCash. If you are not familiar with the command syntax of your distribution's package manager, consult the man pages. See the Package Managers page for a listing of front ends on some Linux systems.

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

The easy way to install most of GnuCash's dependencies is to use your package manager's build dependencies feature as root: 

apt-get build-dep gnucash         # Debian based
yum-builddep gnucash              # RedHat based, but
dnf builddep gnucash              # Fedora (recent)
zypper source-install -d gnucash  # Opensuse

You can do the same for gnucash-docs.

Note
This will install the dependencies of your distributions version. If it is not from the 5.x branch, there may be a few changed dependencies which you will still have to resolve.

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 interference 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-4.<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-4.x" source directory.

Locations to which GnuCash may be installed

The choosen path is stored as ${PREFIX} in the build environment.

System wide multiuser installation locations

Installation for system wide use by all users requires that the user doing the installation has an account with administrator privileges on the system (requires use of the sudo or su command to grant privileges). Locally installed software is normally installed with /usr/local as the base directory on Linux systems under the Linux File System Hierarchy. Software from the distribution software repository will normally install in this location so that it is unaffected by changes/updates to the system software which is normally located with /usr as the base directory. Usually software built on the system will be located under /opt as its base dircectory and packages installed in this location must have a directory labelled with the package name (or a registered provider name). (Some distributions may differ from this - if so consult the distribution documentation.)

Common Linux system install locations
Location Comment
/usr Commonly used for software installed from distribution software repositories. Should never be used for user installed software -including /usr/bin, /usr/etc, /usr/lib, /usr/share. These locations may be overwritten during system updates.
/usr/local Used by system administrator (you on single user systems) to install packages. It can be used to install GnuCash from a build /usr/local has bin, etc, lib and share subdirectories. GnuCash components are installed into these sub-directories.
Suggestion
Run sudo make uninstall before you build a new version.
/opt Preferred location for user built software available to the system. Requires installation under a directory with the packagename e.g. /opt/gnucash which will contain directories /opt/gnucash/bin, /opt/gnucash/etc, /opt/gnucash/lib and /opt/gnucash/share.
Note
The GnuCash build process handles this requirement if you choose /opt as the CMAKE_INSTALL_PREFIX location. Software installed in this location can be initiated by creating a symlink from /usr/bin or /usr/local/bin to the executable or by defining an alias which includes the path to the executable.
See also
File Hierarchy Standard 3.0 about /opt

Installation in a User's Home Directory for a Single User

Installation under the user's home directory is necessary for users who

do not have admin privileges and
cannot get a system administrator to install software for them.

The Linux File System Hierarchy does not specify any standard structures for users home directories. The Free Desktop Software Foundation maintains the XDG standard however this does not specify a location for local installation of software. Previously we have suggested installing GnuCash under the users .local hidden directory, /home/<user>/.local. This however conflicts with the use of /home/<user>/.local/share/gnucash to store user preference and customization data as the build also creates a gnucash directory in this location. For clarity we will use and recommend /home/<user>/opt in the following to parallel the /opt system location. This is the location recommended for inexperienced users with no or litle software building and installation experience on Linux systems. More experienced users may use any directory they like under their home directory.

Substitute <user> in the above and the following with the user's username on the computer on which GnuCash being installed. On most Linux systems the environmental variable HOME is defined as /home/<user> and can be used in commands in the terminal by prefixing it with $, i.e. using $HOME in a command will substitute /home/<user> into the command.

Recommended Single User Location in User's Home Directory
Location Comment
$HOME/.local Recommended location to install stable releases of gnucash as a single user application.
$HOME/opt Recommended location to install gnucash for tests while developing.

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/opt/gnucash - in your home directory. Requires adding $HOME/opt/gnucash/bin to $PATH environment variable. Use export PATH=$PATH:$HOME/opt/gnucash/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 (Note Other distributions may use different files for this purpose. Consult recommendations for your Linux distribution). $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-4.<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-4.<x>;

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

Build using Cmake and Make

mkdir build-gnucash-4.<x>                 # create the build directory - Note: Named to identify the source since it is not necessarily within the source directory.
cd build-gnucash-4.<x>                    # change into the build directory
cmake -DCMAKE_INSTALL_PREFIX=$HOME/opt  ../gnucash-4.<x>     # As shown this will install in the opt 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-4.<x>                # create the build directory - Note: Named to identify the source since it is not within the source directory.
cd build-gnucash-4.<x>                   # change into the build directory
cmake -GNinja -DCMAKE_INSTALL_PREFIX=$HOME/opt ../gnucash-4.<x>     # As shown this will install in the opt 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:

Target Description
all build all libraries and the program
install install the program and libraries
install/strip remove debugging information - useful for release
install/local install in /usr/local (requires admin privileges - prefix with sudo)
check build and run the unit tests
clean remove all files produced by the build (compiled object
help list all build targets

Note: Information on current build issues with Linux distributions is available from #Distribution Specific Issues.

Configuration_Locations

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

Running GnuCash

Installed in /home/<user>/opt

To run GnuCash type in a shell 

/home/<user>/opt/bin/gnucash

Alternatively you could use one of the following: 

$HOME/opt/bin/gnucash       # HOME environment variable is usually defined on Linux systems.
~/opt/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/opt/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 one of the following: 

PATH=$PATH:$HOME/opt/bin      # your home directory will be searched after the system directories
PATH=$HOME/opt/bin:$PATH      # this will search your home directory before the system directories

Note: The right hand side in the above does not need to be quoted and "~" is not used because it may not expand correctly 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/opt/share/icons/hicolor/<nn>x<nn>/apps/gnucash-icon.png. Here <nn> is a 2 digit number giving the icon size (<nn> ={16,22,24,32,48,64,96,128,256}. There is also a scalable icon image in a scalable directory in addition to the <nn>x<nn> labelled directories.

Installed in /usr/local

/usr/local/bin is normally included in the PATH environment variable on most Linux systems. Type 

echo $PATH
at a shell prompt to check this.

You can type the following at a shell prompt to execute GnuCash 

gnucash
.

A menu launcher can besetup using your system's menu editor. Here you will only have to enter "gnucash" and not the full path. In this case the icon can be found at /usr/local/share/icons/hicolor/<nn>x<nn>/apps/gnucash-icon.png with <nn> = {16, 22, 24, 32, 48, 64, 96, 128, 256} as above.

Installed in /opt

In this case /opt is not normally included in the PATH environment variable. Often software installed here may be installed within a self named parent directory, e.g.

  • /opt/gnucash

with subdirectories:

  • /opt/gnucash/bin
  • /opt/gnucash/lib
  • /opt/gnucash/etc
  • /opt/gnucash/share

into which the program components are stored. As described above in the $HOME/.local installation the program can be executed using the full path to the executable in a shell by typing: 

/opt/gnucash/bin/gnucash
.

Again one can add the path to the executable to the PATH environment variable by adding: 

PATH=$PATH:/opt/gnucash/bin  # search system paths first then /opt/gnucash/bin
PATH=/opt/gnucash/bin:$PATH  # search /opt/gnucash/bin before system paths

and then simply type gnucash at the prompt.

You may also setup a menu launcher using the menu editing process for the executable and an add icon as described above. Here the icons will be located in /opt/gnucash/share/icons/hicolor/<nn>x<nn>/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.

Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=Building_On_Linux&oldid=21979"