11//! Canonical definitions of `home_dir`, `cargo_home`, and `rustup_home`.
22//!
3- //! This provides the definition of `home_dir` used by Cargo and
4- //! rustup, as well functions to find the correct value of
5- //! `CARGO_HOME` and `RUSTUP_HOME`.
6- //!
7- //! See also the [`dirs`](https://docs.rs/dirs) crate.
8- //!
9- //! _Note that as of 2019/08/06 it appears that cargo uses this crate. And
10- //! rustup has used this crate since 2019/08/21._
11- //!
123//! The definition of `home_dir` provided by the standard library is
134//! incorrect because it considers the `HOME` environment variable on
145//! Windows. This causes surprising situations where a Rust program
178//! rustup use the standard libraries definition - they use the
189//! definition here.
1910//!
20- //! This crate further provides two functions, `cargo_home` and
11+ //! This crate provides two additional functions, `cargo_home` and
2112//! `rustup_home`, which are the canonical way to determine the
22- //! location that Cargo and rustup store their data.
13+ //! location that Cargo and rustup use to store their data.
14+ //! The `env` module contains utilities for mocking the process environment
15+ //! by Cargo and rustup.
2316//!
2417//! See also this [discussion].
2518//!
2619//! [discussion]: https://github.com/rust-lang/rust/pull/46799#issuecomment-361156935
2720
28- #![ doc( html_root_url = "https://docs.rs/home/0.5.5 " ) ]
21+ #![ doc( html_root_url = "https://docs.rs/home/0.5.6 " ) ]
2922#![ deny( rust_2018_idioms) ]
3023
3124pub mod env;
@@ -36,29 +29,34 @@ mod windows;
3629use std:: io;
3730use std:: path:: { Path , PathBuf } ;
3831
39- /// Returns the path of the current user's home directory if known.
32+ /// Returns the path of the current user's home directory using environment
33+ /// variables or OS-specific APIs.
4034///
4135/// # Unix
4236///
4337/// Returns the value of the `HOME` environment variable if it is set
44- /// and not equal to the empty string. Otherwise, it tries to determine the
45- /// home directory by invoking the `getpwuid_r` function on the UID of the
46- /// current user.
38+ /// **even** if it is an empty string. Otherwise, it tries to determine the
39+ /// home directory by invoking the [`getpwuid_r`][getpwuid] function with
40+ /// the UID of the current user.
41+ ///
42+ /// [getpwuid]: https://linux.die.net/man/3/getpwuid_r
4743///
4844/// # Windows
4945///
50- /// Returns the value of the `USERPROFILE` environment variable if it
51- /// is set and not equal to the empty string. If both do not exist,
52- /// [`SHGetFolderPathW`][msdn] is used to return the appropriate path.
46+ /// Returns the value of the `USERPROFILE` environment variable if it is set
47+ /// **and** it is not an empty string. Otherwise, it tries to determine the
48+ /// home directory by invoking the [`SHGetFolderPathW`][shgfp] function with
49+ /// [`CSIDL_PROFILE`][csidl].
5350///
54- /// [msdn]: https://docs.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetfolderpathw
51+ /// [shgfp]: https://docs.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetfolderpathw
52+ /// [csidl]: https://learn.microsoft.com/en-us/windows/win32/shell/csidl
5553///
5654/// # Examples
5755///
5856/// ```
5957/// match home::home_dir() {
60- /// Some(path) => println!("{}", path.display()),
61- /// None => println!("Impossible to get your home dir!"),
58+ /// Some(path) if !path.as_os_str().is_empty() => println!("{}", path.display()),
59+ /// _ => println!("Unable to get your home dir!"),
6260/// }
6361/// ```
6462pub fn home_dir ( ) -> Option < PathBuf > {
0 commit comments