env_home rust crate

一个用于通过环境变量以平台无关的方式确定用户主目录的纯 Rust crate，无需外部依赖。

检查 Unix 上的 HOME 和 Windows 上的 USERPROFILE。

描述

env_home 是一个通用 crate，用于通过环境变量确定当前用户的主目录。

它可以作为 rust 标准库中的 std::env::home_dir (已弃用) 的直接替换。

与 std::env::home_dir 不同，此 crate 仅 查看环境变量，并不尝试回退到特定平台的 API。因此，env_home_dir 的实现 非常简单，不依赖于其他 crate。

此功能与 Golang 的 os.UserHomeDir() 或 Python 的 Path.home() 类似。

env_home::env_home_dir 行为

此 crate 的 API 是一个名为 env_home_dir 的单一函数，它尝试以平台无关的方式从环境变量中获取用户的主目录，支持 Windows 和 Unix (Linux/MacOS/BSD/WSL 等)。

1. 如果环境变量未设置，则返回 None。
2. 如果环境变量设置为空字符串，则返回 None。
3. 在未实现主目录的非 Unix / 非 Windows 平台（如 WASM）上，将返回 None。
4. 如果环境变量设置为非空字符串，则将其作为 PathBuf 返回。

就是这些。

如果您需要一个更全面的 crate，请考虑使用 dirs crate。

用法

cargo add env_home

crate 导出一个名为 env_home_dir 的单一函数，它返回 Option<PathBuf>

use env_home::env_home_dir as home_dir;
fn main() {
    match home_dir() {
        Some(path) => println!("User home directory: {}", path.display()),
        None => println!("No home found. HOME/USERPROFILE not set or empty"),
    }
}

请参阅 std::path::PathBuf 文档 以获取有关如何使用 PathBuf 对象的更多信息。

与 std::env::home_dir 的区别

当 HOME 或 USERPROFILE 设置为空字符串时，env_home_dir 返回 None 而不是 ""。

我认为 std::env::home_dir 试图过于聪明。当 HOME 或 USERPROFILE 环境变量未设置时，它调用平台特定的 API，如 Windows 上的 GetUserProfileDirectoryW 或 Unix 上的 getpwuid_r 作为后备。我们只是放弃并返回 None。

该软件包存在的原因是因为标准库提供的 home_dir 的行为可能在 Windows 上不可预期。因此，它已被 弃用，并且从 Rust 1.29.0（2018 年 9 月）以来一直处于损坏/未修复状态。

作为 home 软件包的替代方案

尽管许多项目已从 std::env::home_dir 切换到 home::home_dir，但这是由 cargo 团队维护的，因此可能是“官方”的。Cargo 团队已明确表示，home 软件包不是供社区一般使用的。

"cargo 团队不希望将 home 作为通用软件包维护" [...] "我们正在考虑记录 home 不是用于除 cargo 和 rustup 之外的目的，并建议人们使用其他软件包。" source

因此，home 软件包拒绝为 WASM 目标编译，并且他们没有计划修复此问题。

env_home 软件包实现了回退无操作，在非 Windows/非 Unix 平台（如 WASM）上返回 None。

其他注意事项

使用 std::env::set_var 在多线程应用程序中更改环境是不安全的。全停。它可能导致随机崩溃或未定义的行为。你已经收到警告。

额外：由于 cargo 默认在并行线程中运行测试，即使你的应用程序不是多线程的，如果你的测试调用了 std::env::set_var，请确保设置 RUST_TEST_THREADS=1 或使用 cargo test -- --test-threads=1，否则你的测试可能会间歇性地崩溃并失败。

请参阅rust-lang/rust#27970 和 Setenv is not Thread Safe and C Doesn't Want to Fix It 获取更多信息。

许可证

版权所有 (c) 2024 Peter Tripp

本项目可根据您的选择在以下许可证下使用：[MIT许可证](https://github.com/notpeter/env-home/blob/803d4d8ccd8b1d1031f0d4f884d03931e918e766/LICENSE-MIT) 或 [Apache许可证，版本2.0](https://github.com/notpeter/env-home/blob/803d4d8ccd8b1d1031f0d4f884d03931e918e766/LICENSE-APACHE)。