development/cargo
development/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo synced 2024-10-12 18:52:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

home: fix & enhance documentation

Browse source
This commit is contained in:
Utkarsh Gupta 2023-04-27 16:54:48 +05:30
parent 0ad289b264
commit c078c0ca21
No known key found for this signature in database
GPG key ID: 428BFDF197596BDC
1 changed files with 19 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
crates/home/src/lib.rs
View file

@ -1,14 +1,5 @@
//! Canonical definitions of `home_dir`, `cargo_home`, and `rustup_home`.
//!
//! 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`.
//!
//! See also the [`dirs`](https://docs.rs/dirs) crate.
//!
//! _Note that as of 2019/08/06 it appears that cargo uses this crate. And
//! rustup has used this crate since 2019/08/21._
//!
//! 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
@ -17,9 +8,11 @@
//! rustup use the standard libraries definition - they use the
//! definition here.
//!
//! This crate further provides two functions, `cargo_home` and
//! This crate provides two additional functions, `cargo_home` and
//! `rustup_home`, which are the canonical way to determine the
//! location that Cargo and rustup store their data.
//! location that Cargo and rustup use to store their data.
//! The `env` module contains utilities for mocking the process environment
//! by Cargo and rustup.
//!
//! See also this [discussion].
//!
@ -36,29 +29,34 @@ mod windows;
use std::io;
use std::path::{Path, PathBuf};
/// Returns the path of the current user's home directory if known.
/// Returns the path of the current user's home directory using environment
/// variables or OS-specific APIs.
///
/// # Unix
///
/// Returns the value of the `HOME` environment variable if it is set
/// and not equal to the empty string. Otherwise, it tries to determine the
/// home directory by invoking the `getpwuid_r` function on the UID of the
/// current user.
/// **even** if it is an empty string. Otherwise, it tries to determine the
/// home directory by invoking the [`getpwuid_r`][getpwuid] function with
/// the UID of the current user.
///
/// [getpwuid]: https://linux.die.net/man/3/getpwuid_r
///
/// # Windows
///
/// Returns the value of the `USERPROFILE` environment variable if it
/// is set and not equal to the empty string. If both do not exist,
/// [`SHGetFolderPathW`][msdn] is used to return the appropriate path.
/// Returns the value of the `USERPROFILE` environment variable if it is set
/// **and** it is not an empty string. Otherwise, it tries to determine the
/// home directory by invoking the [`SHGetFolderPathW`][shgfp] function with
/// [`CSIDL_PROFILE`][csidl].
///
/// [msdn]: https://docs.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetfolderpathw
/// [shgfp]: https://docs.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetfolderpathw
/// [csidl]: https://learn.microsoft.com/en-us/windows/win32/shell/csidl
///
/// # Examples
///
/// ```
/// match home::home_dir() {
/// Some(path) => println!("{}", path.display()),
/// None => println!("Impossible to get your home dir!"),
/// Some(path) if !path.as_os_str().is_empty() => println!("{}", path.display()),
/// _ => println!("Unable to get your home dir!"),
/// }
/// ```
pub fn home_dir() -> Option<PathBuf> {