Add new blog post
This commit is contained in:
parent
df91e20d7b
commit
61add0fd96
125
articles/Use the XDG Base Directory specification.md
Normal file
125
articles/Use the XDG Base Directory specification.md
Normal file
|
@ -0,0 +1,125 @@
|
||||||
|
# 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!
|
|
@ -0,0 +1 @@
|
||||||
|
2023-07-04
|
140
rss.xml
140
rss.xml
|
@ -3,6 +3,146 @@
|
||||||
<title>speedie's blog</title>
|
<title>speedie's blog</title>
|
||||||
<description>speedie's blog, about stuff I want to talk about.</description>
|
<description>speedie's blog, about stuff I want to talk about.</description>
|
||||||
<atom:link href="https://speedie.site/blog" rel="self" type="application/rss+xml" />
|
<atom:link href="https://speedie.site/blog" rel="self" type="application/rss+xml" />
|
||||||
|
<item>
|
||||||
|
<title>Use the XDG Base Directory specification</title>
|
||||||
|
<link>/blog.php/Use+the+XDG+Base+Directory+specification</link>
|
||||||
|
<guid>/blog.php/Use+the+XDG+Base+Directory+specification</guid>
|
||||||
|
<pubDate>Tue, 04 Jul 2023 00:00:00 +0000</pubDate>
|
||||||
|
<description>
|
||||||
|
<![CDATA[
|
||||||
|
<h1>Use the XDG Base Directory specification</h1>
|
||||||
|
|
||||||
|
<p>2023-07-04</p>
|
||||||
|
|
||||||
|
<p>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.</p>
|
||||||
|
|
||||||
|
<h2>What is XDG Base Directory?</h2>
|
||||||
|
|
||||||
|
<p><a href="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory</a>
|
||||||
|
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.</p>
|
||||||
|
|
||||||
|
<p>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.</p>
|
||||||
|
|
||||||
|
<p>The XDG Base Directory standard came around to solve this very real problem,
|
||||||
|
by creating a <em>few</em> directories in the home directory, that programs can
|
||||||
|
use for storing data, hence the name.</p>
|
||||||
|
|
||||||
|
<p>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:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>$XDG_CONFIG_HOME</li>
|
||||||
|
<li>$XDG_CACHE_HOME</li>
|
||||||
|
<li>$XDG_DATA_HOME</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>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?</p>
|
||||||
|
|
||||||
|
<p>$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.</p>
|
||||||
|
|
||||||
|
<h2>A common misconception</h2>
|
||||||
|
|
||||||
|
<p>No, by placing config files into ~/.config or cache files in ~/.cache,
|
||||||
|
you are <strong>NOT</strong> 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.</p>
|
||||||
|
|
||||||
|
<p>In shell script for instance, you would do something along the lines of
|
||||||
|
<code>mkdir -p ${XDG_CONFIG_HOME:-$HOME/.config}/my-software</code>. In C you would use
|
||||||
|
<code>getenv("XDG_CONFIG_HOME");</code>. But in any case, it isn't hard.</p>
|
||||||
|
|
||||||
|
<h2>Why follow the specification?</h2>
|
||||||
|
|
||||||
|
<p>If you're an end user, this is most likely already obvious to you. If you were
|
||||||
|
to run simply <code>ls</code> 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 <code>ls -a ~/</code>
|
||||||
|
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.</p>
|
||||||
|
|
||||||
|
<p>By following the specification, you're allowing your users a lot more choice over
|
||||||
|
<em>their</em> home directory. At the end of the day, it's <em>their</em> home directory,
|
||||||
|
not the program's home directory.</p>
|
||||||
|
|
||||||
|
<p>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.</p>
|
||||||
|
|
||||||
|
<p>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.</p>
|
||||||
|
|
||||||
|
<h2>Following the specification is easy</h2>
|
||||||
|
|
||||||
|
<p>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:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>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}.</li>
|
||||||
|
<li>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.</li>
|
||||||
|
<li>Create a directory inside whenever it makes sense to do so.</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<p>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.</p>
|
||||||
|
|
||||||
|
<h2>The only exception</h2>
|
||||||
|
|
||||||
|
<p>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 <strong>require</strong> 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 <code>.mozilla</code> 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.</p>
|
||||||
|
|
||||||
|
<p>If your shiny new project doesn't support the XDG <em>standard</em>, especially if
|
||||||
|
almost no people depend on it or its configuration file/cache file location,
|
||||||
|
you have no excuse.</p>
|
||||||
|
|
||||||
|
<h2>EOF</h2>
|
||||||
|
|
||||||
|
<p>Some programs don't quite fully support the specification. The Arch wiki
|
||||||
|
has an excellent <a href="https://wiki.archlinux.org/title/XDG_Base_Directory#Supported">article</a>
|
||||||
|
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.</p>
|
||||||
|
|
||||||
|
<p>It's the XDG Base Directory <em>standard</em>. If you are a software developer,
|
||||||
|
follow the <em>standard</em>. That's it for today, have a good day!</p>
|
||||||
|
|
||||||
|
]]>
|
||||||
|
</description>
|
||||||
|
</item>
|
||||||
<item>
|
<item>
|
||||||
<title>File pickers suck</title>
|
<title>File pickers suck</title>
|
||||||
<link>/blog.php/File+pickers+suck</link>
|
<link>/blog.php/File+pickers+suck</link>
|
||||||
|
|
Reference in a new issue