Skip to content

Instantly share code, notes, and snippets.

@soc

soc/dirs.md

Last active January 9, 2018 06:34
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save soc/bf891c18e31318b765c30130d77b1eb3 to your computer and use it in GitHub Desktop.
Save soc/bf891c18e31318b765c30130d77b1eb3 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
dirs.md

Summary

Improve Cargo's integration into the host operating system by using platform-specific paths for config files, cache files and executables, so it interacts well with other tools on that platform.

Motivation

Currently, Cargo puts all its files in a directory named .cargo below the home directory of the user. Using this proposal, it would reuse existing standard directories of the host platform. This allows other tools oblivious to Cargo to function in the best way.

Benefits include:

  • Using a .cargo directory is violating the recommendations/rules on most operating systems. (Linux, Windows, macOS. Especially painful on Windows, where dotfiles are not hidden.)
  • Putting caches in designated cache directories allows backup tools to ignore them. (Linux, Windows, macOS. Example: Time Machine ignores the cache directory on macOS.)
  • It makes it easier for users to manage, share and version-control their configuraton files, as configuration files from different applications end up in the same place, instead of being intermingled with cache files. (Linux and macOS.)
  • Cargo contributes to the slow cleanup of the $HOME directory by stopping to add its application-private clutter to it. (Linux.)
  • Using a standard directory for binary outputs can allow the user to execute Cargo-installed binaries without modifying their PATH variable. (Linux (and macOS?).)

Solving this problem will likely also solve the same problem in Cargo-related tools such as rustup as their strategy is "do what Cargo does".

Detailed design

In order to maintain backward compatibility, the old directory locations will be checked if the new ones don't exist. In detail, this means:

  1. If there is an override for the Cargo directory, using CARGO_HOME, the directories for cache, configuration and executables are placed inside this directory.
  2. Otherwise, if the platform-specific directories exist, use them.
  3. Otherwise, check whether the legacy directory exists (.cargo) and use it.
  4. If everything else fails, create the platform-specific directories and use them.

This makes Cargo use platform-specific directories for new installs while retaining compatibility for the old directory layout. It also allows one to keep all Cargo related data in one place if one wishes to.

Linux

Follow the XDG specification as well as the recent proposal adding $XDG_BIN_HOME.

By default, if no further variables are set, this means the following subdirectories will be used:

cache:    ~/.cache/cargo  (`$XDG_CACHE_HOME`)
config:   ~/.config/cargo (`$XDG_CONFIG_HOME`)
binaries: ~/.local/bin    (`$XDG_BIN_HOME`)

Windows

Follow the official recommendations and use KnownFolder API and the KNOWNFOLDERIDs, supplemented by precedences established by other libraries like Qt¹:

cache:    {FOLDERID_LocalAppData}\Cargo\cache
config:   {FOLDERID_AppData}\Roaming\Cargo\config
binaries: {FOLDERID_LocalAppData}\Cargo\bin

¹ Note the difference in meaning between the cache directory as used by Cargo and the temp directory as specified by Windows.

macOS

Follow the Standard Directory rules as specified in the macOS File System Programming Guide:

cache:    ~/Library/Caches/Cargo
config:   ~/Library/Preferences/Cargo
binaries: ~/Applications/Cargo

Unresolved questions

  • Should BSDs follow the XDG base dir spec?
  • $CARGO_HOME should probably replaced with $CARGO_CACHE, $CARGO_CONFIG and $CARGO_BIN.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment