Difference between revisions of "Configuration Locations"

From GnuCash
Jump to: navigation, search
m (TODO integrate background info below: This has been incorporated in the Directory section)
(Add section with methods to override default directory locations and drop XDG section. The relevant parts have been incorporated, for more details refer to Directories page)
Line 53: Line 53:
  
 
=== USER_CONFIG_HOME ===
 
=== USER_CONFIG_HOME ===
This directory is used to configuration files for applications. The difference between "configuration files" and "application data that can't be stored with the main data file" is subtle. On Windows and Macos for example there is no difference between the two and the same directories will be used for USER_DATA_HOME and USER_CONFIG_HOME. On linux GnuCash will roughly make a distinction on whether the file is intended to be created/modified by the user (USER_CONFIG_HOME) or by GnuCash itself (USER_DATA_HOME). I believe Gtk3 maintains a similar strategy.
+
This directory is used to configuration files for applications. The difference between "configuration files" and "application data that can't be stored with the main data file" is subtle. On Windows for example there is no difference between the two and USER_DATA_HOME will be used. On linux GnuCash will roughly make a distinction on whether the file is intended to be created/modified by the user (USER_CONFIG_HOME) or by GnuCash itself (USER_DATA_HOME). I believe Gtk3 maintains a similar strategy. On Macos it's a bit more complicated as GnuCash will use USER_DATA_HOME for all GnuCash own configuration files, but another directory for all of its support libraries.
  
 
Default locations:
 
Default locations:
Line 119: Line 119:
  
  
 +
== How to override default locations ==
  
== TODO integrate background info below ==
+
The [[#Directories]] section above shows default locations used on different operating systems. Sometimes there locations are not convenient. There are several ways to alter them (or your system already alters them for you using one of the below methods).
  
=== Override methods for the above files and directories (Todo) ===
+
=== Environment variable GNC_DATA_HOME ===
  
=== XDG_* Variables ===
+
'''Platforms:''' All
  
The XDG_* variables come from a free desktop specification [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html (1)] that defines a
+
When a directory is specified via this environment variable GnuCash will unconditionally use that directory as GNC_DATA_HOME, provided this directory exists and is writable or can be created writable. This override will take the highest precedence and works on all operating systems.
number standard directories and paths that each system that claims to follow
 
this standard should adhere to. Most desktop environments (kde, gnome,
 
xfce,...) on linux do adhere to this so they can interoperate properly. Many
 
programs rely on this, and gnucash is no exception as it's based on gtk (which
 
underpins the gnome desktop environment as well).
 
  
There are two that gnucash uses as of gnucash 3.0 and related to user data:
+
=== Environment variable XDG_DATA_HOME ===
;XDG_DATA_HOME: (defaults to <tt>~/.local/share</tt> on linux)
 
;XDG_CONFIG_HOME: (defaults to <tt>~/.config</tt> on linux)
 
  
On systems that follow the XDG specification, users can override either by
+
'''Platforms:''' Linux, macos
setting environment variables with these names. In practice this is everywhere
 
except on Windows and in the Quartz version of gnucash. Both of these instead
 
use the platform specific default paths and will ignore the XDG_* settings
 
[2].
 
  
As you may observe neither path is specific to gnucash. These directories are
+
This environment variable can be used to directly set USER_DATA_HOME. As such it will affect the base directory for GNC_DATA_HOME and GTK_DATA_HOME. On macos this will only affect GTK_DATA_HOME.
shared by all applications adherering to the above specification. So in order
 
to keep these directories tidy, most applications make an application specific
 
subdirectory in there. For gnucash on linux these are (predictably)
 
~/.local/share/gnucash
 
~/.config/gnucash
 
  
The former can be overridden by setting GNC_DATA_HOME, the latter can't be
+
;Note: The [[Directories]] page has some background information on the origin of the XDG_ environment variables.
overridden (that's an oversight, not intentional).
 
  
Lastly, the 2.6 .gnucash dir has no one to one mapping to a directory under 3.0. In fact it's content has been distributed over the two directories above. The rationale is this:
+
=== Environment variable XDG_CONFIG_HOME ===
  
Any configuration file we expect the user to tweak manually should go in config/gnucash. GnuCash will never alter any file in there (except for the one-time initial migration. Any file we don't expect the user to tweak manually (as it's written and maintained by gnucash itself) should go into local/share/gnucash. We expect users to not touch these files directly and
+
'''Platforms:''' Linux, macos
gnucash can overwrite these at any time.
 
  
Files that should go in <tt>.config</tt> are things like a customized css file, a config file with custom scheme code, ...
+
This environment variable can be used to directly set USER_CONFIG_HOME. As such it will affect the base directory for GNC_CONFIG_HOME and GTK_CONFIG_HOME. On macos this will only affect GTK_CONFIG_HOME.
  
Files that still go in <tt>.local/share</tt> are saved reports (gnucash manages these), state files, style sheets,...
+
There is a caveat here though: on macos GnuCash will set XDG_CONFIG_HOME itself via <bundle>/Resources/etc/gnucash/environment. The only way to override XDG_CONFIG_HOME on this platform is via [[#File environment.local]] and this should be repeated each time a GnuCash update is installed.
  
Currently the accelerator-maps are also still stored in there, but I believe this is a mistake as well that should be corrected at some point.
+
;Note: The [[Directories]] page has some background information on the origin of the XDG_ environment variables.
 +
 
 +
=== Environment variables LOCALAPPDATA and APPDATA ===
 +
 
 +
'''Platforms:''' Windows
 +
 
 +
By setting these environment variables USER_DATA_HOME (and by extension USER_CONFIG_HOME) can be set directly on Windows. Hence depending on which of these two is altered this directly affects GNC_DATA_HOME/GNC_CONFIG_HOME (in case of APPDATA) or GTK_DATA_HOME/GTK_CONFIG_HOME (in case of LOCALAPPDATA).
 +
 
 +
Note you probably don't want to change these environment variables system wide as that would affect all applications on your system.
 +
 
 +
=== File environment.local ===
 +
 
 +
'''Platforms:''' All
 +
 
 +
All of the above environment variables can also be set for GnuCash only by creating a file named <tt>environment.local</tt> next to the file named <tt>environment</tt> in the gnucash installation. The typical location for this environment file is platform dependent:
 +
 
 +
;Linux: <tt>/etc/gnucash/environment</tt> or more generally <tt><installprefix>/etc/gnucash/environment</tt>
 +
;Windows: <tt>c:\Program Files(x86)\GnuCash\etc\GnuCash\environment</tt>
 +
;Macos (formerly OS X): <tt><GnuCash.app>/Resources/etc/GnuCash/environment</tt>
 +
 
 +
The format of the environment.local file is explained at the top of the environment file.
 +
 
 +
;Note: while on Macos this works there is an issue when updating gnucash. Each time you update your gnucash package environment.local will be removed. So you may want to keep a copy of the file outside of the application bundle that you can put back after each update.

Revision as of 11:49, 25 June 2018

This article describes the configuration file locations as they related to GnuCash v3.0. Originally posted by Geert in a mailing list thread.

TODO: Overlaps with Directories.

GnuCash 3.0 will read several configuration files in different directories. And several pages on this wiki will refer to one or more of these. As these directories often differ between operating systems and may be overridden in several ways, this page will attempt to give an overview. What each file does can be found on other pages instead.

Directories

Let's start with defining a few common directory locations that will be referred to regularly.

HOME

The user's home directory on your computer. While this may be obvious I'm mentioning it here as it's the base directory for several others below. The usual locations per OS are:

Linux
/home/<username> - for example /home/johndoe
Note that in a linux context this directory is also often referred to as $HOME or ~/
Windows
c:\Users\<username> - for example c:\Users\johndoe
Macos (formerly OS X)
/Users/<username> - for example /Users/johndoe

In the following directories I will simply refer to this base directory as HOME.

USER_DATA_HOME

This directory can be used by applications to store data that can't be stored in the user's data file for some reason. For example gnucash will store saved reports here, or some metadata such as which register tabs were open for your books last time you closed them. The default locations:

Linux
HOME/.local/share
Windows
On this platform there are actually two directories for this kind of data:
HOME\AppData\Local, often referred to as %LOCALAPPDATA%
HOME\AppData\Roaming, often referred to as %APPDATA%
The reason for having two is not important in the scope of this page.
Note %APPDATA% is a hidden directory. However if you type %APPDATA% directly in the location bar of your Windows Explorer you will see its contents directly. Similarly you can also directly access %LOCALAPPDATA%.
Macos (formerly OS X)
On this platform there are actually two directories for this kind of data:
HOME/Library/Application Support
HOME/.local/share
The former is native to Macos (and will be used by GnuCash), the latter is often used by software that's ported from linux (like Gtk3). The difference will get clearer further down.

It's important to understand this directory is shared by all applications you run on your system. So aside from gnucash, applications like Firefox, Microsoft Office, LibreOffice and so on will also write here. To avoid clutter most applications have the courtesy to create their own subdirectory in here and only write in that subdirectory. This leads us seamlessly to the next couple of important directories:

GNC_DATA_HOME

This is the subdirectory in USER_DATA_HOME GnuCash uses exclusively for it's user specific data. The default locations:

Linux
USER_DATA_HOME/gnucash
Windows
%APPDATA%\GnuCash
Macos (formerly OS X)
HOME/Library/Application Support/GnuCash

To note is that on Windows the base directory is APPDATA and on OS X this is HOME/Library/Application Support. The base directories will be different for the next relevant directory:

GTK_DATA_HOME

As gnucash is using Gtk for its graphical user interface, locations that are used by Gtk are also relevant. Note the base directories on Windows and Macos for this one differ from the base directories for GNC_DATA_HOME.

Linux
USER_DATA_HOME/gtk-3.0
Windows
%LOCALAPPDATA%\gtk-3.0
Macos (formerly OS X)
HOME/.local/share/gtk-3.0

USER_CONFIG_HOME

This directory is used to configuration files for applications. The difference between "configuration files" and "application data that can't be stored with the main data file" is subtle. On Windows for example there is no difference between the two and USER_DATA_HOME will be used. On linux GnuCash will roughly make a distinction on whether the file is intended to be created/modified by the user (USER_CONFIG_HOME) or by GnuCash itself (USER_DATA_HOME). I believe Gtk3 maintains a similar strategy. On Macos it's a bit more complicated as GnuCash will use USER_DATA_HOME for all GnuCash own configuration files, but another directory for all of its support libraries.

Default locations:

Linux
HOME/.config
Windows
On this platform there are actually two directories for this kind of data:
HOME\AppData\Local, often referred to as %LOCALAPPDATA%
HOME\AppData\Roaming, often referred to as %APPDATA%
The reason for having two is not important in the scope of this page.
Note %APPDATA% is a hidden directory. However if you type %APPDATA% directly in the location bar of your Windows Explorer you will see its contents directly. Similarly you can also directly access %LOCALAPPDATA%.
Macos (formerly OS X)
On this platform there are actually two directories for this kind of data:
HOME/Library/Application Support
HOME/Library/Application Support/config
The former is native to Macos (and will be used by GnuCash), the latter is what GnuCash configures for all its support libraries (like Gtk3).

Like USER_DATA_HOME USER_CONFIG_HOME is common for all applications. Each application will typically expect an application specific subdirectory here.

GNC_CONFIG_HOME

This is the subdirectory in USER_CONFIG_HOME GnuCash uses exclusively for it's user specific configuration data. The default locations:

Linux
USER_CONFIG_HOME/gnucash
Windows
%APPDATA%\GnuCash
Macos (formerly OS X)
HOME/Library/Application Support/GnuCash

To note is that on Windows the base directory is APPDATA and on OS X this is HOME/Library/Application Support. The base directories will be different for the next relevant directory:

GTK_CONFIG_HOME

As gnucash is using Gtk for its graphical user interface, locations that are used by Gtk are also relevant. Note the base directories on Windows and Macos for this one differ from the base directories for GNC_DATA_HOME.

Linux
USER_CONFIG_HOME/gtk-3.0
Windows
%LOCALAPPDATA%\gtk-3.0
Macos (formerly OS X)
HOME/Library/Application Support/GnuCash/gtk-3.0

Files

With the most common base directories defined we can now create a reference list of relevant data and configuration files in each of these directories.

In GNC_DATA_HOME

As written above GnuCash manages these files for you. So usually there's no need to manipulate these by hand. If you do need to make changes be sure to do so while GnuCash is not running.

accelerator-map
A file in which custom accelerator key bindings are stored.
books/<name>.gcm
GnuCash tracks all metadata related to a book in this file. There will be one such file for each book you have ever created/opened. This metadata contains things like window positions, sort orders, which columns to show, CSV import presets,...
checks
a directory to hold custom check formats.
Note for developers: this should probably live in GNC_CONFIG_HOME as this is mostly user configurable data.
expressions-2.0
a file to contain custom expressions managed by the GnuCash expression parser.
Note for developers: This file needs more documentation.
qif-accounts-map
used by the qif importer to keep track of mappings between qif account references and gnucash accounts. This file is formatted in the guile scripting language.
saved-reports-x.y
this file keeps track of all saved report configurations you have created in gnucash. There may be more than one such file with different numbers in x.y. Normally the highest number is the active file while those with lower numbers are kept as a backup (they were the main file for older versions of gnucash). As qif-accounts-map this file is formatted in the guile scripting language.
stylesheets-2.0
this file keeps track of all personalized style sheets for reports. This file is formatted in the guile scripting language as well.

In GTK_CONFIG_HOME

settings.ini
a configuration file in which several aspects of Gtk3 can be configured. Examples are the theme, the default font and size, scrollbar behaviour, ...
The full list of configurable parameters can be found on the Gtk Settings page
gtk.css
a css file for styling Gtk widgets. Any css changes in this file will override overlapping style information in the current theme so this can be used to tweak the theme in more detail.

More information on how these file are used can be found on our GTK3 page. That page has several examples as well.

In GNC_CONFIG_HOME

config-user.scm
this file is the entry point to extend GnuCash by means of the guile scripting language. It's most often used to load additional reports but us not restricted to only that.
gtk-3.0.css
like GTK_CONFIG_HOME's gtk.css this file can be used to manipulate styling for Gtk widgets. Any css changes in this file will override overlapping style info in gtk.css (and hence the current theme as well).
The difference between GTK_CONFIG_HOME's gtk.css and GNC_CONFIG_HOME's gtk-3.0.css is subtle: gtk-3.0.css will only affect GnuCash while gtk.css may also affect other gtk based applications on your system (for example gimp,...)
log.conf
via this file you can manipulate how much information GnuCash will write to a log file. By default this is pretty mild. To help developers in debugging problems the verbosity can be increased.


How to override default locations

The #Directories section above shows default locations used on different operating systems. Sometimes there locations are not convenient. There are several ways to alter them (or your system already alters them for you using one of the below methods).

Environment variable GNC_DATA_HOME

Platforms: All

When a directory is specified via this environment variable GnuCash will unconditionally use that directory as GNC_DATA_HOME, provided this directory exists and is writable or can be created writable. This override will take the highest precedence and works on all operating systems.

Environment variable XDG_DATA_HOME

Platforms: Linux, macos

This environment variable can be used to directly set USER_DATA_HOME. As such it will affect the base directory for GNC_DATA_HOME and GTK_DATA_HOME. On macos this will only affect GTK_DATA_HOME.

Note
The Directories page has some background information on the origin of the XDG_ environment variables.

Environment variable XDG_CONFIG_HOME

Platforms: Linux, macos

This environment variable can be used to directly set USER_CONFIG_HOME. As such it will affect the base directory for GNC_CONFIG_HOME and GTK_CONFIG_HOME. On macos this will only affect GTK_CONFIG_HOME.

There is a caveat here though: on macos GnuCash will set XDG_CONFIG_HOME itself via <bundle>/Resources/etc/gnucash/environment. The only way to override XDG_CONFIG_HOME on this platform is via #File environment.local and this should be repeated each time a GnuCash update is installed.

Note
The Directories page has some background information on the origin of the XDG_ environment variables.

Environment variables LOCALAPPDATA and APPDATA

Platforms: Windows

By setting these environment variables USER_DATA_HOME (and by extension USER_CONFIG_HOME) can be set directly on Windows. Hence depending on which of these two is altered this directly affects GNC_DATA_HOME/GNC_CONFIG_HOME (in case of APPDATA) or GTK_DATA_HOME/GTK_CONFIG_HOME (in case of LOCALAPPDATA).

Note you probably don't want to change these environment variables system wide as that would affect all applications on your system.

File environment.local

Platforms: All

All of the above environment variables can also be set for GnuCash only by creating a file named environment.local next to the file named environment in the gnucash installation. The typical location for this environment file is platform dependent:

Linux
/etc/gnucash/environment or more generally <installprefix>/etc/gnucash/environment
Windows
c:\Program Files(x86)\GnuCash\etc\GnuCash\environment
Macos (formerly OS X)
<GnuCash.app>/Resources/etc/GnuCash/environment

The format of the environment.local file is explained at the top of the environment file.

Note
while on Macos this works there is an issue when updating gnucash. Each time you update your gnucash package environment.local will be removed. So you may want to keep a copy of the file outside of the application bundle that you can put back after each update.