126 lines
6.2 KiB
Markdown
126 lines
6.2 KiB
Markdown
# 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!
|