XDG Basedir Library🔗ℹ

William Hatch <william@hatch.uno>

1 XDG Basedir Specification🔗ℹ

This library provides functions for easily accessing configuration and data files according to the XDG Base Directory Specification.

The point of the XDG base directory is to allow programs to put configuration and data files on the filesystem in a consistent and user-configurable way. It solves the problem of having many different configuration and data files and directories (dotfiles) in your home directory.

An important point of the XDG specification is that it specifies a single directory for writable configuration files ($XDG_CONFIG_HOME) and a list of directories ($XDG_CONFIG_DIRS) for non-writable configuration files. If a program can modify its own configuration, it should do so only using the writable directory, and not change the others. Similarly $XDG_DATA_HOME and $XDG_DATA_DIRS exist for the same purpose for data files. There is only one directory for cache files ($XDG_CACHE_HOME), since the whole point of cache files is that they are for the program to write.

Having multiple configuration or data file directories is useful. Consider the common scenario of keeping a synchronized directory of configuration data (with git, dropbox, or the like), as well as local configuration for each machine, and potentially different directories for public and private synchronized configuration. So programs should read all available configuration files and compose the configurations, where possible.

Some words of warning about the runtime dir: The runtime dir should be used for storing ephemeral things like pipes and sockets or other objects restricted to the current run of the program. It is likely created when a user logs in and deleted when the user logs out. It probably lives in a RAM-based file system. The spec says that it may be cleaned of old files occasionally, and to keep your files from being cleaned up you should either update their timestamps regularly (every 6 hours is what they consider regularly) or set the sticky bit on the files. The directory should be readable only by the owner.

To learn more about the XDG basedir specification, visit https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

2 Reference🔗ℹ

This parameter is provided for convenience, so that you can set your program’s XDG path name once and not put it in every call to other basedir functions.

The default value of this parameter is NOT guaranteed to remain stable. A program that wants to have configuration files should be setting its name so the user can see it.

For example, let’s say you write a program named "foo" and your main config file is named "foorc". Bobby (a Debian user) has $XDG_CONFIG_HOME unset (IE at its default value) and $XDG_CONFIG_DIRS set to /home/bobby/config-git:/home/bobby/config-git-private:/home/bobby/local-config and the files /home/bobby/.config/foo/foorc, /home/bobby/config-git/foo/foorc, and /home/bobby/local-config/foo/foorc exist (but not /home/bobby/config-git-private/foo/foorc), then (list-config-files "foorc" #:program "foo") will return a list of paths for those three files that exist on the path. The foo program should, if possible, use the pieces of configuration found in each of the files.

Also note that file-name may actually be a path (eg. subdir/filename), in case you want further nesting in your configuration or data directory.

Since there is only one cache directory and one runtime directory, list-cache-files and list-runtime-files will return either a list with one element or an empty list.

Following the example from above with Bobby and the foo program, while several "foorc" files exist, the only one that should be written to is /home/bobby/.config/foo/foorc. That path would be returned by (writable-config-file "foorc" #:program "foo")

3 Code and License🔗ℹ

The code is available on github.

This library is licensed under the terms of the LGPL version 3, or (at your option) any later version published by the Free Software Foundation (IE LGPL3+).