From 5770ceaa19d3aa1e5d4209918475fda70dc2734f Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Sat, 14 May 2016 18:56:05 +0200 Subject: [PATCH 1/8] Let Cargo put data into platform-specific directories --- text/1615-cargo-platform-standards.md | 102 ++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 text/1615-cargo-platform-standards.md diff --git a/text/1615-cargo-platform-standards.md b/text/1615-cargo-platform-standards.md new file mode 100644 index 00000000000..130da47eae2 --- /dev/null +++ b/text/1615-cargo-platform-standards.md @@ -0,0 +1,102 @@ +- Feature Name: N/A +- Start Date: 2016-05-14 +- RFC PR: + [rust-lang/rfcs#1615](https://github.com/rust-lang/rfcs/pull/1615) +- Cargo Issues: + [rust-lang/cargo#1734](https://github.com/rust-lang/cargo/issues/1734) + [rust-lang/cargo#1976](https://github.com/rust-lang/cargo/issues/1976) + +# Summary + +Improve Cargo's integration into the host operating system by using +platform-specific paths for config files, temporary files and caches, 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. Using standard directories is the best way +to go unless there are concrete reasons for not doing so, otherwise Cargo just +adds complexity to all systems that try to interoperate with it. Benefits +include: + +* Using a standard directory for binary outputs can allow the user to execute + Cargo-installed binaries without modifying their `PATH` variable. E.g. on + Fedora this is apparantly already the case, in Debian there's a ticket to + include it. +* Putting caches in designated cache directories allows backup tools to ignore + them. +* Using a `.cargo` directory on Windows is not idiomatic at all, no programs + for Windows would such a directory. +* Platform specific clean-up tools such as the Disk Cleanup Wizard work with + Cargo (it wouldn't be very useful to try to modify the Wizard instead of + Cargo to make this work). + +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". + +There seems to prior art for this in pip, the Python package manager. + +# 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`, use + that for all files. +2. Otherwise, if the platform-specific directories exist, use them. +3. If that's not the case, check whether the legacy directory exists (`.cargo`) + and use it in that case. +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. + +## Windows + +We'll obtain each of the following directories using the correct API. + +``` +cache: AppData\Local\Temp\Cargo +config: AppData\Roaming\Cargo +binaries: AppData\Local\Programs\Cargo +``` + +## OS X + +``` +cache: Library/Caches/Cargo +config: Library/Cargo +binaries: Library/Cargo/bin +``` + +## Other unixy systems (Linux, BSDs) + +Here, we're following the XDG spec: + +``` +cache: .cache/cargo +config .config/cargo +binaries: .local/bin +``` +# Drawbacks + +* This increases the complexity of where to find the files Cargo uses. This can + be alleviated by providing library functions for Cargo related tools and a + command line to tell which paths are in use. + +# Alternatives + +* OS X could also use the XDG specification. This would remove the difference + between OS X and other unixy OSs. This is also done by Python's pip. + +* One could only change the Windows paths, as the Windows integration is + currently the worst. + +# Unresolved questions + +* None so far. From c0e0a4275c30cb2a63313db686b5e5a4fcc19151 Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Sat, 14 May 2016 21:31:50 +0200 Subject: [PATCH 2/8] Mention how this can affect tutorials (thanks @steveklabnik) --- text/1615-cargo-platform-standards.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/text/1615-cargo-platform-standards.md b/text/1615-cargo-platform-standards.md index 130da47eae2..add404e3766 100644 --- a/text/1615-cargo-platform-standards.md +++ b/text/1615-cargo-platform-standards.md @@ -89,6 +89,11 @@ binaries: .local/bin be alleviated by providing library functions for Cargo related tools and a command line to tell which paths are in use. +* It can also complicate tutorials that tell users how Cargo works. The + tutorials should probably reference the Cargo subcommand that displays the + used locations. However it's still more complicated than static directory + name (it's in a weird location for Windows users though). + # Alternatives * OS X could also use the XDG specification. This would remove the difference From 170edb7ad7eac79a0edba8473955fcc4d9f82f68 Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Mon, 16 May 2016 19:14:10 +0200 Subject: [PATCH 3/8] Fix a typo --- text/1615-cargo-platform-standards.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1615-cargo-platform-standards.md b/text/1615-cargo-platform-standards.md index add404e3766..bf90abf4774 100644 --- a/text/1615-cargo-platform-standards.md +++ b/text/1615-cargo-platform-standards.md @@ -29,7 +29,7 @@ include: * Putting caches in designated cache directories allows backup tools to ignore them. * Using a `.cargo` directory on Windows is not idiomatic at all, no programs - for Windows would such a directory. + for Windows would use such a directory. * Platform specific clean-up tools such as the Disk Cleanup Wizard work with Cargo (it wouldn't be very useful to try to modify the Wizard instead of Cargo to make this work). From 38f82c4cd99a0bce890c2123e4649e9a40f9a194 Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Mon, 16 May 2016 19:15:24 +0200 Subject: [PATCH 4/8] Use XDG on OS X as well This swaps an alternative with the appropiate section in detailed design. --- text/1615-cargo-platform-standards.md | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/text/1615-cargo-platform-standards.md b/text/1615-cargo-platform-standards.md index bf90abf4774..3017acbbf30 100644 --- a/text/1615-cargo-platform-standards.md +++ b/text/1615-cargo-platform-standards.md @@ -66,15 +66,7 @@ config: AppData\Roaming\Cargo binaries: AppData\Local\Programs\Cargo ``` -## OS X - -``` -cache: Library/Caches/Cargo -config: Library/Cargo -binaries: Library/Cargo/bin -``` - -## Other unixy systems (Linux, BSDs) +## Unixy systems (OS X, Linux, BSDs) Here, we're following the XDG spec: @@ -96,8 +88,8 @@ binaries: .local/bin # Alternatives -* OS X could also use the XDG specification. This would remove the difference - between OS X and other unixy OSs. This is also done by Python's pip. +* OS X could also use the `Library` folder for storing its data. This is mostly + done by UI applications. * One could only change the Windows paths, as the Windows integration is currently the worst. From 6c0547171b7b53ad6cc1472002fb9e8a6f5a1c13 Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Wed, 18 May 2016 09:23:36 +0200 Subject: [PATCH 5/8] Clarify that we're following the XDG spec on non-Windows --- text/1615-cargo-platform-standards.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/text/1615-cargo-platform-standards.md b/text/1615-cargo-platform-standards.md index 3017acbbf30..ccbfee9ec57 100644 --- a/text/1615-cargo-platform-standards.md +++ b/text/1615-cargo-platform-standards.md @@ -68,7 +68,9 @@ binaries: AppData\Local\Programs\Cargo ## Unixy systems (OS X, Linux, BSDs) -Here, we're following the XDG spec: +Here, we're following the [XDG specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-0.7.html). +By default, if no further variables are set, this means that we'll be using the +following subdirectories of the home directory. ``` cache: .cache/cargo From 11e4e4da3350581c7b691ef84378db00605f16ac Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Tue, 9 Jan 2018 12:51:35 +0100 Subject: [PATCH 6/8] Add `CARGO_{BIN,CACHE,CONFIG}_DIR` env variables --- text/1615-cargo-platform-standards.md | 79 ++++++++++++++++++++++++--- 1 file changed, 72 insertions(+), 7 deletions(-) diff --git a/text/1615-cargo-platform-standards.md b/text/1615-cargo-platform-standards.md index ccbfee9ec57..2e037acb3cf 100644 --- a/text/1615-cargo-platform-standards.md +++ b/text/1615-cargo-platform-standards.md @@ -5,6 +5,10 @@ - Cargo Issues: [rust-lang/cargo#1734](https://github.com/rust-lang/cargo/issues/1734) [rust-lang/cargo#1976](https://github.com/rust-lang/cargo/issues/1976) + [rust-lang/cargo#2127](https://github.com/rust-lang/cargo/pull/2127) +- Rustup Issues: + [rust-lang-nursery/rustup.rs#247](https://github.com/rust-lang-nursery/rustup.rs/issues/247) + [rust-lang-nursery/rustup.rs#473](https://github.com/rust-lang-nursery/rustup.rs/issues/473) # Summary @@ -41,15 +45,35 @@ There seems to prior art for this in pip, the Python package manager. # Detailed design +We are going to introduce new environment variables: +``` +CARGO_BIN_DIR +CARGO_CACHE_DIR +CARGO_CONFIG_DIR +``` + +For the default values of these variables if they are set to the empty string +or not set (which will be the common case), see below. + +These will be used to split the current `.cargo` (`CARGO_HOME`) directory up: +The cached packages (`.cargo/git`, `.cargo/registry`) will go into +`CARGO_CACHE_DIR`, binaries (`.cargo/bin`) installed by Cargo will go into +`CARGO_BIN_DIR` and the config (`.cargo/config`) will go into +`CARGO_CONFIG_DIR`. + 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`, use - that for all files. -2. Otherwise, if the platform-specific directories exist, use them. -3. If that's not the case, check whether the legacy directory exists (`.cargo`) +1. If any of the new variables `CARGO_BIN_DIR`, `CARGO_CACHE_DIR`, + `CARGO_CONFIG_DIR` are set and nonempty, use the new directory structure. +2. Else, if there is an override for the legacy Cargo directory, using + `CARGO_HOME`, use that for all files. +3. Otherwise, if the Cargo-specfic platform-specific directories exist, use + them. What constitutes a Cargo-specific directory is laid out below, for + each platform. +4. If that's not the case, check whether the legacy directory exists (`.cargo`) and use it in that case. -4. If everything else fails, create the platform-specific directories and use +5. If everything else fails, create the platform-specific directories and use them. This makes Cargo use platform-specific directories for new installs while @@ -66,7 +90,7 @@ config: AppData\Roaming\Cargo binaries: AppData\Local\Programs\Cargo ``` -## Unixy systems (OS X, Linux, BSDs) +## Unixy systems (macOS, Linux, BSDs) Here, we're following the [XDG specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-0.7.html). By default, if no further variables are set, this means that we'll be using the @@ -77,6 +101,46 @@ cache: .cache/cargo config .config/cargo binaries: .local/bin ``` + +**There is currently an on-going discussion about standardizing the location of +`.local/bin` together with a new XDG variable `XDG_BIN_HOME`. The +implementation of this RFC should be delayed until that discussion has finished +and use the result. This RFC will be amended with that result.** + + +## Rustup + +Rustup will replicate Cargo's priorisation algorithm. If the results differ +from what the executed version of Cargo will do, Rustup will add environment +variables `CARGO_BIN_DIR`, `CARGO_CACHE_DIR`, `CARGO_CONFIG_DIR` for the new +versions of Cargo, and add symlinks for the old versions of Cargo. + + +## New subcommand + +Cargo (and Rustup) are going to gain a new subcommand, `cargo dirs`. It will +display the directories currently in use, in a human-readable format. In order +to support other programs and scripts, this subcommand will also have switches +to print the data in machine-readable form, at least `--json` for JSON output +and maybe `--shell` for env-compatible output. + +Example JSON (specifics left to the implementation): +``` +{ + "bin_dir": "C:\\Users\\User\\AppData\\Local\\Programs\\Cargo", + "cache_dir": "C:\\Users\\User\\AppData\\Local\\Temp\\Cargo", + "config_dir": "C:\\Users\\User\\AppData\\Roaming\\Cargo" +} +``` + +Example (env-compatible): +``` +CARGO_BIN_DIR=/home/user/.local/bin +CARGO_CACHE_DIR=/home/user/.cache/cargo +CARGO_CONFIG_DIR=/home/user/.config/cargo +``` + + # Drawbacks * This increases the complexity of where to find the files Cargo uses. This can @@ -88,9 +152,10 @@ binaries: .local/bin used locations. However it's still more complicated than static directory name (it's in a weird location for Windows users though). + # Alternatives -* OS X could also use the `Library` folder for storing its data. This is mostly +* macOS could also use the `Library` folder for storing its data. This is mostly done by UI applications. * One could only change the Windows paths, as the Windows integration is From 1471b8a0aff71eadee0831b1c9efa45400bf40a4 Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Tue, 9 Jan 2018 13:05:52 +0100 Subject: [PATCH 7/8] Incorporate some of the suggestions from @soc --- text/1615-cargo-platform-standards.md | 40 +++++++++++++++------------ 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/text/1615-cargo-platform-standards.md b/text/1615-cargo-platform-standards.md index 2e037acb3cf..93359c847b2 100644 --- a/text/1615-cargo-platform-standards.md +++ b/text/1615-cargo-platform-standards.md @@ -13,35 +13,37 @@ # Summary Improve Cargo's integration into the host operating system by using -platform-specific paths for config files, temporary files and caches, so it -interacts well with other tools on that platform. +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. Using standard directories is the best way -to go unless there are concrete reasons for not doing so, otherwise Cargo just -adds complexity to all systems that try to interoperate with it. Benefits -include: +Cargo to function in the best way. -* Using a standard directory for binary outputs can allow the user to execute - Cargo-installed binaries without modifying their `PATH` variable. E.g. on - Fedora this is apparantly already the case, in Debian there's a ticket to - include it. +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. -* Using a `.cargo` directory on Windows is not idiomatic at all, no programs - for Windows would use such a directory. -* Platform specific clean-up tools such as the Disk Cleanup Wizard work with - Cargo (it wouldn't be very useful to try to modify the Wizard instead of - Cargo to make this work). + 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)_ 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". -There seems to prior art for this in pip, the Python package manager. +This seems to be implemented in pip, the Python package manager, already. # Detailed design @@ -67,7 +69,8 @@ be checked if the new ones don't exist. In detail, this means: 1. If any of the new variables `CARGO_BIN_DIR`, `CARGO_CACHE_DIR`, `CARGO_CONFIG_DIR` are set and nonempty, use the new directory structure. 2. Else, if there is an override for the legacy Cargo directory, using - `CARGO_HOME`, use that for all files. + `CARGO_HOME`, the directories for cache, configuration and executables are + placed inside this directory. 3. Otherwise, if the Cargo-specfic platform-specific directories exist, use them. What constitutes a Cargo-specific directory is laid out below, for each platform. @@ -161,6 +164,7 @@ CARGO_CONFIG_DIR=/home/user/.config/cargo * One could only change the Windows paths, as the Windows integration is currently the worst. + # Unresolved questions * None so far. From 0215ab6cb5857cd31d791e07e56c7bf238e174a1 Mon Sep 17 00:00:00 2001 From: Pieter Frenssen Date: Mon, 22 Mar 2021 22:13:03 +0200 Subject: [PATCH 8/8] Update RFC with default paths for macOS Ref suggestion https://github.com/rust-lang/rfcs/pull/1615#issuecomment-803561712 --- text/1615-cargo-platform-standards.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/text/1615-cargo-platform-standards.md b/text/1615-cargo-platform-standards.md index 93359c847b2..4b68bcae59c 100644 --- a/text/1615-cargo-platform-standards.md +++ b/text/1615-cargo-platform-standards.md @@ -93,7 +93,7 @@ config: AppData\Roaming\Cargo binaries: AppData\Local\Programs\Cargo ``` -## Unixy systems (macOS, Linux, BSDs) +## Unixy systems (Linux, BSDs) Here, we're following the [XDG specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-0.7.html). By default, if no further variables are set, this means that we'll be using the @@ -105,6 +105,18 @@ config .config/cargo binaries: .local/bin ``` + +## MacOS + +On macOS we follow the standard paths as specified in the [Library Directories](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html) +and will retrieve these from the [API](https://developer.apple.com/documentation/foundation/1414224-nssearchpathfordirectoriesindoma?language=objc). + +``` +cache: Library/Caches/org.rust-lang.Cargo +config Library/Application Support/org.rust-lang.Cargo +binaries: /usr/local/bin +``` + **There is currently an on-going discussion about standardizing the location of `.local/bin` together with a new XDG variable `XDG_BIN_HOME`. The implementation of this RFC should be delayed until that discussion has finished