121 lines
5.5 KiB
Markdown
121 lines
5.5 KiB
Markdown
# platform-dirs-rs
|
|
|
|
[](https://crates.io/crates/platform-dirs)
|
|
[](https://docs.rs/platform-dirs)
|
|
|
|
A Rust library for obtaining platform dependent directory paths for application and user directories.
|
|
|
|
Uses the following standards:
|
|
- Linux/*BSD: [XDG Base Directories] and [XDG User Directories]
|
|
- macOS: [Standard Directories]
|
|
- Windows: [Known Folder]
|
|
|
|
[XDG Base Directories]: https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
|
|
[XDG user directories]: https://www.freedesktop.org/wiki/Software/xdg-user-dirs/
|
|
[Known Folder]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378457.aspx
|
|
[Standard Directories]: https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW6
|
|
|
|
## Installation
|
|
|
|
Add the following to your Cargo.toml:
|
|
|
|
```toml
|
|
[dependencies]
|
|
platform-dirs = "0.3.0"
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Obtaining paths
|
|
|
|
```rust
|
|
use platform_dirs::{AppDirs, UserDirs};
|
|
|
|
fn main() {
|
|
let app_dirs = AppDirs::new(Some("name"), false).unwrap();
|
|
dbg!(&app_dirs);
|
|
// AppDirs {
|
|
// cache_dir: "/home/cjbassi/.cache/name",
|
|
// config_dir: "/home/cjbassi/.config/name",
|
|
// data_dir: "/home/cjbassi/.local/share/name",
|
|
// state_dir: "/home/cjbassi/.local/state/name"
|
|
// }
|
|
|
|
let user_dirs = UserDirs::new().unwrap();
|
|
dbg!(&user_dirs);
|
|
// UserDirs {
|
|
// desktop_dir: "/home/cjbassi/Desktop",
|
|
// document_dir: "/home/cjbassi/Documents",
|
|
// download_dir: "/home/cjbassi/Downloads",
|
|
// music_dir: "/home/cjbassi/Music",
|
|
// picture_dir: "/home/cjbassi/Pictures",
|
|
// public_dir: "/home/cjbassi/Public",
|
|
// video_dir: "/home/cjbassi/Videos"
|
|
// }
|
|
}
|
|
```
|
|
|
|
### Opening config file
|
|
|
|
```rust
|
|
use std::fs::{self, File};
|
|
|
|
use platform_dirs::AppDirs;
|
|
|
|
fn main() {
|
|
let app_dirs = AppDirs::new(Some("name"), true).unwrap();
|
|
let config_file_path = app_dirs.config_dir.join("config-file");
|
|
|
|
fs::create_dir_all(&app_dirs.config_dir).unwrap();
|
|
|
|
let file = if config_file_path.exists() {
|
|
File::open(config_file_path).unwrap()
|
|
} else {
|
|
File::create(config_file_path).unwrap()
|
|
};
|
|
}
|
|
```
|
|
|
|
## Path list
|
|
|
|
### AppDirs
|
|
|
|
Directory | Windows | Linux/*BSD | macOS
|
|
-----------|--------------------------------------------------------|--------------------------------------|------------------------------------
|
|
cache_dir | `%LOCALAPPDATA%` (`C:\Users\%USERNAME%\AppData\Local`) | `$XDG_CACHE_HOME` (`~/.cache`) | `~/Library/Caches`
|
|
config_dir | `%APPDATA%` (`C:\Users\%USERNAME%\AppData\Roaming`) | `$XDG_CONFIG_HOME` (`~/.config`) | `~/Library/Application Support`
|
|
data_dir | `%LOCALAPPDATA%` (`C:\Users\%USERNAME%\AppData\Local`) | `$XDG_DATA_HOME` (`~/.local/share`) | `~/Library/Application Support`
|
|
state_dir | `%LOCALAPPDATA%` (`C:\Users\%USERNAME%\AppData\Local`) | `$XDG_STATE_HOME` (`~/.local/state`) | `~/Library/Application Support`
|
|
|
|
### UserDirs
|
|
|
|
Directory | Windows | Linux/*BSD | macOS
|
|
-------------|-----------------------------------------------------------|-------------------------------------|------------------
|
|
desktop_dir | `{FOLDERID_Desktop}` (`C:\Users\%USERNAME%\Desktop`) | `$XDG_DESKTOP_DIR` (`~/Desktop`) | `~/Desktop`
|
|
document_dir | `{FOLDERID_Documents}` (`C:\Users\%USERNAME%\Documents`) | `$XDG_DOCUMENTS_DIR` (`~/Documents`) | `~/Documents`
|
|
download_dir | `{FOLDERID_Downloads}` (`C:\Users\%USERNAME%\Downloads`) | `$XDG_DOWNLOAD_DIR` (`~/Downloads`) | `~/Downloads`
|
|
music_dir | `{FOLDERID_Music}` (`C:\Users\%USERNAME%\Music`) | `$XDG_MUSIC_DIR` (`~/Music`) | `~/Music`
|
|
picture_dir | `{FOLDERID_Pictures}` (`C:\Users\%USERNAME%\Pictures`) | `$XDG_PICTURES_DIR` (`~/Pictures`) | `~/Pictures`
|
|
public_dir | `{FOLDERID_Public}` (`C:\Users\%USERNAME%\Public`) | `$XDG_PUBLICSHARE_DIR` (`~/Public`) | `~/Public`
|
|
video_dir | `{FOLDERID_Videos}` (`C:\Users\%USERNAME%\Videos`) | `$XDG_VIDEOS_DIR` (`~/Videos`) | `~/Movies`
|
|
|
|
## Comparisons
|
|
|
|
platform-dirs differs from [dirs-rs](https://github.com/soc/dirs-rs) and [directories-rs](https://github.com/soc/directories-rs) in several ways:
|
|
|
|
- allows for using the XDG spec on macOS for CLI apps
|
|
- changes the config directory on macOS from `Library/Preferences` to `Library/Application Support`
|
|
- `Library/Preferences` is supposed to be used for macOS unique plist preferences: [info](https://www.reddit.com/r/rust/comments/8hbzyx/can_people_here_give_the_dirs_and_directories/dyj4qtk/)
|
|
- only includes directories that are cross platform
|
|
- `AppDirs`:
|
|
- removes `data_local_dir`
|
|
- `UserDirs`:
|
|
- removes `runtime_dir`, `executable_dir`
|
|
- provides a simpler API than directories-rs
|
|
- the fields of `UserDirs` are no longer `Options`
|
|
- the struct fields are now publicly accessible
|
|
- combines the `ProjectDirs` struct into `AppDirs`
|
|
- adds `state_dir` to `AppDirs`
|
|
- documentation can be found [here](https://wiki.debian.org/XDGBaseDirectorySpecification) at the bottom of the page
|
|
- used for stateful application data like logs, history, etc
|
|
- on Linux, returns default platforms values for the `UserDirs` if they are not set instead of returning `None`
|