Complete migration guide to XDG directory layout

[andreasabel]

Lifted from @mouse07410 's comment:

• https://github.com/haskell/cabal/pull/7386#issuecomment-1286189184

@athas, could we please get a complete migration guide to XDG?

We currently have:

• https://github.com/haskell/cabal/blob/master/release-notes/Cabal-3.10.1.0.md#significant-changes
• https://cabal.readthedocs.io/en/3.10/config.html#directories

I would like the table that @mouse07410 requested:

Legacy	XDG
~/.cabal/config	~/.config/cabal/config
~/.cabal/bin	~/.local/bin
~/.cabal/store	~/.local/state/cabal/store (?)
~/.cabal/lib	?
~/.cabal/share	?
~/.cabal/packages	?

Also, the docs talk about variables like XDG_CONFIG_HOME but not what their value would be on different systems. E.g. on macOS, these variables seem undefined:

$ echo $XDG_CONFIG_HOME

$

N.B.: I would also be good to get some advice what to cache in CI. E.g. the whole ~/.local/state/cabal or just ~/.local/state/cabal/store (considering that the previous advice was to cache /.cabal/store).

[athas]

XDG defines defaults when the variables are unset; those defaults are also implicitly listed here: https://cabal.readthedocs.io/en/3.10/config.html#directories

The full information is in the XDG specification itself: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

Based on a quick search on my own machine, the table is

Legacy	XDG
~/.cabal/config	~/.config/cabal/config
~/.cabal/bin	~/.local/bin
~/.cabal/store	~/.local/state/cabal/store
~/.cabal/lib	~/.local/lib (very rarely used)
~/.cabal/share	~/.local/share (very rarely used)
~/.cabal/packages	~/.cache/cabal/packages

I caution against thinking of this as a "migration"; you should not copy any of these things to their new destinations and expect it to work.

Also, another quirk is that all of these are just defaults: these locations are only used if the cabal-install config file does not set its own paths.

[ulysses4ever]

I support extending the docs along the lines charted here. Including the table: even if these are just defaults, it’ll still be helpful in many cases.