Skip to content

Commit

Permalink
Better documentation for env::home_dir()'s broken behaviour
Browse files Browse the repository at this point in the history
This improves the documentation to say *why* it was deprecated. The reason was because it reads `HOME` on Windows which is meaningless there. Note that the PR that deprecated it stated that returning an empty string if `HOME` is set to an empty string was a problem, however I can find no evidence that this is the case. `cd` handles it fine whereas if `HOME` is unset it gives an explicit `HOME not set` error.

* Original deprecation reason: https://internals.rust-lang.org/t/deprecate-or-break-fix-std-env-home-dir/7315
* Original deprecation PR: rust-lang/rust#51656

See #71684
  • Loading branch information
Timmmm committed Sep 10, 2022
1 parent 2e18efd commit bb37f69
Showing 1 changed file with 8 additions and 1 deletion.
9 changes: 8 additions & 1 deletion std/src/env.rs
Original file line number Diff line number Diff line change
Expand Up @@ -570,6 +570,13 @@ impl Error for JoinPathsError {
///
/// [msdn]: https://docs.microsoft.com/en-us/windows/win32/api/userenv/nf-userenv-getuserprofiledirectorya
///
/// # Deprecation
///
/// This function is deprecated because the behaviour on Windows is not correct.
/// The 'HOME' environment variable has no meaning on Windows so it should not
/// be checked. This result is that under Cygwin or Mingw it will return `/home/you`
/// when it should return `C:\Users\you`.
///
/// # Examples
///
/// ```
Expand All @@ -582,7 +589,7 @@ impl Error for JoinPathsError {
/// ```
#[deprecated(
since = "1.29.0",
note = "This function's behavior is unexpected and probably not what you want. \
note = "This function's behavior may be unexpected on Windows. \
Consider using a crate from crates.io instead."
)]
#[must_use]
Expand Down

0 comments on commit bb37f69

Please sign in to comment.