dirs_next/lib.rs
1//! The _dirs-next_ crate is
2//!
3//! - a tiny library with a minimal API (16 functions)
4//! - that provides the platform-specific, user-accessible locations
5//! - for finding and storing configuration, cache and other data
6//! - on Linux, Redox, Windows (≥ Vista) and macOS.
7//!
8//! The library provides the location of these directories by leveraging the mechanisms defined by
9//!
10//! - the [XDG base directory](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) and the [XDG user directory](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/) specifications on Linux,
11//! - the [Known Folder](https://msdn.microsoft.com/en-us/library/windows/desktop/bb776911(v=vs.85).aspx) system on Windows, and
12//! - the [Standard Directories](https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW6) on macOS.
13
14#![deny(missing_docs)]
15#![warn(rust_2018_idioms)]
16
17use cfg_if::cfg_if;
18
19use std::path::PathBuf;
20
21cfg_if! {
22 if #[cfg(target_os = "windows")] {
23 mod win;
24 use win as sys;
25 } else if #[cfg(any(target_os = "macos", target_os = "ios"))] {
26 mod mac;
27 use mac as sys;
28 } else if #[cfg(target_arch = "wasm32")] {
29 mod wasm;
30 use wasm as sys;
31 } else {
32 mod lin;
33 use crate::lin as sys;
34 }
35}
36
37/// Returns the path to the user's home directory.
38///
39/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
40///
41/// |Platform | Value | Example |
42/// | ------- | -------------------- | -------------- |
43/// | Linux | `$HOME` | /home/alice |
44/// | macOS | `$HOME` | /Users/Alice |
45/// | Windows | `{FOLDERID_Profile}` | C:\Users\Alice |
46///
47/// ### Linux and macOS:
48///
49/// - Use `$HOME` if it is set and not empty.
50/// - If `$HOME` is not set or empty, then the function `getpwuid_r` is used to determine
51/// the home directory of the current user.
52/// - If `getpwuid_r` lacks an entry for the current user id or the home directory field is empty,
53/// then the function returns `None`.
54///
55/// ### Windows:
56///
57/// This function retrieves the user profile folder using `SHGetKnownFolderPath`.
58///
59/// All the examples on this page mentioning `$HOME` use this behavior.
60///
61/// _Note:_ This function's behavior differs from [`std::env::home_dir`],
62/// which works incorrectly on Linux, macOS and Windows.
63///
64/// [`std::env::home_dir`]: https://doc.rust-lang.org/std/env/fn.home_dir.html
65pub fn home_dir() -> Option<PathBuf> {
66 sys::home_dir()
67}
68/// Returns the path to the user's cache directory.
69///
70/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
71///
72/// |Platform | Value | Example |
73/// | ------- | ----------------------------------- | ---------------------------- |
74/// | Linux | `$XDG_CACHE_HOME` or `$HOME`/.cache | /home/alice/.cache |
75/// | macOS | `$HOME`/Library/Caches | /Users/Alice/Library/Caches |
76/// | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local |
77pub fn cache_dir() -> Option<PathBuf> {
78 sys::cache_dir()
79}
80/// Returns the path to the user's config directory.
81///
82/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
83///
84/// |Platform | Value | Example |
85/// | ------- | ------------------------------------- | -------------------------------- |
86/// | Linux | `$XDG_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config |
87/// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support |
88/// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming |
89pub fn config_dir() -> Option<PathBuf> {
90 sys::config_dir()
91}
92/// Returns the path to the user's data directory.
93///
94/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
95///
96/// |Platform | Value | Example |
97/// | ------- | ---------------------------------------- | ---------------------------------------- |
98/// | Linux | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share |
99/// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support |
100/// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming |
101pub fn data_dir() -> Option<PathBuf> {
102 sys::data_dir()
103}
104/// Returns the path to the user's local data directory.
105///
106/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
107///
108/// |Platform | Value | Example |
109/// | ------- | ---------------------------------------- | ---------------------------------------- |
110/// | Linux | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share |
111/// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support |
112/// | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local |
113pub fn data_local_dir() -> Option<PathBuf> {
114 sys::data_local_dir()
115}
116/// Returns the path to the user's executable directory.
117///
118/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
119///
120/// |Platform | Value | Example |
121/// | ------- | ---------------------------------------------------------------- | ---------------------- |
122/// | Linux | `$XDG_BIN_HOME` or `$XDG_DATA_HOME`/../bin or `$HOME`/.local/bin | /home/alice/.local/bin |
123/// | macOS | – | – |
124/// | Windows | – | – |
125pub fn executable_dir() -> Option<PathBuf> {
126 sys::executable_dir()
127}
128/// Returns the path to the user's runtime directory.
129///
130/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
131///
132/// |Platform | Value | Example |
133/// | ------- | ------------------ | --------------- |
134/// | Linux | `$XDG_RUNTIME_DIR` | /run/user/1001/ |
135/// | macOS | – | – |
136/// | Windows | – | – |
137pub fn runtime_dir() -> Option<PathBuf> {
138 sys::runtime_dir()
139}
140
141/// Returns the path to the user's audio directory.
142///
143/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
144///
145/// |Platform | Value | Example |
146/// | ------- | ------------------ | -------------------- |
147/// | Linux | `XDG_MUSIC_DIR` | /home/alice/Music |
148/// | macOS | `$HOME`/Music | /Users/Alice/Music |
149/// | Windows | `{FOLDERID_Music}` | C:\Users\Alice\Music |
150pub fn audio_dir() -> Option<PathBuf> {
151 sys::audio_dir()
152}
153/// Returns the path to the user's desktop directory.
154///
155/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
156///
157/// |Platform | Value | Example |
158/// | ------- | -------------------- | ---------------------- |
159/// | Linux | `XDG_DESKTOP_DIR` | /home/alice/Desktop |
160/// | macOS | `$HOME`/Desktop | /Users/Alice/Desktop |
161/// | Windows | `{FOLDERID_Desktop}` | C:\Users\Alice\Desktop |
162pub fn desktop_dir() -> Option<PathBuf> {
163 sys::desktop_dir()
164}
165/// Returns the path to the user's document directory.
166///
167/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
168///
169/// |Platform | Value | Example |
170/// | ------- | ---------------------- | ------------------------ |
171/// | Linux | `XDG_DOCUMENTS_DIR` | /home/alice/Documents |
172/// | macOS | `$HOME`/Documents | /Users/Alice/Documents |
173/// | Windows | `{FOLDERID_Documents}` | C:\Users\Alice\Documents |
174pub fn document_dir() -> Option<PathBuf> {
175 sys::document_dir()
176}
177/// Returns the path to the user's download directory.
178///
179/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
180///
181/// |Platform | Value | Example |
182/// | ------- | ---------------------- | ------------------------ |
183/// | Linux | `XDG_DOWNLOAD_DIR` | /home/alice/Downloads |
184/// | macOS | `$HOME`/Downloads | /Users/Alice/Downloads |
185/// | Windows | `{FOLDERID_Downloads}` | C:\Users\Alice\Downloads |
186pub fn download_dir() -> Option<PathBuf> {
187 sys::download_dir()
188}
189/// Returns the path to the user's font directory.
190///
191/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
192///
193/// |Platform | Value | Example |
194/// | ------- | ---------------------------------------------------- | ------------------------------ |
195/// | Linux | `$XDG_DATA_HOME`/fonts or `$HOME`/.local/share/fonts | /home/alice/.local/share/fonts |
196/// | macOS | `$HOME/Library/Fonts` | /Users/Alice/Library/Fonts |
197/// | Windows | – | – |
198pub fn font_dir() -> Option<PathBuf> {
199 sys::font_dir()
200}
201/// Returns the path to the user's picture directory.
202///
203/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
204///
205/// |Platform | Value | Example |
206/// | ------- | --------------------- | ----------------------- |
207/// | Linux | `XDG_PICTURES_DIR` | /home/alice/Pictures |
208/// | macOS | `$HOME`/Pictures | /Users/Alice/Pictures |
209/// | Windows | `{FOLDERID_Pictures}` | C:\Users\Alice\Pictures |
210pub fn picture_dir() -> Option<PathBuf> {
211 sys::picture_dir()
212}
213/// Returns the path to the user's public directory.
214///
215/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
216///
217/// |Platform | Value | Example |
218/// | ------- | --------------------- | ------------------- |
219/// | Linux | `XDG_PUBLICSHARE_DIR` | /home/alice/Public |
220/// | macOS | `$HOME`/Public | /Users/Alice/Public |
221/// | Windows | `{FOLDERID_Public}` | C:\Users\Public |
222pub fn public_dir() -> Option<PathBuf> {
223 sys::public_dir()
224}
225/// Returns the path to the user's template directory.
226///
227/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
228///
229/// |Platform | Value | Example |
230/// | ------- | ---------------------- | ---------------------------------------------------------- |
231/// | Linux | `XDG_TEMPLATES_DIR` | /home/alice/Templates |
232/// | macOS | – | – |
233/// | Windows | `{FOLDERID_Templates}` | C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Templates |
234pub fn template_dir() -> Option<PathBuf> {
235 sys::template_dir()
236}
237
238/// Returns the path to the user's video directory.
239///
240/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
241///
242/// |Platform | Value | Example |
243/// | ------- | ------------------- | --------------------- |
244/// | Linux | `XDG_VIDEOS_DIR` | /home/alice/Videos |
245/// | macOS | `$HOME`/Movies | /Users/Alice/Movies |
246/// | Windows | `{FOLDERID_Videos}` | C:\Users\Alice\Videos |
247pub fn video_dir() -> Option<PathBuf> {
248 sys::video_dir()
249}
250
251#[cfg(test)]
252mod tests {
253 #[test]
254 fn test_dirs() {
255 println!("home_dir: {:?}", crate::home_dir());
256 println!("cache_dir: {:?}", crate::cache_dir());
257 println!("config_dir: {:?}", crate::config_dir());
258 println!("data_dir: {:?}", crate::data_dir());
259 println!("data_local_dir: {:?}", crate::data_local_dir());
260 println!("executable_dir: {:?}", crate::executable_dir());
261 println!("runtime_dir: {:?}", crate::runtime_dir());
262 println!("audio_dir: {:?}", crate::audio_dir());
263 println!("home_dir: {:?}", crate::desktop_dir());
264 println!("cache_dir: {:?}", crate::document_dir());
265 println!("config_dir: {:?}", crate::download_dir());
266 println!("font_dir: {:?}", crate::font_dir());
267 println!("picture_dir: {:?}", crate::picture_dir());
268 println!("public_dir: {:?}", crate::public_dir());
269 println!("template_dir: {:?}", crate::template_dir());
270 println!("video_dir: {:?}", crate::video_dir());
271 }
272}