speedie-page/articles/Use the XDG Base Directory specification.md

# Use the XDG Base Directory specification

2023-07-04

Alright, so as you guys know I have been very critical of Freedesktop in the past.
Some of that I think is justified, some maybe less so. Today I'm going to talk
about the complete opposite though. The XDG Base Directory specification, or
what is in my opinion one of the best things Freedesktop have come up with.

## What is XDG Base Directory?

[XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
is a specification by Freedesktop, but I would go as far as to call it a standard,
because frankly if you're a developer who isn't following it, most end users
hate you, myself included. I won't have you read the entire specification, so I
will summarize the specification.

In the past, programs would just write configuration files, cache files, and
other data wherever the hell the programmer decided that they should go. Perhaps
this is practical to the programmer, but what ends up happening is users find
that they have possibly hundreds of hidden files that they did not create.

The XDG Base Directory standard came around to solve this very real problem,
by creating a *few* directories in the home directory, that programs can
use for storing data, hence the name.

But what people tend to forget is that it doesn't necessarily have to be your
home directory. You could put these directories anywhere your user has read
and write permission, or hell, even /dev/null if you want to break stuff.
This is why this specification rocks. But what are the directories
and variables? There are many of them, but the most common are:

- $XDG_CONFIG_HOME
- $XDG_CACHE_HOME
- $XDG_DATA_HOME

All of them are unset by default, but when developing a program you should
still read and use them. $XDG_CONFIG_HOME is where user configuration
files should be read from and written to. On most systems, it is set
to ~/.config by default. Does that sound familiar?

$XDG_CACHE_HOME is where cache files should be stored. On most
systems, it is set to ~/.cache by default. $XDG_DATA_HOME is for
program data, and is set to ~/.local/share by default on most systems.
All of these will probably sound familiar to you if you have been using
GNU/Linux or even BSD operating systems for a decent amount of time.

## A common misconception

No, by placing config files into ~/.config or cache files in ~/.cache,
you are **NOT** supporting the XDG Base Directory specification. I see this
very often in shell scripts especially, and I've been guilty of it as well but
to properly support the specification, you need to check the variable. If the variable
is unset, you should (but technically don't have to) use the default path.

In shell script for instance, you would do something along the lines of
`mkdir -p ${XDG_CONFIG_HOME:-$HOME/.config}/my-software`. In C you would use
`getenv("XDG_CONFIG_HOME");`. But in any case, it isn't hard.

## Why follow the specification?

If you're an end user, this is most likely already obvious to you. If you were
to run simply `ls` on your home directory, you probably wouldn't think it's that
bad. But that's because the ls command doesn't show dotfiles. Run `ls -a ~/`
instead. Look at the absolutely insane amount of dotfiles. In fact, you likely
have more configuration files than normal files you actually care about. Your
home directory has turned into a dumpster for programs to throw their config
files and cache into.

By following the specification, you're allowing your users a lot more choice over
*their* home directory. At the end of the day, it's *their* home directory,
not the program's home directory.

If you do not follow this specification, you are actively causing your users
pain and suffering from having a cluttered home directory. You go out of your
way to treat your user's home folder like a dumpster. I am a minimalist, and
I don't use that many programs. I have 28 hidden files and directories in my
$HOME folder. Now imagine how many dotfiles your average GNOME or KDE user
would have on his or her computer.

Please, for the love of god, if you're a developer, follow the XDG Base
Directory specification. It really should be the XDG Base Directory
specification, and the only people who are preventing this from happening are stubborn
developers like you.

## Following the specification is easy

Following the specification is incredibly easy, and even if you're new to software
development (like me), you can easily follow the specification. All you have to do
to support the specification is the following:

1. Check if the XDG variable is set. Depending on the type of file you're trying
to store it will be different. For cache files, this is ${XDG_CACHE_HOME}, for
config files this is ${XDG_CONFIG_HOME}, for general data this is ${XDG_DATA_HOME}.
2. If it isn't set, use the default for that variable. For ${XDG_CACHE_HOME},
it would be ~/.cache, for ${XDG_CONFIG_HOME} it is ~/.config and for ${XDG_DATA_HOME}
it is ~/.local/share.
3. Create a directory inside whenever it makes sense to do so.

That's it. That's all you have to do. You're now one step closer to being a developer
writing quality software, rather than a developer that makes your users consider
throwing away their computers. It's not hard.

## The only exception

The only exception where I think it is acceptable to not follow this standard,
is when thousands of people heavily depend on a program, who **require** that the
config file or cache path never change. There are a few such cases, Firefox being
one notable example. I ultimately dislike having the `.mozilla` directory in my
home directory, but the location changing could cause significant issues for a
lot of people, who would have to adjust to it.

If your shiny new project doesn't support the XDG *standard*, especially if
almost no people depend on it or its configuration file/cache file location,
you have no excuse.

## EOF

Some programs don't quite fully support the specification. The Arch wiki
has an excellent [article](https://wiki.archlinux.org/title/XDG_Base_Directory#Supported)
dedicated to software that can use the XDG standard, both programs that support
it natively and programs that need a environment variable to be exported.

It's the XDG Base Directory *standard*. If you are a software developer,
follow the *standard*. That's it for today, have a good day!