Properly support XDG Base Directory Specification

[hvr]

directory provides a function getAppUserDataDirectory :: String -> IO FilePath which on Linux simply constructs the resulting path as ${HOME}/.${APPNAME}.

However, that doesn't conform to the XDG Base Directory Specification

Further reading:

• http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
• https://wiki.debian.org/XDGBaseDirectorySpecification
• https://wiki.gnome.org/Initiatives/GnomeGoals/XDGConfigFolders

[hvr]

@simonmar commented some time ago:

To do this properly, we should really add getAppConfigDirectory, getAppCacheDirectory etc.

[nomeata]

Clearly, we cannot simply chnage getAppUserDataDirectory, as that would breakt lots of apps. But deprecating it (without a plan to remove it) in favour of additional functions would work.

Or providing a function that returns ${HOME}/.${APPNAME} when available and uses the proper locations otherwise.

[hvr]

@nomeata I'm afraid deprecating getAppUserDataDirectory in order to add a new function won't work here, as directory is supposed to be a platform-abstracted package, and getAppUserDataDirectory is already supposed to get you the special folder according the OS-specific conventions (which on Windows is accomplished by using the SHGetFolderPath function)

If we have to deprecate the current getAppUserDataDirectory function incarnation each time we discover the need to update the scheme to conform to some new OS-specific convention, we'll end up with several such functions.

Isn't there a way to modify getAppUserDataDirectory in such a way that it's backward compatible (like you seem to suggest by returning the old-style ${HOME}/.${APPNAME} location if it exists, and only otherwise attempt to be XDG-compliant?)

How did other Linux software manage the migration from pre-XDG to XDG-style per-user application data directories?

[nomeata]

Isn't there a way to modify getAppUserDataDirectory in such a way that it's backward compatible (like you seem to suggest by returning the old-style ${HOME}/.${APPNAME} location if it exists, and only otherwise attempt to be XDG-compliant?)

That would be possible as well, and might be good enough. I think its also what other programs do, unless they actually move one directory to the other (which programs using this function could do as well, of course)

[JLimperg]

I believe any change to getAppUserDataDirectory would be backwards-incompatible in a strict sense because the documentation specifies that its result must be $HOME/.appName on Unix(-likes). So, is it considered acceptable to break code that relies on this property?

[kmarekspartz]

Does XDG apply for many/most of the programs using this? Isn't XDG primarily for GUI apps?

[pjones]

@zeckalpha while the XDG directory specification was pioneered in the GUI world, many daemons and command-line tools use it too. It's especially useful for managing application data vs. configuration.

@hvr How do you feel about a new function getAppUserConfigFile? That function plus getAppUserDataDirectory would probably be enough for most applications to fully support XDG.

I'm traveling the next few days which means I'll have some free time in the evenings to work on this if you need help. I like the idea of getAppUserDataDirectory returning ${HOME}/.${APPNAME} if it exists, and the XDG data directory otherwise. That should be pretty easy to code up and mostly backwards compatibly. It will, of course, break the documentation for tools that expect ${HOME}/.${APPNAME}.

[hvr]

@pjones getAppUserConfigFile sounds useful, but what would it return on Windows and/or on other non-XDG platforms? (Maybe the same value as getAppUserDataDirectory?)

[pjones]

@hvr In that case I think it should be:

dir <- getAppUserDataDirectory appName
return (dir </> appName)

for consistency. An alternative to using the appName twice would be "config" instead.

[odi]

What is if I have two different environments for one application. On has set the XDG Base Directory an one hast not. Maybe the application would conduct different in this case and the solution will be better to split these functions in XDG based functions and not XDG based functions and the user of this library should decide for he's own if he uses the XDG based functions or not.

The other way is to make this decision in the library itself e.g.

getAppUserDataDirectory appname = do
  dir <- lookupEnv "XDG_DATA_HOME"
  case dir of
   Nothing -> do
     home <- getEnv "HOME"
     return $ home ++ '/' : '.' : appname
   Just path -> return $ path ++ '/' : appname

IMHO this should be the base decision of this discussion.

[hvr]

I just became aware of the related Xmonad Issue 484: Use XDG Base Directory Specification (which links also back here)

[Rufflewind]

If we have to deprecate the current getAppUserDataDirectory function incarnation each time we discover the need to update the scheme to conform to some new OS-specific convention, we'll end up with several such functions.

I don't think new OS conventions would appear so rapidly as to be a problem. I also don't think there's a way to implement this in a backward-compatible manner: changing the location will cause surprises for both developers and end-users downstream.

If we do add a new function, getAppUserDataDirectory should not be deprecated, since some may prefer the traditional behavior. From my experience, quite a few programs (probably the majority) still use the traditional location.

We could add the following functions:

• getXdgUserDataDirectory: XDG_DATA_HOME (~/.local/share); Windows: AppData/Roaming?
• getXdgUserConfigDirectory: XDG_CONFIG_HOME (~/.config); Windows: AppData/Roaming
• getXdgUserCacheDirectory: XDG_CACHE_HOME (~/.cache); Windows: AppData/Local
• getXdgUserRuntimeDirectory: XDG_RUNTIME_DIR (/tmp/<user>/<app>?); Windows: AppData/Local/Temp?

and perhaps some utility functions for obtaining various search paths:

• getExecutableDirectories: PATH (not relevant to this issue though)
• getXdgDataDirectories: XDG_DATA_DIRS (/usr/local/share/:/usr/share); Windows: none?
• getXdgConfigDirectories: XDG_CONFIG_DIRS (/etc/xdg); Windows: none?

However, I don't know if we should add all of them right away since not all of them are necessarily in demand. (Do people even use XDG_RUNTIME_DIR? Using /etc/xdg seems very unnecessary, IMO.)

[Rufflewind]

Fixed in ab9d081

(I did not implement the utility functions nor XDG_RUNTIME_DIR however. Nonetheless, if anyone else has a need for them feel free to open another ticket.)

[hvr]

@Rufflewind I'm wondering, with the given operation, what's the recommended upgrade path for code currently using getAppUserDataDirectory? If we have a recommendation, which may want to document it in the Haddocks...

[Rufflewind]

Note: I don't intend to deprecate getAppUserDataDirectory, so applications are not required to migrate to getXdgDirectory unless they really want to.

Unfortunately, migrating is not as simple as tweaking the code:

1. Using the new location will obviously break any existing setup, thus a user-friendly application should seamlessly migrate the files to the new location. (And update any old documentation, tutorials, etc, to reflect this.)

2. One must consider where the files are to be migrated. Depending on how strict the application wants to conform to the XDG specs, it will have to decide between

   • ~/.local/share (equivalent to /usr/share but user-specific),
   • ~/.config (equivalent to /etc but user-specific),
   • ~/.cache (equivalent to /var/cache but user-specific),

   or some subset of the three. If the developer doesn't care about these pesky details, ~/.config seems like a safe bet, I think.

3. Updating the code to use the XDG directories is pretty straightforward. Just replace

   getAppUserDataDirectory "myapp"
   

   with

   getXdgDirectory XdgConfig "myapp"
   

   Substitute XdgConfig with XdgData or XdgCache as needed.

Ultimately, the hardest part is performing the migration correctly :\

Edit: this comment has been updated to use the new two-parameter API instead of the previous one-parameter API, as suggested by hvr's comment below

[hvr]

I think any guidance we can give via the documentation helps users (to avoid having everyone having to figure it out for themselves individually, as well as reducing the risk of mistakes)

bikeshed-warning Looking at your last example, I wonder if there are any cases where you want the base-folder returned by

getXdgDirectory :: XdgDirectory -> IO FilePath

rather than having the slightly more convenient form

getXdgDirectory :: XdgDirectory -> FilePath -> IO FilePath

which would encode the policy that you're expected to refer to an app-specific subfolder in the respective Xdg-base-folder... (and if you deliberately pass the empty string or ".", you'd still get the base-folder)

[Rufflewind]

I agree the latter is more convenient. I picked the former because it felt simpler and didn't make any assumptions as to what the user intended to do with it.

However, I think passing an empty string to get the base directory is reasonable as long as it's documented behavior. For getAppUserDataDirectory it's currently unspecified, but that can be fixed. (On second thought: I'm not sure if there's a reason to fix that.)