X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=vendor%2Fdirs%2Fsrc%2Flib.rs;fp=vendor%2Fdirs%2Fsrc%2Flib.rs;h=96f66a818c98c9badc0ad0f3109562240f396a97;hb=f20569fa03b3b370f70f0df777c134d7f38d09e9;hp=0000000000000000000000000000000000000000;hpb=36d6ef2b3b6819c441d79135fddfee590bb92ee1;p=rustc.git diff --git a/vendor/dirs/src/lib.rs b/vendor/dirs/src/lib.rs new file mode 100644 index 0000000000..96f66a818c --- /dev/null +++ b/vendor/dirs/src/lib.rs @@ -0,0 +1,272 @@ +//! The _dirs_ crate is +//! +//! - a tiny library with a minimal API (16 functions) +//! - that provides the platform-specific, user-accessible locations +//! - for finding and storing configuration, cache and other data +//! - on Linux, Redox, Windows (≥ Vista) and macOS. +//! +//! The library provides the location of these directories by leveraging the mechanisms defined by +//! +//! - 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, +//! - the [Known Folder](https://msdn.microsoft.com/en-us/library/windows/desktop/bb776911(v=vs.85).aspx) system on Windows, and +//! - 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. + +#![deny(missing_docs)] + +#[macro_use] +extern crate cfg_if; + +use std::path::PathBuf; + +cfg_if! { + if #[cfg(target_os = "windows")] { + mod win; + use win as sys; + } else if #[cfg(any(target_os = "macos", target_os = "ios"))] { + mod mac; + use mac as sys; + } else if #[cfg(target_arch = "wasm32")] { + mod wasm; + use wasm as sys; + } else { + mod lin; + use lin as sys; + } +} + +/// Returns the path to the user's home directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | -------------------- | -------------- | +/// | Linux | `$HOME` | /home/alice | +/// | macOS | `$HOME` | /Users/Alice | +/// | Windows | `{FOLDERID_Profile}` | C:\Users\Alice | +/// +/// ### Linux and macOS: +/// +/// - Use `$HOME` if it is set and not empty. +/// - If `$HOME` is not set or empty, then the function `getpwuid_r` is used to determine +/// the home directory of the current user. +/// - If `getpwuid_r` lacks an entry for the current user id or the home directory field is empty, +/// then the function returns `None`. +/// +/// ### Windows: +/// +/// This function retrieves the user profile folder using `SHGetKnownFolderPath`. +/// +/// All the examples on this page mentioning `$HOME` use this behavior. +/// +/// _Note:_ This function's behavior differs from [`std::env::home_dir`], +/// which works incorrectly on Linux, macOS and Windows. +/// +/// [`std::env::home_dir`]: https://doc.rust-lang.org/std/env/fn.home_dir.html +pub fn home_dir() -> Option { + sys::home_dir() +} +/// Returns the path to the user's cache directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | ----------------------------------- | ---------------------------- | +/// | Linux | `$XDG_CACHE_HOME` or `$HOME`/.cache | /home/alice/.cache | +/// | macOS | `$HOME`/Library/Caches | /Users/Alice/Library/Caches | +/// | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local | +pub fn cache_dir() -> Option { + sys::cache_dir() +} +/// Returns the path to the user's config directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | ------------------------------------- | -------------------------------- | +/// | Linux | `$XDG_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config | +/// | macOS | `$HOME`/Library/Preferences | /Users/Alice/Library/Preferences | +/// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming | +pub fn config_dir() -> Option { + sys::config_dir() +} +/// Returns the path to the user's data directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | ---------------------------------------- | ---------------------------------------- | +/// | Linux | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share | +/// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support | +/// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming | +pub fn data_dir() -> Option { + sys::data_dir() +} +/// Returns the path to the user's local data directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | ---------------------------------------- | ---------------------------------------- | +/// | Linux | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share | +/// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support | +/// | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local | +pub fn data_local_dir() -> Option { + sys::data_local_dir() +} +/// Returns the path to the user's executable directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | ---------------------------------------------------------------- | ---------------------- | +/// | Linux | `$XDG_BIN_HOME` or `$XDG_DATA_HOME`/../bin or `$HOME`/.local/bin | /home/alice/.local/bin | +/// | macOS | – | – | +/// | Windows | – | – | +pub fn executable_dir() -> Option { + sys::executable_dir() +} +/// Returns the path to the user's runtime directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | ------------------ | --------------- | +/// | Linux | `$XDG_RUNTIME_DIR` | /run/user/1001/ | +/// | macOS | – | – | +/// | Windows | – | – | +pub fn runtime_dir() -> Option { + sys::runtime_dir() +} + +/// Returns the path to the user's audio directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | ------------------ | -------------------- | +/// | Linux | `XDG_MUSIC_DIR` | /home/alice/Music | +/// | macOS | `$HOME`/Music | /Users/Alice/Music | +/// | Windows | `{FOLDERID_Music}` | C:\Users\Alice\Music | +pub fn audio_dir() -> Option { + sys::audio_dir() +} +/// Returns the path to the user's desktop directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | -------------------- | ---------------------- | +/// | Linux | `XDG_DESKTOP_DIR` | /home/alice/Desktop | +/// | macOS | `$HOME`/Desktop | /Users/Alice/Desktop | +/// | Windows | `{FOLDERID_Desktop}` | C:\Users\Alice\Desktop | +pub fn desktop_dir() -> Option { + sys::desktop_dir() +} +/// Returns the path to the user's document directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | ---------------------- | ------------------------ | +/// | Linux | `XDG_DOCUMENTS_DIR` | /home/alice/Documents | +/// | macOS | `$HOME`/Documents | /Users/Alice/Documents | +/// | Windows | `{FOLDERID_Documents}` | C:\Users\Alice\Documents | +pub fn document_dir() -> Option { + sys::document_dir() +} +/// Returns the path to the user's download directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | ---------------------- | ------------------------ | +/// | Linux | `XDG_DOWNLOAD_DIR` | /home/alice/Downloads | +/// | macOS | `$HOME`/Downloads | /Users/Alice/Downloads | +/// | Windows | `{FOLDERID_Downloads}` | C:\Users\Alice\Downloads | +pub fn download_dir() -> Option { + sys::download_dir() +} +/// Returns the path to the user's font directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | ---------------------------------------------------- | ------------------------------ | +/// | Linux | `$XDG_DATA_HOME`/fonts or `$HOME`/.local/share/fonts | /home/alice/.local/share/fonts | +/// | macOS | `$HOME/Library/Fonts` | /Users/Alice/Library/Fonts | +/// | Windows | – | – | +pub fn font_dir() -> Option { + sys::font_dir() +} +/// Returns the path to the user's picture directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | --------------------- | ----------------------- | +/// | Linux | `XDG_PICTURES_DIR` | /home/alice/Pictures | +/// | macOS | `$HOME`/Pictures | /Users/Alice/Pictures | +/// | Windows | `{FOLDERID_Pictures}` | C:\Users\Alice\Pictures | +pub fn picture_dir() -> Option { + sys::picture_dir() +} +/// Returns the path to the user's public directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | --------------------- | ------------------- | +/// | Linux | `XDG_PUBLICSHARE_DIR` | /home/alice/Public | +/// | macOS | `$HOME`/Public | /Users/Alice/Public | +/// | Windows | `{FOLDERID_Public}` | C:\Users\Public | +pub fn public_dir() -> Option { + sys::public_dir() +} +/// Returns the path to the user's template directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | ---------------------- | ---------------------------------------------------------- | +/// | Linux | `XDG_TEMPLATES_DIR` | /home/alice/Templates | +/// | macOS | – | – | +/// | Windows | `{FOLDERID_Templates}` | C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Templates | +pub fn template_dir() -> Option { + sys::template_dir() +} + +/// Returns the path to the user's video directory. +/// +/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`. +/// +/// |Platform | Value | Example | +/// | ------- | ------------------- | --------------------- | +/// | Linux | `XDG_VIDEOS_DIR` | /home/alice/Videos | +/// | macOS | `$HOME`/Movies | /Users/Alice/Movies | +/// | Windows | `{FOLDERID_Videos}` | C:\Users\Alice\Videos | +pub fn video_dir() -> Option { + sys::video_dir() +} + +#[cfg(test)] +mod tests { + #[test] + fn test_dirs() { + println!("home_dir: {:?}", ::home_dir()); + println!("cache_dir: {:?}", ::cache_dir()); + println!("config_dir: {:?}", ::config_dir()); + println!("data_dir: {:?}", ::data_dir()); + println!("data_local_dir: {:?}", ::data_local_dir()); + println!("executable_dir: {:?}", ::executable_dir()); + println!("runtime_dir: {:?}", ::runtime_dir()); + println!("audio_dir: {:?}", ::audio_dir()); + println!("home_dir: {:?}", ::desktop_dir()); + println!("cache_dir: {:?}", ::document_dir()); + println!("config_dir: {:?}", ::download_dir()); + println!("font_dir: {:?}", ::font_dir()); + println!("picture_dir: {:?}", ::picture_dir()); + println!("public_dir: {:?}", ::public_dir()); + println!("template_dir: {:?}", ::template_dir()); + println!("video_dir: {:?}", ::video_dir()); + } +}