From 014378f8c07bec557b6c6608e5baf0761a12d504 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 15 Dec 2024 14:20:56 -0800 Subject: [PATCH] Clarify status of `home_dir` Users should be using the standard library `home_dir` instead of this crate. --- crates/home/README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/crates/home/README.md b/crates/home/README.md index 23523f9bd..47f408a1a 100644 --- a/crates/home/README.md +++ b/crates/home/README.md @@ -7,13 +7,19 @@ This provides the definition of `home_dir` used by Cargo and rustup, as well functions to find the correct value of `CARGO_HOME` and `RUSTUP_HOME`. -The definition of `home_dir` provided by the standard library is +The definition of [`home_dir`] provided by the standard library is incorrect because it considers the `HOME` environment variable on Windows. This causes surprising situations where a Rust program will behave differently depending on whether it is run under a Unix emulation environment like Cygwin or MinGW. Neither Cargo nor rustup use the standard library's definition - they use the definition here. +**Note:** This has been fixed in Rust 1.85 to no longer use the `HOME` +environment variable on Windows. If you are still using this crate for the +purpose of getting a home directory, you are strongly encouraged to switch to +using the standard library's [`home_dir`] instead. It is planned to have the +deprecation notice removed in 1.86. + This crate further provides two functions, `cargo_home` and `rustup_home`, which are the canonical way to determine the location that Cargo and rustup store their data. @@ -25,6 +31,7 @@ See [rust-lang/rust#43321]. > crate may make major changes to its APIs or be deprecated without warning. [rust-lang/rust#43321]: https://github.com/rust-lang/rust/issues/43321 +[`home_dir`]: https://doc.rust-lang.org/nightly/std/env/fn.home_dir.html ## License