Unix has traditionally lacked a consistent way of storing user specific and system wide configuration and support files. This has lead to a mess of dot files in a user’s home directory and other associated files being all over the file system. The XDG Base Directory Specification describes a simple and clean way to locate these files across all Unix-like systems. The xdgbasedir module allows you to easily access this specification from Tcl.

Why Use the XDG Base Directory Specification?

By storing an applications files using this spec. it makes it much easier for the user to find the files associated with your application so that they can edit and back them up. For the application, it makes it much easier to work with files in a consistent manner on whichever Unix platform it is running.

Ultimately the spec. allows you to turn this:

.                     Downloads           .lives            .scummvm
..                    .fontconfig         .lives-dir        .scummvmrc
.android              .FontForge          livestmp          .sitecopy
.aptitude             .gcjwebplugin       .local            .sitecopyrc
archive               .gconf              .lyrics           .slrnrc
.avm                  .gconfd             .mbox             .ssh
.balazar              .gegl-0.0           .mcoprc           .synaptic
.bash_history         .gem                .mess             .tdfsb
.bash_logout          .gitconfig          .metacity         Templates
.bash_profile         .gitk               Music             .themes
.bashrc               .gnash              .nexuiz           .thumbnails
.bochsrc              .gnome              .openMSX          .tremulous
.bogofilter           .gnome2             .openoffice.org   .tsclient
.bundler              gpodder-downloads   .orbit            .tvtime
.cache                .gramps             .pan2             Video
.Catapult             .gtkrc-1.2-gnome2   .pcmanx           .vim
.cgobanrc             .gtwitter           Pictures          .viminfo
.civserver_history    .gvfs               .pingus           .vimrc
.config               .gvimrc             Podcasts          .vlc
.conky                .hplip              Public            .w3m
.conkyrc              .ICEauthority       .purple           .wapi
.corewars             .icons              .q3a              .wmii
data                  .inkscape           .qt               .wmii-3.5
.dbus                 .irb-history        retro_archive     .Xauthority
Desktop               .jigdo-lite         retro             .xawtv
dev                   .libreoffice        rtb               .xchat2
.dmenu_cache          .liferea            .rvm
.dmrc                 .lincity            .sane
Documents             .liquidwarrc        .scorched3d

Into this:

.         .config   Documents           Music      retro
..        data      Downloads           Pictures   retro_archive
archive   Desktop   gpodder-downloads   Public     Templates
.cache    dev       .local              Podcasts   Videos

How Should I Locate Files Using the Specification?

A brief explanation of the spec. follows, for more look at the XDG Base Directory Specification recommended by freedesktop.org.

The specification uses six environmental variables to locate files. These are:

$XDG_DATA_HOMEFor user-specific data files.
$XDG_CONFIG_HOMEFor user-specific configuration files.
$XDG_CACHE_HOMEFor user-specific non-essential data.
$XDG_RUNTIME_DIRFor user-specific runtime files.
$XDG_DATA_DIRSA list of directories, in order of preference, which should be searched for data files.
$XDG_CONFIG_DIRSA list of directories, in order of preference, which should be searched for configuration files.


For each directory or for each directory in the list of directories (in the case of the environmental variables ending with _DIRS), you would normally append the name of your application. So for example if the $XDG_DATA_HOME variable returned ~/.local/share, and your application was called myapp, you should look in ~/.local/share/myapp/ for that application’s user-specific data files.

The xdgbasedir module for Tcl

To ease working with the XDG Base Directory Specification from Tcl, I created the xdgbasedir module.

To access the XDG directories you would typically specify the subdirectory that these directories will be relative to. The subdirectory is normally the name of the application, myapp in this example:

package require xdgbasedir

puts "XDG_DATA_HOME: [XDG::DATA_HOME myapp]"
puts "XDG_CACHE_HOME: [XDG::CACHE_HOME myapp]"
puts "XDG_CONFIG_HOME: [XDG::CONFIG_HOME myapp]"

puts "XDG_RUNTIME_DIR: [XDG::RUNTIME_DIR myapp]"
puts "XDG_DATA_DIRS: [XDG::DATA_DIRS myapp]"
puts "XDG_CONFIG_DIRS: [XDG::CONFIG_DIRS myapp]"

The XDG procs ending in _DIRS return a list of directories in order of preference.

Getting xdgbasedir

You can download xdgbasedir from the archive page on github, and read the installation instructions in the README.md file.