]>
Commit | Line | Data |
---|---|---|
f20569fa XL |
1 | [![crates.io](https://img.shields.io/crates/v/dirs-next.svg)](https://crates.io/crates/dirs-next) |
2 | [![API documentation](https://docs.rs/dirs-next/badge.svg)](https://docs.rs/dirs-next/) | |
3 | ||
4 | # `dirs-next` | |
5 | ||
6 | **Note**: This is a fork of once-abandoned `dirs` crate. | |
7 | ||
8 | There is a mid-level sister library, [directories-next]. | |
9 | ||
10 | ## Introduction | |
11 | ||
12 | - a tiny low-level library with a minimal API | |
13 | - that provides the platform-specific, user-accessible locations | |
14 | - for retrieving and storing configuration, cache and other data | |
15 | - on Linux, Redox, Windows (≥ Vista), macOS and other platforms. | |
16 | ||
17 | The library provides the location of these directories by leveraging the mechanisms defined by | |
18 | - the [XDG base directory](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) and | |
19 | the [XDG user directory](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/) specifications on Linux and Redox | |
20 | - the [Known Folder](https://msdn.microsoft.com/en-us/library/windows/desktop/dd378457.aspx) API on Windows | |
21 | - the [Standard Directories](https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW6) | |
22 | guidelines on macOS | |
23 | ||
24 | ## Platforms | |
25 | ||
26 | This library is written in Rust, and supports Linux, Redox, macOS and Windows. | |
27 | Other platforms are also supported; they use the Linux conventions. | |
28 | ||
29 | ## Minimum Rust version policy | |
30 | ||
31 | The minimal required version of Rust is `1.34.0`. | |
32 | ||
33 | We may bump the Rust version in major and minor releases (`x`/`y` in `x.y.z`). | |
34 | Changing the Rust version will be written in the CHANGELOG. | |
35 | ||
36 | ## Example | |
37 | ||
38 | Library run by user Alice: | |
39 | ||
40 | ```rust | |
41 | dirs_next::home_dir(); | |
42 | // Lin: Some(/home/alice) | |
43 | // Win: Some(C:\Users\Alice) | |
44 | // Mac: Some(/Users/Alice) | |
45 | ||
46 | dirs_next::audio_dir(); | |
47 | // Lin: Some(/home/alice/Music) | |
48 | // Win: Some(C:\Users\Alice\Music) | |
49 | // Mac: Some(/Users/Alice/Music) | |
50 | ||
51 | dirs_next::config_dir(); | |
52 | // Lin: Some(/home/alice/.config) | |
53 | // Win: Some(C:\Users\Alice\AppData\Roaming) | |
54 | // Mac: Some(/Users/Alice/Library/Application Support) | |
55 | ||
56 | dirs_next::executable_dir(); | |
57 | // Lin: Some(/home/alice/.local/bin) | |
58 | // Win: None | |
59 | // Mac: None | |
60 | ``` | |
61 | ||
62 | ## Design Goals | |
63 | ||
64 | - The _dirs-next_ library is a low-level crate designed to provide the paths to standard directories | |
65 | as defined by operating systems rules or conventions. If your requirements are more complex, | |
66 | e. g. computing cache, config, etc. paths for specific applications or projects, consider using | |
67 | [directories-next] instead. | |
68 | - This library does not create directories or check for their existence. The library only provides | |
69 | information on what the path to a certain directory _should_ be. How this information is used is | |
70 | a decision that developers need to make based on the requirements of each individual application. | |
71 | - This library is intentionally focused on providing information on user-writable directories only. | |
72 | There is no discernible benefit in returning a path that points to a user-level, writable | |
73 | directory on one operating system, but a system-level, read-only directory on another, that would | |
74 | outweigh the confusion and unexpected failures such an approach would cause. | |
75 | - `executable_dir` is specified to provide the path to a user-writable directory for binaries.<br/> | |
76 | As such a directory only commonly exists on Linux, it returns `None` on macOS and Windows. | |
77 | - `font_dir` is specified to provide the path to a user-writable directory for fonts.<br/> | |
78 | As such a directory only exists on Linux and macOS, it returns `None` on Windows. | |
79 | - `runtime_dir` is specified to provide the path to a directory for non-essential runtime data. | |
80 | It is required that this directory is created when the user logs in, is only accessible by the | |
81 | user itself, is deleted when the user logs out, and supports all filesystem features of the | |
82 | operating system.<br/> | |
83 | As such a directory only commonly exists on Linux, it returns `None` on macOS and Windows. | |
84 | ||
85 | ## Features | |
86 | ||
87 | **If you want to compute the location of cache, config or data directories for your own application or project, | |
88 | use `ProjectDirs` of the [directories-next] project instead.** | |
89 | ||
90 | | Function name | Value on Linux/Redox | Value on Windows | Value on macOS | | |
91 | | ---------------- | ------------------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------------------- | | |
92 | | `home_dir` | `Some($HOME)` | `Some({FOLDERID_Profile})` | `Some($HOME)` | | |
93 | | `cache_dir` | `Some($XDG_CACHE_HOME)` or `Some($HOME`/.cache`)` | `Some({FOLDERID_LocalAppData})` | `Some($HOME`/Library/Caches`)` | | |
94 | | `config_dir` | `Some($XDG_CONFIG_HOME)` or `Some($HOME`/.config`)` | `Some({FOLDERID_RoamingAppData})` | `Some($HOME`/Library/Application Support`)` | | |
95 | | `data_dir` | `Some($XDG_DATA_HOME)` or `Some($HOME`/.local/share`)` | `Some({FOLDERID_RoamingAppData})` | `Some($HOME`/Library/Application Support`)` | | |
96 | | `data_local_dir` | `Some($XDG_DATA_HOME)` or `Some($HOME`/.local/share`)` | `Some({FOLDERID_LocalAppData})` | `Some($HOME`/Library/Application Support`)` | | |
97 | | `executable_dir` | `Some($XDG_BIN_HOME`/../bin`)` or `Some($XDG_DATA_HOME`/../bin`)` or `Some($HOME`/.local/bin`)` | `None` | `None` | | |
98 | | `runtime_dir` | `Some($XDG_RUNTIME_DIR)` or `None` | `None` | `None` | | |
99 | | `audio_dir` | `Some(XDG_MUSIC_DIR)` or `None` | `Some({FOLDERID_Music})` | `Some($HOME`/Music/`)` | | |
100 | | `desktop_dir` | `Some(XDG_DESKTOP_DIR)` or `None` | `Some({FOLDERID_Desktop})` | `Some($HOME`/Desktop/`)` | | |
101 | | `document_dir` | `Some(XDG_DOCUMENTS_DIR)` or `None` | `Some({FOLDERID_Documents})` | `Some($HOME`/Documents/`)` | | |
102 | | `download_dir` | `Some(XDG_DOWNLOAD_DIR)` or `None` | `Some({FOLDERID_Downloads})` | `Some($HOME`/Downloads/`)` | | |
103 | | `font_dir` | `Some($XDG_DATA_HOME`/fonts/`)` or `Some($HOME`/.local/share/fonts/`)` | `None` | `Some($HOME`/Library/Fonts/`)` | | |
104 | | `picture_dir` | `Some(XDG_PICTURES_DIR)` or `None` | `Some({FOLDERID_Pictures})` | `Some($HOME`/Pictures/`)` | | |
105 | | `public_dir` | `Some(XDG_PUBLICSHARE_DIR)` or `None` | `Some({FOLDERID_Public})` | `Some($HOME`/Public/`)` | | |
106 | | `template_dir` | `Some(XDG_TEMPLATES_DIR)` or `None` | `Some({FOLDERID_Templates})` | `None` | | |
107 | | `video_dir` | `Some(XDG_VIDEOS_DIR)` or `None` | `Some({FOLDERID_Videos})` | `Some($HOME`/Movies/`)` | | |
108 | ||
109 | ## Comparison | |
110 | ||
111 | There are other crates in the Rust ecosystem that try similar or related things. | |
112 | Here is an overview of them, combined with ratings on properties that guided the design of this crate. | |
113 | ||
114 | Please take this table with a grain of salt: a different crate might very well be more suitable for your specific use case. | |
115 | ||
116 | | Library | Status | Lin | Mac | Win |Base|User|Proj|Conv| | |
117 | | --------------------- | -------------- |:---:|:---:|:---:|:--:|:--:|:--:|:--:| | |
118 | | `app_dirs` | Unmaintained | ✔ | ✔ | ✔ | 🞈 | ✖ | ✔ | ✖ | | |
119 | | `app_dirs2` | Maintained | ✔ | ✔ | ✔ | 🞈 | ✖ | ✔ | ✖ | | |
120 | | **dirs-next** | **Developed** | ✔ | ✔ | ✔ | ✔ | ✔ | ✖ | ✔ | | |
121 | | `directories-next` | Developed | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | | |
122 | | `s_app_dir` | Unmaintained? | ✔ | ✖ | 🞈 | ✖ | ✖ | 🞈 | ✖ | | |
123 | | `standard_paths` | Maintained | ✔ | ✖ | ✔ | ✔ | ✔ | ✔ | ✖ | | |
124 | | `xdg` | Maintained | ✔ | ✖ | ✖ | ✔ | ✖ | ✔ | 🞈 | | |
125 | | `xdg-basedir` | Unmaintained? | ✔ | ✖ | ✖ | ✔ | ✖ | ✖ | 🞈 | | |
126 | | `xdg-rs` | Obsolete | ✔ | ✖ | ✖ | ✔ | ✖ | ✖ | 🞈 | | |
127 | ||
128 | - Lin: Linux support | |
129 | - Mac: macOS support | |
130 | - Win: Windows support | |
131 | - Base: Supports [generic base directories](https://github.com/xdg-rs/dirs/tree/master/directories#basedirs) | |
132 | - User: Supports [user directories](https://github.com/xdg-rs/dirs/tree/master/directories#userdirs) | |
133 | - Proj: Supports [project-specific base directories](https://github.com/xdg-rs/dirs/tree/master/directories#projectdirs) | |
134 | - Conv: Follows naming conventions of the operating system it runs on | |
135 | ||
136 | ## Build | |
137 | ||
138 | It's possible to cross-compile this library if the necessary toolchains are installed with rustup. | |
139 | This is helpful to ensure a change hasn't broken code on a different platform. | |
140 | ||
141 | The following commands will build this library on Linux, macOS and Windows: | |
142 | ||
143 | ```console | |
144 | cargo build --target=x86_64-unknown-linux-gnu | |
145 | cargo build --target=x86_64-pc-windows-gnu | |
146 | cargo build --target=x86_64-apple-darwin | |
147 | cargo build --target=x86_64-unknown-redox | |
148 | ``` | |
149 | ||
150 | ## License | |
151 | ||
152 | Licensed under either of | |
153 | ||
154 | * Apache License, Version 2.0 | |
155 | ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) | |
156 | * MIT license | |
157 | ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) | |
158 | ||
159 | at your option. | |
160 | ||
161 | ## Contribution | |
162 | ||
163 | Unless you explicitly state otherwise, any contribution intentionally submitted | |
164 | for inclusion in the work by you, as defined in the Apache-2.0 license, shall be | |
165 | dual licensed as above, without any additional terms or conditions. | |
166 | ||
167 | [directories-next]: https://github.com/xdg-rs/dirs/tree/master/directories |