GNOME Goal: XDG Base Directory Specification Usage

Problem

Unix like systems have traditionally lacked a standard way to store application or user data on a per-user basis. Consequently these data are often stored in an ad-hoc, inconsistent, and problematic way in "dot files" of the user's home directory.

This is a problem because:

• It breaks when sharing a home directory between different machines, or sessions (eg. using NFS)
• Not cleanly separating cache, runtime (eg. sockets), or app data from user settings make it very difficult to manage
• It makes it extremely challenging to perform smart or selective migration of settings between different OS versions
• It is hard to reset settings without breaking things
• It is hard to determine how to clear cache data to make room when the disk is filling up
• It is hard to write a robust and efficient backup solution
• It doesn't allow an admin flexibility to change where data and settings are stored
• It dramatically increases the complexity and incoherence of the system for administrators
• Aggregated across the entire OS it is an embarrassing mess

See one example user's story in this post.

Guidelines

FreeDesktop has issued a recommended solution for this problem.

• Separation of user data, preferences, and cache items
• Backwards compatibility should be taken into account

• If you remove the .cache folder, the user MUST not notice it except maybe for performance (might be huge performance drop)

• If you remove the .config folder, the user will see all the preferences reset to the default but without any data loss.
• .local should be treated as any other user data
• If you are storing application logs, you may want to consider using syslog or the systemd journal instead

Read this more detailled explanation of the XDG specification.

Bonus point: if the user chooses a default preference, this preference should not be saved anywhere and the corresponding entry in the config file should be empty (or "default" or whatever). This way, we are sure that an user does not keep the 10 years old default without even noticing it and that his default setup is correctly upgraded.

The application is a target for this goal if:

• the application stores file in an hidden folder others than the XDG ones
• OR if removing the .cache or the .config folders induces data loss for the user
• OR removing the .config folder doesn't get the application in its default configuration

Examples

GLib

const char *cache_dir = g_get_user_cache_dir ();
char *mydir = g_build_filename (cache_dir, "myapp", NULL);
/* use it */
g_free (mydir);

Python

import os
from gi.repository import GLib
mydir = os.path.join(GLib.get_user_config_dir(), 'myapp')

or

_runtime_dir = os.environ.get('XDG_RUNTIME_DIR', os.environ.get('XDG_CACHE_HOME', os.path.join(os.path.expanduser("~"), '.cache')))
_config_dir = os.environ.get('XDG_CONFIG_HOME', os.path.join(os.path.expanduser("~"), '.config'))
_cache_dir = os.environ.get('XDG_CACHE_HOME', os.path.join(os.path.expanduser("~"), '.cache'))
_data_dir = os.environ.get('XDG_DATA_HOME', os.path.join(os.path.expanduser("~"), '.local/share'))

Vala

Environment.get_user_cache_dir()

Migration

A good example are the empathy patches by fpeters:

• Migrate configuration files to XDG config directory

• Put configuration data in XDG_CONFIG_DIRS

GLib convenience functions: here

Status of this goal

Above are the states and corresponding markup to update the modules state table below.

See Also

• Ubuntu Brainstorm