# Platform Directories (XDG)

Issues:
- XDG: https://github.com/rust-lang/cargo/issues/1734
- Windows: https://github.com/rust-lang/cargo/issues/1976
- rustup: https://github.com/rust-lang/rustup/issues/247

Benefits
- ["Wow! I once wondered about whether that special case existed---the docs at http://doc.crates.io/config.html#hierarchical-structure are extremely unclear as to that point. I think using a different naming scheme for the home directory would make the special casing a lot more intuitive---@tbu- IMO this de-obfuscation is worth adding to the RFC as extra motivation."](https://github.com/rust-lang/rfcs/pull/1615#issuecomment-233432901)

Questions / concerns
- https://github.com/rust-lang/cargo/pull/5183#issuecomment-381449546
- Must address rustup
- https://github.com/rust-lang/rfcs/pull/1615#issuecomment-262344486
- What should be done for macOS?
- https://github.com/rust-lang/cargo/pull/2127#issuecomment-155963971
- ["People could use the XDG environment variables to stick their mac config in the Library directory (or where it normally goes, I don't have a mac). Then we both have a single Unix policy and everything is in its proper place. Win, win!"](https://github.com/rust-lang/rfcs/pull/1615#issuecomment-232763775)
- What should be done for misc OS (Redox being a strawman)?
- I'm worried about the fragmentation this causes across platforms. It's no longer easy given an arbitrary system to find out where Cargo has placed its cache directory or where you should place configuration.
- https://github.com/rust-lang/cargo/pull/2127#issuecomment-155963971
- (as of 2015) It looks like we'd be one of the first package managers to do something like this. None of bundler, npm, pypi, or rubygems seem to do anything related to this. Our target audience isn't always experienced linux folks who expect this behavior but often newbies who may not know where to probe to find Cargo-related files.
- https://github.com/rust-lang/cargo/pull/2127#issuecomment-155963971
- XDG status: https://wiki.archlinux.org/title/XDG_Base_Directory#Support
- anaconda
- pip
- cabal
- luarocks
- elixer (requires explicitly setting XDG variables)
- ghc
- ccache
- clangd
- git
- mercurial

Proposals
- [RFC#1615](https://github.com/rust-lang/rfcs/pull/1615)
- Introduces:
- CARGO_BIN_DIR
- CARGO_CACHE_DIR
- CARGO_CONFIG_DIR
- macOS: Use app dirs, not XDG
- [Further investigation showed that command line applications on Mac OS X almost universally do not follow this scheme, and it would be outside of the norms for cargo to follow it.](https://github.com/rust-lang/rfcs/pull/1615#issuecomment-233500599)
- Precedence
- Use new if set, nonempty
- Use CARGO_HOME, if set
- Use platform dirs if exist
- Use `.cargo` if exist
- Use platform dirs
- rustup would create symlinks for old cargo
- `cargo dirs` subcommand to get the dirs
- Summary
- https://github.com/rust-lang/rfcs/pull/1615#issuecomment-262343742
- https://github.com/rust-lang/rfcs/pull/1615#issuecomment-274235688
- https://github.com/rust-lang/rfcs/pull/1615#issuecomment-324535074
- [spacekookie's unpublished RFC](https://github.com/spacekookie/rfcs/pull/1/files)
- Introduces:
- CARGO_BIN_DIR
- Formerly `$CARGO_HOME/bin`, `$CARGO_HOME/.crates.toml`, `$CARGO_HOME/.crates2.json`
- CARGO_CACHE_DIR
- `$CARGO_CONFIG_DIR/git`
- `$CARGO_CONFIG_DIR/registry`
- CARGO_CONFIG_DIR
- `$CARGO_CONFIG_DIR/config.toml`
- `$CARGO_HOME/credentials`?
- People are less likely to scrutinize what they put in a `.config` git repo and could accidentally leak their credentials
- [poignardazur's blog post](https://poignardazur.github.io/2023/05/23/platform-compliance-in-cargo/)
- Introduces:
- CARGO_BIN_DIR?
- Is there enough precedence for this?
- cargo/rustup assumes complete control
- CARGO_CACHE_DIR
- CARGO_CONFIG_DIR
- Update `home` to support these
- Initially, these map back to existing locations
- Transition plan
- Initially, `home` crate will provide new functions that map to old locations
- Next, support full precedence but fallback to old locations
- Next, change fallback to new locations
- macOS: Use app dirs, not XDG
- Precedence
- If CARGO_HOME is set
- use that as the **fallback** for a `CARGO_*_DIR` not being set
- Else use CARGO_HOME
- Set CARGO_HOME to the old location
- If `CARGO_*_DIR` is set, use that
- If platform-specific dir exists, use that
- Else use ... (depends on transition plan)
- rustup runs through above and sets the variables
- Rustup currently uses RUSTUP_HOME and defaults to $HOME/.rustup. It would need its own RUSTUP_CACHE_DIR and RUSTUP_CONFIG_DIR env variables. Presumably they would be set in a way consistent with CARGO_HOME and CARGO_***_DIR, but the code should not assume that this is the case.
- epage
- CARGO_CONFIG_DIR
- Like git, read `$CARGO_HOME/config.toml` **and** `$CARGO_CONFIG_DIR/config.toml` (if different)
- CARGO_CACHE_DIR
- Hard split like git->sparse registry
- Backup: transition plan like poignardazur
- CARGO_BIN_DIR
- Must be separate from `CARGO_CACHE_DIR` since users shouldn't be as free to delete this as `CARGO_CACHE_DIR`
- Must take into account that rustup expects total control of this directory atm
- Precedence
- If `CARGO_*_DIR` is set, use that
- If CARGO_HOME is set, use that
- Else ...
- Initially, these map to existing locations
- Eventually, switch to OS-native paths
- macOS: use XDG as that seems to be the stronger precedent for unix-y CLI tools
- Recognizing not everyone will agree with this
- Can use env variables to force OS-native behavior
- Maybe `cargo --print config-dir --print cache-dir` for programmatic lookup
- Meant to model `rustc --print <item>`
- Alt: `cargo config get`
- Alt: `cargo dirs` or `cargo home`
- Rustup currently uses RUSTUP_HOME and defaults to $HOME/.rustup. It would need its own RUSTUP_CACHE_DIR and RUSTUP_CONFIG_DIR env variables. Presumably they would be set in a way consistent with CARGO_HOME and CARGO_***_DIR, but the code should not assume that this is the case.
- These new variables would be prevented from being set in cargo config