dirs/lib.rs
1//! The _dirs_ crate is
2//!
3//! - a tiny library with a minimal API (18 public 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
16use std::path::PathBuf;
17
18#[cfg(target_os = "windows")]
19mod win;
20#[cfg(target_os = "windows")]
21use win as sys;
22
23#[cfg(any(target_os = "macos", target_os = "ios"))]
24mod mac;
25#[cfg(any(target_os = "macos", target_os = "ios"))]
26use mac as sys;
27
28#[cfg(target_arch = "wasm32")]
29mod wasm;
30#[cfg(target_arch = "wasm32")]
31use wasm as sys;
32
33#[cfg(not(any(
34 target_os = "windows",
35 target_os = "macos", target_os = "ios",
36 target_arch = "wasm32"
37)))]
38mod lin;
39#[cfg(not(any(
40 target_os = "windows",
41 target_os = "macos", target_os = "ios",
42 target_arch = "wasm32"
43)))]
44use lin as sys;
45
46/// Returns the path to the user's home directory.
47///
48/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
49///
50/// |Platform | Value | Example |
51/// | ------- | -------------------- | -------------- |
52/// | Linux | `$HOME` | /home/alice |
53/// | macOS | `$HOME` | /Users/Alice |
54/// | Windows | `{FOLDERID_Profile}` | C:\Users\Alice |
55///
56/// ### Linux and macOS:
57///
58/// - Use `$HOME` if it is set and not empty.
59/// - If `$HOME` is not set or empty, then the function `getpwuid_r` is used to determine
60/// the home directory of the current user.
61/// - If `getpwuid_r` lacks an entry for the current user id or the home directory field is empty,
62/// then the function returns `None`.
63///
64/// ### Windows:
65///
66/// This function retrieves the user profile folder using `SHGetKnownFolderPath`.
67///
68/// All the examples on this page mentioning `$HOME` use this behavior.
69///
70/// _Note:_ This function's behavior differs from [`std::env::home_dir`],
71/// which works incorrectly on Linux, macOS and Windows.
72///
73/// [`std::env::home_dir`]: https://doc.rust-lang.org/std/env/fn.home_dir.html
74pub fn home_dir() -> Option<PathBuf> {
75 sys::home_dir()
76}
77/// Returns the path to the user's cache directory.
78///
79/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
80///
81/// |Platform | Value | Example |
82/// | ------- | ----------------------------------- | ---------------------------- |
83/// | Linux | `$XDG_CACHE_HOME` or `$HOME`/.cache | /home/alice/.cache |
84/// | macOS | `$HOME`/Library/Caches | /Users/Alice/Library/Caches |
85/// | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local |
86pub fn cache_dir() -> Option<PathBuf> {
87 sys::cache_dir()
88}
89/// Returns the path to the user's config directory.
90///
91/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
92///
93/// |Platform | Value | Example |
94/// | ------- | ------------------------------------- | ---------------------------------------- |
95/// | Linux | `$XDG_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config |
96/// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support |
97/// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming |
98pub fn config_dir() -> Option<PathBuf> {
99 sys::config_dir()
100}
101/// Returns the path to the user's data directory.
102///
103/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
104///
105/// |Platform | Value | Example |
106/// | ------- | ---------------------------------------- | ---------------------------------------- |
107/// | Linux | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share |
108/// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support |
109/// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming |
110pub fn data_dir() -> Option<PathBuf> {
111 sys::data_dir()
112}
113/// Returns the path to the user's local data directory.
114///
115/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
116///
117/// |Platform | Value | Example |
118/// | ------- | ---------------------------------------- | ---------------------------------------- |
119/// | Linux | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share |
120/// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support |
121/// | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local |
122pub fn data_local_dir() -> Option<PathBuf> {
123 sys::data_local_dir()
124}
125/// Returns the path to the user's executable directory.
126///
127/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
128///
129/// |Platform | Value | Example |
130/// | ------- | ---------------------------------------------------------------- | ---------------------- |
131/// | Linux | `$XDG_BIN_HOME` or `$XDG_DATA_HOME`/../bin or `$HOME`/.local/bin | /home/alice/.local/bin |
132/// | macOS | – | – |
133/// | Windows | – | – |
134pub fn executable_dir() -> Option<PathBuf> {
135 sys::executable_dir()
136}
137/// Returns the path to the user's preference directory.
138///
139/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
140///
141/// |Platform | Value | Example |
142/// | ------- | ------------------------------------- | -------------------------------- |
143/// | Linux | `$XDG_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config |
144/// | macOS | `$HOME`/Library/Preferences | /Users/Alice/Library/Preferences |
145/// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming |
146pub fn preference_dir() -> Option<PathBuf> {
147 sys::preference_dir()
148}
149/// Returns the path to the user's runtime directory.
150///
151/// The runtime directory contains transient, non-essential data (like sockets or named pipes) that
152/// is expected to be cleared when the user's session ends.
153///
154/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
155///
156/// |Platform | Value | Example |
157/// | ------- | ------------------ | --------------- |
158/// | Linux | `$XDG_RUNTIME_DIR` | /run/user/1001/ |
159/// | macOS | – | – |
160/// | Windows | – | – |
161pub fn runtime_dir() -> Option<PathBuf> {
162 sys::runtime_dir()
163}
164/// Returns the path to the user's state directory.
165///
166/// The state directory contains data that should be retained between sessions (unlike the runtime
167/// directory), but may not be important/portable enough to be synchronized across machines (unlike
168/// the config/preferences/data directories).
169///
170/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
171///
172/// |Platform | Value | Example |
173/// | ------- | ----------------------------------------- | ------------------------ |
174/// | Linux | `$XDG_STATE_HOME` or `$HOME`/.local/state | /home/alice/.local/state |
175/// | macOS | – | – |
176/// | Windows | – | – |
177pub fn state_dir() -> Option<PathBuf> {
178 sys::state_dir()
179}
180
181/// Returns the path to the user's audio directory.
182///
183/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
184///
185/// |Platform | Value | Example |
186/// | ------- | ------------------ | -------------------- |
187/// | Linux | `XDG_MUSIC_DIR` | /home/alice/Music |
188/// | macOS | `$HOME`/Music | /Users/Alice/Music |
189/// | Windows | `{FOLDERID_Music}` | C:\Users\Alice\Music |
190pub fn audio_dir() -> Option<PathBuf> {
191 sys::audio_dir()
192}
193/// Returns the path to the user's desktop directory.
194///
195/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
196///
197/// |Platform | Value | Example |
198/// | ------- | -------------------- | ---------------------- |
199/// | Linux | `XDG_DESKTOP_DIR` | /home/alice/Desktop |
200/// | macOS | `$HOME`/Desktop | /Users/Alice/Desktop |
201/// | Windows | `{FOLDERID_Desktop}` | C:\Users\Alice\Desktop |
202pub fn desktop_dir() -> Option<PathBuf> {
203 sys::desktop_dir()
204}
205/// Returns the path to the user's document directory.
206///
207/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
208///
209/// |Platform | Value | Example |
210/// | ------- | ---------------------- | ------------------------ |
211/// | Linux | `XDG_DOCUMENTS_DIR` | /home/alice/Documents |
212/// | macOS | `$HOME`/Documents | /Users/Alice/Documents |
213/// | Windows | `{FOLDERID_Documents}` | C:\Users\Alice\Documents |
214pub fn document_dir() -> Option<PathBuf> {
215 sys::document_dir()
216}
217/// Returns the path to the user's download directory.
218///
219/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
220///
221/// |Platform | Value | Example |
222/// | ------- | ---------------------- | ------------------------ |
223/// | Linux | `XDG_DOWNLOAD_DIR` | /home/alice/Downloads |
224/// | macOS | `$HOME`/Downloads | /Users/Alice/Downloads |
225/// | Windows | `{FOLDERID_Downloads}` | C:\Users\Alice\Downloads |
226pub fn download_dir() -> Option<PathBuf> {
227 sys::download_dir()
228}
229/// Returns the path to the user's font directory.
230///
231/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
232///
233/// |Platform | Value | Example |
234/// | ------- | ---------------------------------------------------- | ------------------------------ |
235/// | Linux | `$XDG_DATA_HOME`/fonts or `$HOME`/.local/share/fonts | /home/alice/.local/share/fonts |
236/// | macOS | `$HOME/Library/Fonts` | /Users/Alice/Library/Fonts |
237/// | Windows | – | – |
238pub fn font_dir() -> Option<PathBuf> {
239 sys::font_dir()
240}
241/// Returns the path to the user's picture directory.
242///
243/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
244///
245/// |Platform | Value | Example |
246/// | ------- | --------------------- | ----------------------- |
247/// | Linux | `XDG_PICTURES_DIR` | /home/alice/Pictures |
248/// | macOS | `$HOME`/Pictures | /Users/Alice/Pictures |
249/// | Windows | `{FOLDERID_Pictures}` | C:\Users\Alice\Pictures |
250pub fn picture_dir() -> Option<PathBuf> {
251 sys::picture_dir()
252}
253/// Returns the path to the user's public directory.
254///
255/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
256///
257/// |Platform | Value | Example |
258/// | ------- | --------------------- | ------------------- |
259/// | Linux | `XDG_PUBLICSHARE_DIR` | /home/alice/Public |
260/// | macOS | `$HOME`/Public | /Users/Alice/Public |
261/// | Windows | `{FOLDERID_Public}` | C:\Users\Public |
262pub fn public_dir() -> Option<PathBuf> {
263 sys::public_dir()
264}
265/// Returns the path to the user's template directory.
266///
267/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
268///
269/// |Platform | Value | Example |
270/// | ------- | ---------------------- | ---------------------------------------------------------- |
271/// | Linux | `XDG_TEMPLATES_DIR` | /home/alice/Templates |
272/// | macOS | – | – |
273/// | Windows | `{FOLDERID_Templates}` | C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Templates |
274pub fn template_dir() -> Option<PathBuf> {
275 sys::template_dir()
276}
277
278/// Returns the path to the user's video directory.
279///
280/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
281///
282/// |Platform | Value | Example |
283/// | ------- | ------------------- | --------------------- |
284/// | Linux | `XDG_VIDEOS_DIR` | /home/alice/Videos |
285/// | macOS | `$HOME`/Movies | /Users/Alice/Movies |
286/// | Windows | `{FOLDERID_Videos}` | C:\Users\Alice\Videos |
287pub fn video_dir() -> Option<PathBuf> {
288 sys::video_dir()
289}
290
291#[cfg(test)]
292mod tests {
293 #[test]
294 fn test_dirs() {
295 println!("home_dir: {:?}", ::home_dir());
296 println!();
297 println!("cache_dir: {:?}", ::cache_dir());
298 println!("config_dir: {:?}", ::config_dir());
299 println!("data_dir: {:?}", ::data_dir());
300 println!("data_local_dir: {:?}", ::data_local_dir());
301 println!("executable_dir: {:?}", ::executable_dir());
302 println!("preference_dir: {:?}", ::preference_dir());
303 println!("runtime_dir: {:?}", ::runtime_dir());
304 println!("state_dir: {:?}", ::state_dir());
305 println!();
306 println!("audio_dir: {:?}", ::audio_dir());
307 println!("desktop_dir: {:?}", ::desktop_dir());
308 println!("cache_dir: {:?}", ::document_dir());
309 println!("config_dir: {:?}", ::download_dir());
310 println!("font_dir: {:?}", ::font_dir());
311 println!("picture_dir: {:?}", ::picture_dir());
312 println!("public_dir: {:?}", ::public_dir());
313 println!("template_dir: {:?}", ::template_dir());
314 println!("video_dir: {:?}", ::video_dir());
315 }
316}