XDG Home Directories

[timangus]

As discussed in #702. Essentially what this does is to split fs_homepath into fs_homeconfigpath, fs_homedatapath and fs_homestatepath (though you can still set fs_homepath to override them all at once, if you want). The file write functions are split into similar variants, ending in _HomeConfig, _HomeData and _HomeState that are called as appropriate. Game code writes to the data path; we can't allow games to write to different locations without changing the API, which we obviously can't do.

Where things go

Location	Type
Config	.cfg
Data	.pk3, .avi, .jpg, .tga, ._dm*, .txt (console dumps), .log (various types), and game code files
State	q3history, q3key, qkey, .dat (various things), .pid

Arguably logs should really live in the state location, but since game writes to the data location, and game writes logs, I decided it's less confusing to have all the logs going to the same place.

Upgrade path

If ~/.q3a exists, a prompt is shown to the user asking if they want to migrate to the new setup. If they say no, ~/.q3a/.xdgMigrationRefused is written, which is then checked for on subsequent runs to gate whether the prompt is shown. If they say yes, a shell script is written to the temp directory with the relevant locations substituted in, and when executed, the user's files are copied from the old location to the new locations. I did consider doing this in C, by calling the functions that write each file type with the new locations, but they're spread out quite a lot and managing the state would require so much pissing about that I quickly decided it wasn't worth it, and settled on the much simpler shell script approach.

Gnome

KDE

If the new locations exist, then they're used no matter what. As per existing functionality, Flatpaks ignore ~/.q3a and always use XDG, though regrettably the layout is different to what they have been using up until now, which isn't ideal, but I'm not sure there's much that can be done about that besides having a special Flatpak XDG mode and that doesn't sound like a great idea. I guess the migration script could be used in that situation, but I slightly question the effort/value if there are only a small number of people using the Flatpak (do we have any data on that?).

[Calinou]

Looks good to me, but I wonder if we should go with Quake3 as a folder name for two reasons:

• It has an uppercase character, and uppercase is traditionally discouraged in XDG folder names (even if it's technically allowed).
• It's generic for the game, and not specific to the ioquake3 source port. If Quake3e wants to go the same route and adopt the same folder, it will cause conflicts again like ~/.q3a did.
  • In comparison, Doom/Quake 1/Quake 2 source ports almost all use configuration folders specific to the source port. Many can run in portable mode too, but having multiple source ports installed to the same folder is discouraged in that case.

I'd suggest going with ioquake3 instead, or quake3 at the very least.

Now that we are changing the default path, there's no longer the argument that keeping the legacy path allows a seamless transition from vanilla Q3A to ioquake3 (without the migration helper, that is).

[NuclearMonster]

agreed, it should be ioquake3 instead of Quake3

also can we please get rid of the side icon in the dialog box and make it slightly more like my mockup in terms of font sizes/styles so that it's more readable:

[timangus]

I went with Quake3 for two reasons:

1. In the analogous situation on Windows and macOS, we use exactly that. It was weird to use something slightly different (~/.q3a) for that reason alone, but it would also be very weird to brand the directories on Linux only. It should be branded everywhere or nowhere, and this should not depend on what platform you're using.
2. Actually, to my mind having a generic name is a feature, not a bug. If we brand it then other versions of Q3 wanting to use XDG are basically forced into using their own branding, and it seems silly for them to have to use their own dedicated set of directories when we're all sharing the same data and settings, for the most part. If you use multiple versions of Q3 it would be quite annoying to have to install a mod twice (or more) for each. I think it's fair to say that ioq3 is the defacto Q3 community effort so in a sense we set the precedent here, and it makes sense (to me at least) for said precedent to be generic rather than specific. If we keep it generic, then other versions at least have the choice whether they want to use the generic name, but as I say if we brand, we're effectively forcing everyone to brand, and that's kind of dick move, if you ask me.

Capitalisation wise, a quick look at my ~/.config seems to suggest that no one particularly gives a shit, but we can go with quake3 or q3a I guess, point 1 above notwithstanding.

[timangus]

also can we please get rid of the side icon in the dialog box and make it slightly more like my mockup in terms of font sizes/styles so that it's more readable:

No, it's just zentity/kdialog, not an actually hand made dialog box, i.e. there is no way to control the fonts or anything like that, it's just plain text. The image I posted in Discord was the real thing, not a mockup.

[smallmodel]

I agree that the folder name (for all platforms) should be named either ioq3 or ioquake3, to match the product name.

[timangus]

I agree that the folder name (for all platforms) should be named either ioq3 or ioquake3, to match the product name.

The thing is, we can't realistically rename the Windows and Mac directories at this point, so we might as well use what we're already using.

[zturtleman]

As per existing functionality, Flatpaks ignore ~/.q3a and always use XDG, though regrettably the layout is different to what they have been using up until now, which isn't ideal, but I'm not sure there's much that can be done about that besides having a special Flatpak XDG mode and that doesn't sound like a great idea. I guess the migration script could be used in that situation, but I slightly question the effort/value if there are only a small number of people using the Flatpak (do we have any data on that?).

FlatHub says the ioquake3 flatpak has been installed 21,739 times.

There is already a launch script in the flatpak that migrates the home path (it previously used "+set fs_homepath $XDG_DATA_HOME" without a subdirectory, i.e. "q3a"). The flatpak launch script could potentially be extended for changing the home path for this PR.

[timangus]

it will cause conflicts again like ~/.q3a did.

Can you be specific about what you mean here?

[timangus]

I'm keen to move forward with this. There was some minor push back towards splitting the layout into several directories, as per the standard, but the consensus seems to be that this is the way to go or at least there haven't been any convincing and/or compelling arguments against this, so I consider this aspect resolved.

The more contentious issue seems to be the name of the directory, where it's my position that the precedent that we've set on non-Linux platforms (and indeed indirectly in derivative projects such as Quake3e) should be applied, i.e. the top level directory name should be "Quake3". I don't necessarily hate the idea of using "ioquake3"/"ioq3" in itself for this, but what I do hate is that if we go down that route then this makes Linux "special" and inconsistent in that it would use different naming to the other platforms. So if the consensus is that we use the branded name, then to avoid the glaring inconsistency we would need to also change the Windows and macOS directories to match. In this case we would need to implement upgrade paths for these platforms. We can't simply rename the directories since, as I say, other derivative projects have adopted the "Quake3" naming, so we would in effect be deleting the settings of said projects and we obviously can't do that. Instead we would need to copy existing files to a new directory. This is clearly a lot of extra work and would be disruptive for users, derivatives and create new support queries, so I'm not really convinced this is worthwhile.

I haven't really heard any arguments for a branded name other than "that's what other projects do", but I'm open to any further comment here. For what it's worth, I wouldn't really have a problem with the branded name if we were starting afresh, but the fact remains that we already settled on the generic name 15+ years ago and I'm loath to go changing it now.

[NuclearMonster]

For a variety of reasons it'd be preferable to choose ioquake3 or ioq3 for the directory name versus Quake3 or Quake 3. As much as possible I believe it's better going forward to avoid using the Quake 3 name within our project while of course retaining compatibility with baseq3, missionpack, and mods.

ioq3 would be the furthest from Quake 3 while still retaining some recognition with the project name.

This directory rename is unfortunate for cross-fork compatibility. There isn't any way around that.

This naming scheme would be a temporary inconsistency across the platforms.

[timangus]

So, @NuclearMonster and I had a brief conversation about this elsewhere and I think we've reached an understanding that if we arrive a place where we need/want to do a rename of the product then that should be a separate change to the scope of this PR.

This is to say that this is a last call for comments/objections/suggestions before I commit it in its current form.

[smcv]

Debian currently uses a somewhat patched ioquake3 as our engine for both Quake III Arena and OpenArena (we don't use OpenArena's engine fork, to reduce the number of places that need changing if there's a CVE) and I suspect we're not the only distro that does this.

Currently we +set com_homepath .openarena (among many other command-line arguments) when running as OpenArena. Am I correct to think that with this change, we could still +set fs_homepath $HOME/.openarena to keep the old behaviour, or +set com_homepath OpenArena to get ~/.local/share/OpenArena (etc.) alongside ~/.local/share/Quake3 (etc.)?

[timangus]

That's correct, yeah, although I would appreciate it if you could test that; it's not something I've played with that much. The only part that's missing with using the engine this way is that the migration mechanism won't be employed as that would need a new cvar like com_legacyhomepath to be referenced, and that entails a level of complexity I'm not sure I really want to get into for such a relatively niche use case. I guess you could potentially incorporate the migration script into the start up script for OpenArena if you thought it worthwhile though...

Thanks for bringing this up though, as it's highlighted a flaw that I hadn't thought of, that being that using ioq3 in this way will likely result in it trying to migrate from ~/.q3a (if it exists) to ~/.local/share/OpenArena (or whatever) as the former is hard coded as per q_shared.h. Fixed this now.

[smcv]

I guess you could potentially incorporate the migration script into the start up script for OpenArena if you thought it worthwhile though...

Any time a distro does this, they're going to need a startup script anyway to set lots of cvars suitable for the other game (assuming they've compiled the engine to default to trying to be Quake III Arena, which is what we've done in Debian), so adding more logic to that startup script isn't particularly onerous. As long as there's a way we can force the migration not to be done by the engine itself!

[timangus]

As long as there's a way we can force the migration not to be done by the engine itself!

Yup, following the latest changes it won't attempt any migration if either fs_homepath or com_homepath are set.