dirs-nextNote: This is a fork of unmaintained dirs crate.
The library provides the location of these directories by leveraging the mechanisms defined by - the XDG base directory and the XDG user directory specifications on Linux and Redox - the Known Folder API on Windows - the Standard Directories guidelines on macOS
This library is written in Rust, and supports Linux, Redox, macOS and Windows. Other platforms are also supported; they use the Linux conventions.
The minimal required version of Rust is 1.36.
It's mid-level sister library, directories, is available for Rust ([directories-next]).
Library run by user Alice:
```rust dirsnext::homedir(); // Lin: Some(/home/alice) // Win: Some(C:\Users\Alice) // Mac: Some(/Users/Alice)
dirsnext::audiodir(); // Lin: Some(/home/alice/Music) // Win: Some(C:\Users\Alice\Music) // Mac: Some(/Users/Alice/Music)
dirsnext::configdir(); // Lin: Some(/home/alice/.config) // Win: Some(C:\Users\Alice\AppData\Roaming) // Mac: Some(/Users/Alice/Library/Preferences)
dirsnext::executabledir(); // Lin: Some(/home/alice/.local/bin) // Win: None // Mac: None ```
executable_dir is specified to provide the path to a user-writable directory for binaries.None on macOS and Windows.font_dir is specified to provide the path to a user-writable directory for fonts.None on Windows.runtime_dir is specified to provide the path to a directory for non-essential runtime data.
It is required that this directory is created when the user logs in, is only accessible by the
user itself, is deleted when the user logs out, and supports all filesystem features of the
operating system.None on macOS and Windows.If you want to compute the location of cache, config or data directories for your own application or project,
use ProjectDirs of the [directories-next] project instead.
| Function name | Value on Linux/Redox | Value on Windows | Value on macOS |
| ---------------- | ------------------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------------------- |
| home_dir | Some($HOME) | Some({FOLDERID_Profile}) | Some($HOME) |
| cache_dir | Some($XDG_CACHE_HOME) or Some($HOME/.cache) | Some({FOLDERID_LocalAppData}) | Some($HOME/Library/Caches) |
| config_dir | Some($XDG_CONFIG_HOME) or Some($HOME/.config) | Some({FOLDERID_RoamingAppData}) | Some($HOME/Library/Preferences) |
| data_dir | Some($XDG_DATA_HOME) or Some($HOME/.local/share) | Some({FOLDERID_RoamingAppData}) | Some($HOME/Library/Application Support) |
| data_local_dir | Some($XDG_DATA_HOME) or Some($HOME/.local/share) | Some({FOLDERID_LocalAppData}) | Some($HOME/Library/Application Support) |
| executable_dir | Some($XDG_BIN_HOME/../bin) or Some($XDG_DATA_HOME/../bin) or Some($HOME/.local/bin) | None | None |
| runtime_dir | Some($XDG_RUNTIME_DIR) or None | None | None |
| audio_dir | Some(XDG_MUSIC_DIR) or None | Some({FOLDERID_Music}) | Some($HOME/Music/) |
| desktop_dir | Some(XDG_DESKTOP_DIR) or None | Some({FOLDERID_Desktop}) | Some($HOME/Desktop/) |
| document_dir | Some(XDG_DOCUMENTS_DIR) or None | Some({FOLDERID_Documents}) | Some($HOME/Documents/) |
| download_dir | Some(XDG_DOWNLOAD_DIR) or None | Some({FOLDERID_Downloads}) | Some($HOME/Downloads/) |
| font_dir | Some($XDG_DATA_HOME/fonts/) or Some($HOME/.local/share/fonts/) | None | Some($HOME/Library/Fonts/) |
| picture_dir | Some(XDG_PICTURES_DIR) or None | Some({FOLDERID_Pictures}) | Some($HOME/Pictures/) |
| public_dir | Some(XDG_PUBLICSHARE_DIR) or None | Some({FOLDERID_Public}) | Some($HOME/Public/) |
| template_dir | Some(XDG_TEMPLATES_DIR) or None | Some({FOLDERID_Templates}) | None |
| video_dir | Some(XDG_VIDEOS_DIR) or None | Some({FOLDERID_Videos}) | Some($HOME/Movies/) |
There are other crates in the Rust ecosystem that try similar or related things. Here is an overview of them, combined with ratings on properties that guided the design of this crate.
Please take this table with a grain of salt: a different crate might very well be more suitable for your specific use case.
| Library | Status | Lin | Mac | Win |Base|User|Proj|Conv|
| --------------------- | -------------- |:---:|:---:|:---:|:--:|:--:|:--:|:--:|
| app_dirs | Unmaintained | ✔ | ✔ | ✔ | 🞈 | ✖ | ✔ | ✖ |
| app_dirs2 | Maintained | ✔ | ✔ | ✔ | 🞈 | ✖ | ✔ | ✖ |
| dirs-next | Developed | ✔ | ✔ | ✔ | ✔ | ✔ | ✖ | ✔ |
| directories-next | Developed | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| s_app_dir | Unmaintained? | ✔ | ✖ | 🞈 | ✖ | ✖ | 🞈 | ✖ |
| standard_paths | Maintained | ✔ | ✖ | ✔ | ✔ | ✔ | ✔ | ✖ |
| xdg | Maintained | ✔ | ✖ | ✖ | ✔ | ✖ | ✔ | 🞈 |
| xdg-basedir | Unmaintained? | ✔ | ✖ | ✖ | ✔ | ✖ | ✖ | 🞈 |
| xdg-rs | Obsolete | ✔ | ✖ | ✖ | ✔ | ✖ | ✖ | 🞈 |
It's possible to cross-compile this library if the necessary toolchains are installed with rustup. This is helpful to ensure a change hasn't broken code on a different platform.
The following commands will build this library on Linux, macOS and Windows:
console
cargo build --target=x86_64-unknown-linux-gnu
cargo build --target=x86_64-pc-windows-gnu
cargo build --target=x86_64-apple-darwin
cargo build --target=x86_64-unknown-redox
Licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.