1 个稳定版本

使用旧的 Rust 2015

3.0.1	2020年6月23日

在文件系统中排名 #703

每月下载量 1,935
在 6 个 Crates 中使用（直接使用 4 个）

MIT/Apache

36KB
181 行

`dirs`

简介

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

该库通过利用 Linux 和 Redox 的 XDG 基目录和 XDG 用户目录规范、Windows 的已知文件夹 API 和 macOS 的标准目录指南来提供这些目录的位置

平台

该库是用 Rust 编写的，并支持 Linux、Redox、macOS 和 Windows。其他平台也得到支持；它们使用 Linux 习惯。

所需的最小 Rust 版本为 1.13。

它的中等级别库姐妹库 directories 可用于 Rust（directories-rs）和 JVM（directories-jvm）。

用法

依赖项

通过将以下内容插入到您的 Cargo.toml 文件的 [dependencies] 部分，将库作为依赖项添加到您的项目中。

dirs = "3.0"

如果您是从版本 2 升级，请先阅读破坏性更改部分。

示例

由 Alice 用户运行的库

extern crate dirs;

dirs::home_dir();
// Lin: Some(/home/alice)
// Win: Some(C:\Users\Alice)
// Mac: Some(/Users/Alice)

dirs::audio_dir();
// Lin: Some(/home/alice/Music)
// Win: Some(C:\Users\Alice\Music)
// Mac: Some(/Users/Alice/Music)

dirs::config_dir();
// Lin: Some(/home/alice/.config)
// Win: Some(C:\Users\Alice\AppData\Roaming)
// Mac: Some(/Users/Alice/Library/Application Support)

dirs::executable_dir();
// Lin: Some(/home/alice/.local/bin)
// Win: None
// Mac: None

设计目标

dirs 库是一个底层 crate，旨在提供由操作系统规则或约定定义的标准目录的路径。
如果您的需求更复杂，例如计算特定应用程序或项目的缓存、配置等路径，请考虑使用directories。
此库不创建目录或检查其存在。该库仅提供特定目录的路径信息。
如何使用这些信息是开发人员根据每个应用程序的需求做出的决定。
此库故意仅关注提供用户可写目录的信息，因为在不同的操作系统上返回指向用户级可写目录的路径而没有系统级只读目录没有明显的好处。
这种方法的混淆和意外失败模式将非常严重。
- executable_dir指定为提供二进制文件的用户可写目录的路径。
  由于此类目录仅在Linux上存在，因此macOS和Windows上返回None。
- font_dir指定为提供字体用户可写目录的路径。
  由于此类目录仅在Linux和macOS上存在，因此Windows上返回None。
- runtime_dir指定为提供非必需运行时数据的目录。要求在用户登录时创建此目录，仅由用户自身访问，在用户注销时删除，并支持操作系统的所有文件系统功能。
  由于此类目录仅在Linux上存在，因此macOS和Windows上返回None。

功能

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

函数名	Linux/Redox上的值	Windows上的值	macOS上的值
`home_dir`	`一些($HOME)`	`一些({FOLDERID_Profile})`	`一些($HOME)`
`cache_dir`	`Some($XDG_CACHE_HOME)`或`Some($HOME`/.cache`)`	`一些({FOLDERID_LocalAppData})`	`Some($XDG_CONFIG_HOME)`或`Some($HOME`/.config`)`
`config_dir`	`Some($XDG_CONFIG_HOME)`或`Some($HOME`/.config`)`	`一些({FOLDERID_RoamingAppData})`	`Some($HOME`/Library/Application Support`)`
`data_dir`	`Some($XDG_DATA_HOME)`或`Some($HOME`/.local/share`)`	`一些({FOLDERID_RoamingAppData})`	`Some($HOME`/Library/Application Support`)`
`data_local_dir`	`Some($XDG_DATA_HOME)`或`Some($HOME`/.local/share`)`	`一些({FOLDERID_LocalAppData})`	`Some($HOME`/Library/Application Support`)`
`executable_dir`	`Some($XDG_DATA_HOME)`或`Some($HOME`/.local/bin`)`	`None`	`None`
`preference_dir`	`Some($XDG_CONFIG_HOME)`或`Some($HOME`/.config`)`	`一些({FOLDERID_RoamingAppData})`	`Some($HOME`/Library/Preferences`)`
`运行时目录`	`Some($XDG_RUNTIME_DIR)` 或 `None`	`None`	`None`
`音频目录`	`Some(XDG_MUSIC_DIR)` 或 `None`	`一些({FOLDERID_Music})`	`Some($HOME`/Music/`)`
`桌面目录`	`Some(XDG_DESKTOP_DIR)` 或 `None`	`一些({FOLDERID_Desktop})`	`Some($HOME`/Desktop/`)`
`文档目录`	`Some(XDG_DOCUMENTS_DIR)` 或 `None`	`一些({FOLDERID_Documents})`	`Some($HOME`/Documents/`)`
`下载目录`	`Some(XDG_DOWNLOAD_DIR)` 或 `None`	`一些({FOLDERID_Downloads})`	`Some($HOME`/Downloads/`)`
`字体目录`	`Some($XDG_DATA_HOME`/fonts/`)` 或 `Some($HOME`/.local/share/fonts/`)`	`None`	`Some($HOME`/Library/Fonts/`)`
`图片目录`	`Some(XDG_PICTURES_DIR)` 或 `None`	`一些({FOLDERID_Pictures})`	`Some($HOME`/Pictures/`)`
`公共目录`	`Some(XDG_PUBLICSHARE_DIR)` 或 `None`	`一些({FOLDERID_Public})`	`Some($HOME`/Public/`)`
`模板目录`	`Some(XDG_TEMPLATES_DIR)` 或 `None`	`一些({FOLDERID_Templates})`	`None`
`视频目录`	`Some(XDG_VIDEOS_DIR)` 或 `None`	`一些({FOLDERID_Videos})`	`Some($HOME`/Movies/`)`

比较

在Rust生态系统中有其他尝试类似或相关功能的库。以下是对它们的概述，并包括了指导此库设计的属性评分。

请以平常心看待此表格：对于您的特定使用场景，可能存在其他更合适的crate。当然，我的 crate在实现我的设计目标方面比其他crate做得更好，这些crate可能有着不同的设计目标。

库	状态	Lin	Mac	Win	Base	User	Proj	Conv
app_dirs	未维护	✔	✔	✔	🞈	✖	✔	✖
app_dirs2	维护中	✔	✔	✔	🞈	✖	✔	✖
dirs	开发中	✔	✔	✔	✔	✔	✖	✔
directories	开发中	✔	✔	✔	✔	✔	✔	✔
s_app_dir	未维护？	✔	✖	🞈	✖	✖	🞈	✖
standard_paths	维护中	✔	✖	✔	✔	✔	✔	✖
xdg	维护中	✔	✖	✖	✔	✖	✔	🞈
xdg-basedir	未维护？	✔	✖	✖	✔	✖	✖	🞈
xdg-rs	已废弃	✔	✖	✖	✔	✖	✖	🞈

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

变更日志

3

重大更改 macOS上config_dir的行为已调整（感谢所有相关人员）
- 现有的config_dir函数已被修改，现在在macOS上返回Application Support目录，如Apple文档中所建议。
- 非macOS平台上config_dir函数的行为没有变化。
- 如果您使用config_dir函数存储文件，可能需要编写代码将文件迁移到macOS上的新位置。
  （替代方案：将config_dir函数的使用改为使用preference_dir函数以保留旧行为。）
新添加的preference_dir函数现在返回macOS上的Preferences目录，根据Apple文档，该目录应仅用于使用Apple专有API存储.plist文件。– preference_dir和config_dir在非macOS平台上的行为相同。

2

Linux上已改进已禁用、缺失或无效的XDG User Dirs条目的行为（由@tmiasko提供，谢谢！）

版本1为这些错误的条目返回用户的家目录（Some($HOME)），除了错误的XDG_DESKTOP_DIR条目返回（Some($HOME/Desktop)）。
版本2为这些条目返回None。

许可

许可方式为以下之一

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许可证定义，您有意提交以包含在本作品中的任何贡献，将按上述方式双许可，不附加任何额外条款或条件。

依赖项

~26–485KB