XDG_CONFIG_HOME vs. XDG_DATA_HOME vs. XDG_DATA_DIRS

[Peter]

I find the XDG Base Directory Specification a bit unclear, especially when it comes to how XDG_DATA_HOME should be handled exactly.

I think there are three types of files that games often deal with that are relevant for this discussion:

• Settings (keybindings, sound volume, fullscreen resolution, etc.)
• Important data files that are created by the game (high scores, replays, save files, etc.)
• Static data files that doesn't change after installation (e.g. sound, graphics, scripts, etc.)

Where should the game write files?

Settings should obviously be written to XDG_CONFIG_HOME.

What about other files (e.g. save files)? Should they also be written to XDG_CONFIG_HOME or should they be written to XDG_DATA_HOME? At first it seems like XDG_DATA_HOME would be the correct place to put them but when considering all the confusion below it becomes quite tempting to want to put these files in XDG_CONFIG_HOME. It makes some sense because the XDG specification doesn't specify what it means by "configuration files" and speaking in very general terms one could argue that save files are just complicated configuration files that describe how the game is "configured".


Where should the game search for static data files?

I understand that one would normally search the XDG_DATA_DIRS paths for the installed static data files (sound, graphics, etc.) but the question is whether XDG_DATA_HOME should be searched as well? I kind of get the impression that it should be when reading the XDG specification.

$XDG_DATA_DIRS defines the preference-ordered set of base directories to search for data files in addition to the $XDG_DATA_HOME base directory.

The order of base directories denotes their importance; the first directory listed is the most important. When the same information is defined in multiple places the information defined relative to the more important base directory takes precedent. The base directory defined by $XDG_DATA_HOME is considered more important than any of the base directories defined by $XDG_DATA_DIRS.

On the other hand, it specifically mentions "user-specific data files" but I'm not sure it could be different type of data files or if it simply refers to the same type of data files that can be found in the XDG_DATA_DIRS with only difference being that the user should have write permission.

There is a single base directory relative to which user-specific data files should be written. This directory is defined by the environment variable $XDG_DATA_HOME.

Do the game need to handle static data files and created data files in the same base directory?

If the intention is that the user should be able to install the game files in XDG_DATA_HOME/mygame/ and the game should also write to that directory then I'm a little bit concerned. It means I would need to avoid name clashes (not too difficult because I could use extra subfolders) and the uninstall script would need to be more advanced than just removing all files in the directory to avoid deleting save files and other files that the user might want to keep.

[Huitsi]

The default XDG_DATA_HOME, $HOME/.local/share, looks like /usr/share, and Filesystem Hierarchy Standard defines /usr/share as "for read-only architecture independent data files". So I'd say XDG_DATA_HOME should be for static files only. I'd certainly rather mix configuration and saves than saves and assets, for the same reasons you wrote.

The common practice seems to disagree though, since my ~/.local/share is full of logs, saves and even configs. It is also what SDL_GetPrefPath returns. That wiki page even says that "You should assume the path returned by this function is the only safe place to write files".

[dulsi]

My thought is that settings would be in config and save files would be data. If someone likes your key bindings, sound levels, etc, they can copy the config data so they don't have to set it up themselves. When programming, I find separating them too much effort and just shove everything in data. As for searching for assets in XDG_DATA_HOME, if the game allows modding, I would search that directory. You shouldn't need root to install a mod.

[Peter]

The default XDG_DATA_HOME, $HOME/.local/share, looks like /usr/share, and Filesystem Hierarchy Standard defines /usr/share as "for read-only architecture independent data files". So I'd say XDG_DATA_HOME should be for static files only.

Thank you for sharing the link to the FHS. It's very interesting.

This explains where the word "share" comes from.

"Shareable" files are those that can be stored on one host and used on others. "Unshareable" files are those that are not shareable. For example, the files in user home directories are shareable whereas device lock files are not.

With this definition I would consider all the files that I speak about to be "shareable", at least for my games.

It's also interesting that it mentions directories specifically for games:

Game data stored in /usr/share/games must be purely static data. Any modifiable files, such as score files, game play logs, and so forth, should be placed in /var/games.

On my computer I find supertux2 and supertuxkart files in both /usr/share/games and /usr/games

From the description it sounds like /var/games would be a place where save files could go but it doesn't exist for me and I don't understand how the write permissions would work since I don't seem to have write permission in /var unless I log in as root.

It seems to be /usr that implies read-only so I'm not sure the similarity between /usr/share and ~/.local/share suggests the latter should be used for "static files only". The XDG specification clearly talks about writing into this directory.

I'd certainly rather mix configuration and saves than saves and assets, for the same reasons you wrote.

I do this in an older game of mine. Originally only the game settings were saved. Later when I started to save other things I used the same directory. I don't remember if this was an intentional decision after reading up on the subject or if it was just "an accident".

The common practice seems to disagree though, since my ~/.local/share is full of logs, saves and even configs.

Interesting. I don't have too many games installed at the moment but I notice that supertuxkart saves the progress of the story mode under ~/.config. Admittedly it's a UTF-32 encoded xml file so maybe that makes a difference. It also uses ~/.local/share for some other things (addons, grandprix and replay).

Supertux2 however seems to put everything in ~/.local/share. I see no duplication of folders between /usr/share/games/supertux2 and ~/.local/share/supertux2. I wonder if it would work to put for example the addon folder in /usr/share/games/supertux2 instead but my guess is that it wouldn't work.

It is also what SDL_GetPrefPath returns. That wiki page even says that "You should assume the path returned by this function is the only safe place to write files".

I have seen that function before but never used it because I haven't updated my games for SDL2 yet. I think what SDL tries to do here is to provide an easy cross platform way to give you a place where your program can save its files. Doing this with a single function is probably enough to get something that works but it might not be enough if you want to handle it the recommended way on specific platforms.

[Peter]

My thought is that settings would be in config and save files would be data. If someone likes your key bindings, sound levels, etc, they can copy the config data so they don't have to set it up themselves.

Yeah, but does it become easier because they are separated?

For a single game, maybe if there are a lots of different files, but not if you want to back up both config and data files.

If you want to back up only the config or only the data for all programs at the same time I guess it becomes easier, but isn't config data usually relatively small and it wouldn't hurt if you included the config as well even if you don't need it? At least for games where save files can be pretty large and settings would be small in comparison. Given the current situation where programs do it inconsistently you would probably want to back up both anyway.

When programming, I find separating them too much effort and just shove everything in data.

My concern here is that there are two types of data. Static data that doesn't change, and data that is created by the program. From the XDG specs it's not clear to me if XDG_DATA_HOME perhaps could/should be used for both.

As for searching for assets in XDG_DATA_HOME, if the game allows modding, I would search that directory. You shouldn't need root to install a mod.

Yeah, while answering Huitsi's post above I got the impression that other games store the modding/addons in that directory.

I agree that you shouldn't need to be root to install a mod but should the root be able to install mods for all users by putting them in one of the XDG_DATA_DIRS?

[sago007]

XDG_DATA_HOME is the sane default for save games. If in doubt you want to default to it.

I would only use XDG_CONFIG_HOME if the primary way of changing the files are by hand. For games I would never mix XDG_CONFIG_HOME and XDG_DATA_HOME.

For log files or cache I will use XDG_CACHE_HOME.

I would never install static files to any of the mentioned directories. I would either have a global install or I'll have a everything in one directory for non system wide installs.

I do wish there were an XDG_GAMES_HOME. I feel that game saves are so much different from everything else in XDG_DATA_HOME. Especially mods could benefit from a different games home.

[Peter]

I would never install static files to any of the mentioned directories.

The question is where the user should be allowed to put these files and expect the program to find them, no matter what the default install script does.

I do wish there were an XDG_GAMES_HOME. I feel that game saves are so much different from everything else in XDG_DATA_HOME. Especially mods could benefit from a different games home.

I think it would have been simpler with just a single HOME for all non-static data. Having all these different ones is confusing and is already handled inconsistently by different programs.


But I'm starting to think that maybe this XDG specification is not the be-all and end-all. Instead programs seems to pick bits and pieces that they like. Someone else mentioned FHS, another standard. To me it seems like XDG would need to clarify a few things for it to become more useful and consistently implemented.

[sago007]

The question is where the user should be allowed to put these files and expect the program to find them, no matter what the default install script does.

I do typically read files from in my games but that is mainly for modding purposes.
I use the PhysFS library so it is quite easy to do but I would normally not expect programs to allow it.

I think it would have been simpler with just a single HOME for all non-static data. Having all these different ones is confusing and is already handled inconsistently by different programs.

I do agree that XDG_CONFIG_HOME and XDG_DATA_HOME are hard to justify and the reason why I would always stick with only using XDG_DATA_HOME.
However only having one location means that we are back to the everything a dot file in HOME and I did not like that either.
I do like that programs do support XDG_DATA_HOME as it opens up options for having multiple config instances as the same user at the same time by overwriting it.
I do also like the idea behind the XDG_CACHE_HOME. It might not be a lot of programs that need it but every program that does put its cache files there makes the world a little bit better.


I do not see FHS and XDG as two conflicting standards. FHS only talks about files outside HOME and XDG only about files usually in HOME.
There are also https://wiki.archlinux.org/title/XDG_user_directories that support things like "Documents" and "Pictures" folders. Also something that I would support. But that standard is mainly for non-hidden files and I would not use it for games.