Skip to content

Commit

Permalink
Clarify status of home_dir
Browse files Browse the repository at this point in the history
Users should be using the standard library `home_dir` instead of this
crate.
  • Loading branch information
ehuss committed Dec 15, 2024
1 parent 769f622 commit 014378f
Showing 1 changed file with 8 additions and 1 deletion.
9 changes: 8 additions & 1 deletion crates/home/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand Down

0 comments on commit 014378f

Please sign in to comment.