Rollup merge of #132515 - kornelski:home_fix, r=jhpratt

Fix and undeprecate home_dir()

`home_dir()` has been deprecated for 6 years due to using `HOME` env var on Windows.

It's been a long time, and having a perpetually buggy and deprecated function in the standard library is not useful. I propose fixing and undeprecating it.

6 years seems more than long enough to warn users against relying on this function. The change in behavior is minor, and it's more of a bug fix than breakage. The old behavior is unlikely to be useful, and even if anybody actually needed to specifically use the non-standard `HOME` on Windows, they can trivially mitigate this change by reading the env var themselves.

----

Use of `USERPROFILE` is in line with the `home` crate: https://github.com/rust-lang/cargo/blob/37bc5f0232a0bb72dedd2c14149614fd8cdae649/crates/home/src/windows.rs#L12

The `home` crate uses `SHGetKnownFolderPath` instead of `GetUserProfileDirectoryW`. AFAIK it doesn't make any difference in practice, because `SHGetKnownFolderPath` merely adds support for more kinds of folders, including virtual (non-filesystem) folders identified by a GUID, but the specific case of [`FOLDERID_Profile`](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid#FOLDERID_Profile) is documented as a FIXED folder (a regular filesystem path). Just in case, I've added a note to documentation that the use of `GetUserProfileDirectoryW` can change.

I've used `CURRENT_RUSTC_VERSION` in a doccomment. `replace-version-placeholder` tool seems to perform a simple string replacement, so hopefully it'll get updated.

Author: jieyouxu

library/std/src/env.rs

@@ -608,20 +608,16 @@ impl Error for JoinPathsError {
 ///
 /// # Windows
 ///
-/// - Returns the value of the 'HOME' environment variable if it is set
-///   (including to an empty string).
-/// - Otherwise, returns the value of the 'USERPROFILE' environment variable if it is set
-///   (including to an empty string).
-/// - If both do not exist, [`GetUserProfileDirectory`][msdn] is used to return the path.
+/// - Returns the value of the 'USERPROFILE' environment variable if it is set, and is not an empty string.
+/// - Otherwise, [`GetUserProfileDirectory`][msdn] is used to return the path. This may change in the future.
 ///
 /// [msdn]: https://docs.microsoft.com/en-us/windows/win32/api/userenv/nf-userenv-getuserprofiledirectorya
 ///
-/// # Deprecation
+/// In UWP (Universal Windows Platform) targets this function is unimplemented and always returns `None`.
 ///
-/// This function is deprecated because the behavior on Windows is not correct.
-/// The 'HOME' environment variable is not standard on Windows, and may not produce
-/// desired results; for instance, under Cygwin or Mingw it will return `/home/you`
-/// when it should return `C:\Users\you`.
+/// Before Rust CURRENT_RUSTC_VERSION, this function used to return the value of the 'HOME' environment variable
+/// on Windows, which in Cygwin or Mingw environments could return non-standard paths like `/home/you`
+/// instead of `C:\Users\you`.
 ///
 /// # Examples
 ///

library/std/src/sys/pal/windows/os.rs

@@ -377,8 +377,8 @@ fn home_dir_crt() -> Option<PathBuf> {
 }
 
 pub fn home_dir() -> Option<PathBuf> {
-    crate::env::var_os("HOME")
-        .or_else(|| crate::env::var_os("USERPROFILE"))
+    crate::env::var_os("USERPROFILE")
+        .filter(|s| !s.is_empty())
         .map(PathBuf::from)
         .or_else(home_dir_crt)
 }

library/std/tests/env.rs

@@ -122,19 +122,19 @@ fn env_home_dir() {
 
             assert!(home_dir().is_some());
 
-            set_var("HOME", "/home/MountainView");
+            set_var("HOME", "/home/PaloAlto");
+            assert_ne!(home_dir(), Some(PathBuf::from("/home/PaloAlto")), "HOME must not be used");
+
+            set_var("USERPROFILE", "/home/MountainView");
             assert_eq!(home_dir(), Some(PathBuf::from("/home/MountainView")));
 
             remove_var("HOME");
 
-            set_var("USERPROFILE", "/home/MountainView");
             assert_eq!(home_dir(), Some(PathBuf::from("/home/MountainView")));
 
-            set_var("HOME", "/home/MountainView");
-            set_var("USERPROFILE", "/home/PaloAlto");
-            assert_eq!(home_dir(), Some(PathBuf::from("/home/MountainView")));
+            set_var("USERPROFILE", "");
+            assert_ne!(home_dir(), Some(PathBuf::from("")), "Empty USERPROFILE must be ignored");
 
-            remove_var("HOME");
             remove_var("USERPROFILE");
 
             if let Some(oldhome) = oldhome { set_var("HOME", oldhome); }