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