]>
Commit | Line | Data |
---|---|---|
f20569fa XL |
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 | ||
17 | use cfg_if::cfg_if; | |
18 | ||
19 | use std::path::PathBuf; | |
20 | ||
21 | cfg_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 | |
65 | pub 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 | | |
77 | pub 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 | | |
89 | pub 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 | | |
101 | pub 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 | | |
113 | pub 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 | – | – | | |
125 | pub 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 | – | – | | |
137 | pub 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 | | |
150 | pub 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 | | |
162 | pub 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 | | |
174 | pub 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 | | |
186 | pub 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 | – | – | | |
198 | pub 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 | | |
210 | pub 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 | | |
222 | pub 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 | | |
234 | pub 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 | | |
247 | pub fn video_dir() -> Option<PathBuf> { | |
248 | sys::video_dir() | |
249 | } | |
250 | ||
251 | #[cfg(test)] | |
252 | mod 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 | } |