directories-next

注意：此包是已废弃的 directories 包的分支。

有一个低级姐妹库，dirs-next。

简介

• 一个具有最小 API 的轻量级中级库
• 提供平台特定的用户可访问位置
• 用于检索和存储配置、缓存和其他数据
• 在 Linux、Redox、Windows (≥ Vista)、macOS 和其他平台上。

该库通过利用 Linux 的 XDG 基目录 和 XDG 用户目录 规范

• Windows 的 已知文件夹 API
• macOS 的 标准目录 指南
• 提供这些目录的位置

平台

此库是用 Rust 编写的，并支持 Linux、Redox、macOS 和 Windows。也支持其他平台；它们使用 Linux 规范。

Rust 版本最低要求策略

所需的最小 Rust 版本是 1.34.0。

我们可能会在主版本和次版本中提升Rust的版本（在x/y中，即在x.y.z）。更改Rust版本将在CHANGELOG中记录。

示例

由Alice用户运行的库

use directories_next::{BaseDirs, UserDirs, ProjectDirs};

if let Some(proj_dirs) = ProjectDirs::from("com", "Foo Corp",  "Bar App") {
    proj_dirs.config_dir();
    // Lin: /home/alice/.config/barapp
    // Win: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config
    // Mac: /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
}

if let Some(base_dirs) = BaseDirs::new() {
    base_dirs.executable_dir();
    // Lin: Some(/home/alice/.local/bin)
    // Win: None
    // Mac: None
}

if let Some(user_dirs) = UserDirs::new() {
    user_dirs.audio_dir();
    // Lin: /home/alice/Music
    // Win: C:\Users\Alice\Music
    // Mac: /Users/Alice/Music
}

设计目标

• directories-next库被设计用来在调用BaseDirs::new、UserDirs::new或ProjectDirs::from时提供一个准确的系统状态的快照。随后系统状态的变化不会反映在之前创建的值上。
• 此库不会创建目录或检查它们的存在。该库仅提供特定目录的路径信息。如何使用这些信息是开发者根据每个应用程序的要求自行决定的。
• 此库故意只关注提供用户可写目录的信息。在一个操作系统上返回指向用户级可写目录的路径，而在另一个操作系统上返回系统级只读目录，这种做法不会带来任何可感知的好处，反而会带来混淆和意外的失败。
  • executable_dir被指定以提供二进制的用户可写目录的路径。
    由于这种目录通常只存在于Linux上，它在macOS和Windows上返回None。
  • font_dir被指定以提供字体的用户可写目录的路径。
    由于这种目录只存在于Linux和macOS上，它在Windows上返回None。
  • runtime_dir被指定以提供非必要运行时数据的目录路径。要求该目录在用户登录时创建，只对用户本身可访问，在用户注销时删除，并支持操作系统的所有文件系统功能。
    由于这种目录通常只存在于Linux上，它在macOS和Windows上返回None。

功能

BaseDirs

BaseDirs的预期用例是用来查询由库运行所在的操作系统惯例定义的、用户不可见的标准目录路径。

如果您想计算您自己的应用程序或项目的缓存、配置或数据目录的位置，请使用ProjectDirs。

用户目录

UserDirs 的预期用途是查询用户界面的标准目录路径，这些目录是根据运行库的操作系统约定定义的。

ProjectDirs

ProjectDirs 的预期用途是计算您自己的应用程序或项目缓存、配置或数据目录的位置，这些目录是从标准目录派生出来的。

<project_path> 的具体值由

ProjectDirs::from(qualifier: &str,
                  organization: &str,
                  application: &str)

函数及其在不同操作系统之间的变化。例如，调用

ProjectDirs::from("org"         /*qualifier*/,
                  "Baz Corp"    /*organization*/,
                  "Foo Bar-App" /*application*/)

将得到以下值

ProjectDirs::from_path函数允许直接从PathBuf值创建ProjectDirs结构体。此参数将按原样使用，并不适应操作系统标准。强烈建议不要使用ProjectDirs::from_path，因为其结果至少在三个平台中的两个平台上不会遵循操作系统标准。

比较

在Rust生态系统中有其他crate尝试类似或相关的事情。以下是它们的概述，以及指导此crate设计的属性评分。

请对此表持保留态度：另一个crate可能非常适合您的特定用例。

• Lin：Linux支持
• Mac：macOS支持
• Win：Windows支持
• Base：支持通用基础目录
• User：支持用户目录
• Proj：支持特定项目的基础目录
• Conv：遵循其运行操作系统的命名约定

构建

如果使用rustup安装了必要的工具链，则可以跨编译此库。这有助于确保更改不会在不同平台上破坏编译。

以下命令将在Linux、macOS和Windows上构建此库

cargo build --target=x86_64-unknown-linux-gnu
cargo build --target=x86_64-pc-windows-gnu
cargo build --target=x86_64-apple-darwin
cargo build --target=x86_64-unknown-redox

许可证

根据您的选择，许可协议为以下之一

• Apache License，版本2.0（LICENSE-APACHE或http://www.apache.org/licenses/LICENSE-2.0）
• MIT许可证（LICENSE-MIT或http://opensource.org/licenses/MIT）

。

贡献

除非您明确表示，否则根据Apache-2.0许可证定义的，您提交的任何旨在包含在作品中并由您提交的贡献，应按上述方式双重许可，而不附加任何其他条款或条件。