diff --git a/Cargo.toml b/Cargo.toml index f3f31e8..4084026 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "dirs" -version = "2.0.2" +version = "3.0.0" authors = ["Simon Ochsenreither "] description = "A tiny low-level library that provides platform-specific standard locations of directories for config, cache and other data on Linux, Windows, macOS and Redox by leveraging the mechanisms defined by the XDG base/user directory specifications on Linux, the Known Folder API on Windows, and the Standard Directory guidelines on macOS." readme = "README.md" @@ -11,4 +11,4 @@ keywords = ["xdg", "basedir", "app_dirs", "path", "folder"] [dependencies] cfg-if = "=0.1.9" -dirs-sys = "0.3.4" +dirs-sys = "0.3.5" diff --git a/README.md b/README.md index e08194a..5acfca1 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ [![crates.io](https://img.shields.io/crates/v/dirs.svg)](https://crates.io/crates/dirs) [![API documentation](https://docs.rs/dirs/badge.svg)](https://docs.rs/dirs/) ![actively developed](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg) -[![TravisCI status](https://img.shields.io/travis/soc/dirs-rs/master.svg?label=Linux/macOS%20build)](https://travis-ci.org/soc/dirs-rs) +[![TravisCI status](https://img.shields.io/travis/dirs-dev/dirs-rs/master.svg?label=Linux/macOS%20build)](https://travis-ci.org/dirs-dev/dirs-rs) [![AppVeyor status](https://img.shields.io/appveyor/ci/soc/dirs-rs/master.svg?label=Windows%20build)](https://ci.appveyor.com/project/soc/dirs-rs/branch/master) ![License: MIT/Apache-2.0](https://img.shields.io/badge/license-MIT%2FApache--2.0-orange.svg) @@ -28,8 +28,8 @@ Other platforms are also supported; they use the Linux conventions. The minimal required version of Rust is 1.13. -It's mid-level sister library, _directories_, is available for Rust ([directories-rs](https://github.com/soc/directories-rs)) -and on the JVM ([directories-jvm](https://github.com/soc/directories-jvm)). +It's mid-level sister library, _directories_, is available for Rust ([directories-rs](https://github.com/dirs-dev/directories-rs)) +and on the JVM ([directories-jvm](https://github.com/dirs-dev/directories-jvm)). ## Usage @@ -38,11 +38,13 @@ and on the JVM ([directories-jvm](https://github.com/soc/directories-jvm)). Add the library as a dependency to your project by inserting ```toml -dirs = "2.0" +dirs = "3.0" ``` into the `[dependencies]` section of your Cargo.toml file. +If you are upgrading from version 2, please read the [section on breaking changes](#3) first. + #### Example Library run by user Alice: @@ -63,7 +65,7 @@ dirs::audio_dir(); dirs::config_dir(); // Lin: Some(/home/alice/.config) // Win: Some(C:\Users\Alice\AppData\Roaming) -// Mac: Some(/Users/Alice/Library/Preferences) +// Mac: Some(/Users/Alice/Library/Application Support) dirs::executable_dir(); // Lin: Some(/home/alice/.local/bin) @@ -74,16 +76,18 @@ dirs::executable_dir(); ## Design Goals - The _dirs_ library is a low-level crate designed to provide the paths to standard directories - as defined by operating systems rules or conventions. If your requirements are more complex, - e. g. computing cache, config, etc. paths for specific applications or projects, consider using - [directories](https://github.com/soc/directories-rs) instead. + as defined by operating systems rules or conventions.
+ If your requirements are more complex, e. g. computing cache, config, etc. paths for specific + applications or projects, consider using [directories](https://github.com/dirs-dev/directories-rs) + instead. - This library does not create directories or check for their existence. The library only provides - information on what the path to a certain directory _should_ be. How this information is used is - a decision that developers need to make based on the requirements of each individual application. -- This library is intentionally focused on providing information on user-writable directories only. - There is no discernible benefit in returning a path that points to a user-level, writable - directory on one operating system, but a system-level, read-only directory on another, that would - outweigh the confusion and unexpected failures such an approach would cause. + information on what the path to a certain directory _should_ be.
+ How this information is used is a decision that developers need to make based on the requirements + of each individual application. +- This library is intentionally focused on providing information on user-writable directories only, + as there is no discernible benefit in returning a path that points to a user-level, writable + directory on one operating system, but a system-level, read-only directory on another.
+ The confusion and unexpected failure modes of such an approach would be immense. - `executable_dir` is specified to provide the path to a user-writable directory for binaries.
As such a directory only commonly exists on Linux, it returns `None` on macOS and Windows. - `font_dir` is specified to provide the path to a user-writable directory for fonts.
@@ -97,16 +101,17 @@ dirs::executable_dir(); ## Features **If you want to compute the location of cache, config or data directories for your own application or project, -use `ProjectDirs` of the [directories](https://github.com/soc/directories-rs) project instead.** +use `ProjectDirs` of the [directories](https://github.com/dirs-dev/directories-rs) 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`)` | +| `config_dir` | `Some($XDG_CONFIG_HOME)` or `Some($HOME`/.config`)` | `Some({FOLDERID_RoamingAppData})` | `Some($HOME`/Library/Application Support`)` | | `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` | +| `preference_dir` | `Some($XDG_CONFIG_HOME)` or `Some($HOME`/.config`)` | `Some({FOLDERID_RoamingAppData})` | `Some($HOME`/Library/Preferences`)` | | `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/`)` | @@ -141,9 +146,9 @@ Please take this table with a grain of salt: a different crate might very well b - Lin: Linux support - Mac: macOS support - Win: Windows support -- Base: Supports [generic base directories](https://github.com/soc/directories-rs#basedirs) -- User: Supports [user directories](https://github.com/soc/directories-rs#userdirs) -- Proj: Supports [project-specific base directories](https://github.com/soc/directories-rs#projectdirs) +- Base: Supports [generic base directories](https://github.com/dirs-dev/directories-rs#basedirs) +- User: Supports [user directories](https://github.com/dirs-dev/directories-rs#userdirs) +- Proj: Supports [project-specific base directories](https://github.com/dirs-dev/directories-rs#projectdirs) - Conv: Follows naming conventions of the operating system it runs on ## Build @@ -162,6 +167,22 @@ cargo build --target=x86_64-unknown-redox ## Changelog +### 3 + +- **BREAKING CHANGE** The behavior of `config_dir` on macOS has been adjusted + (thanks to [everyone involved](https://github.com/dirs-dev/directories-rs/issues/62)): + - The existing `config_dir` function has been changed to return the `Application Support` + directory on macOS, as suggested by Apple documentation. + - The behavior of the `config_dir` function on non-macOS platforms has not been changed. + - If you have used the `config_dir` function to store files, it may be necessary to write code + that migrates the files to the new location on macOS.
+ (Alternative: change uses of the `config_dir` function to uses of the `preference_dir` function + to retain the old behavior.) +- The newly added `preference_dir` function returns the `Preferences` directory on macOS now, + which – according to Apple documentation – shall only be used to store .plist files using + Apple-proprietary APIs. + – `preference_dir` and `config_dir` behave identical on non-macOS platforms. + ### 2 The behavior of deactivated, missing or invalid [_XDG User Dirs_](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/) diff --git a/src/lib.rs b/src/lib.rs index 96f66a8..669f73d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -81,11 +81,11 @@ pub fn cache_dir() -> Option { /// /// 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 | +/// |Platform | Value | Example | +/// | ------- | ------------------------------------- | ---------------------------------------- | +/// | Linux | `$XDG_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config | +/// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support | +/// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming | pub fn config_dir() -> Option { sys::config_dir() } @@ -125,6 +125,18 @@ pub fn data_local_dir() -> Option { pub fn executable_dir() -> Option { sys::executable_dir() } +/// Returns the path to the user's preference 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 preference_dir() -> Option { + sys::preference_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`. @@ -258,6 +270,7 @@ mod tests { println!("data_dir: {:?}", ::data_dir()); println!("data_local_dir: {:?}", ::data_local_dir()); println!("executable_dir: {:?}", ::executable_dir()); + println!("preference_dir: {:?}", ::preference_dir()); println!("runtime_dir: {:?}", ::runtime_dir()); println!("audio_dir: {:?}", ::audio_dir()); println!("home_dir: {:?}", ::desktop_dir()); diff --git a/src/lin.rs b/src/lin.rs index 74ac610..1025bc7 100644 --- a/src/lin.rs +++ b/src/lin.rs @@ -7,7 +7,8 @@ pub fn home_dir() -> Option { dirs_sys::home_dir() } pub fn cache_dir() -> Option { env::var_os("XDG_CACHE_HOME") .and_then(dirs_sys::is_absolute_path).or_else(|| home_dir().map(|h| h.join(".cache"))) } pub fn config_dir() -> Option { env::var_os("XDG_CONFIG_HOME").and_then(dirs_sys::is_absolute_path).or_else(|| home_dir().map(|h| h.join(".config"))) } pub fn data_dir() -> Option { env::var_os("XDG_DATA_HOME") .and_then(dirs_sys::is_absolute_path).or_else(|| home_dir().map(|h| h.join(".local/share"))) } -pub fn data_local_dir() -> Option { data_dir().clone() } +pub fn data_local_dir() -> Option { data_dir() } +pub fn preference_dir() -> Option { config_dir() } pub fn runtime_dir() -> Option { env::var_os("XDG_RUNTIME_DIR").and_then(dirs_sys::is_absolute_path) } pub fn executable_dir() -> Option { env::var_os("XDG_BIN_HOME").and_then(dirs_sys::is_absolute_path).or_else(|| { diff --git a/src/mac.rs b/src/mac.rs index ae7f9c9..113b1f9 100644 --- a/src/mac.rs +++ b/src/mac.rs @@ -4,9 +4,10 @@ use std::path::PathBuf; pub fn home_dir() -> Option { dirs_sys::home_dir() } pub fn cache_dir() -> Option { home_dir().map(|h| h.join("Library/Caches")) } -pub fn config_dir() -> Option { home_dir().map(|h| h.join("Library/Preferences")) } +pub fn config_dir() -> Option { home_dir().map(|h| h.join("Library/Application Support")) } pub fn data_dir() -> Option { home_dir().map(|h| h.join("Library/Application Support")) } pub fn data_local_dir() -> Option { data_dir() } +pub fn preference_dir() -> Option { home_dir().map(|h| h.join("Library/Preferences")) } pub fn executable_dir() -> Option { None } pub fn runtime_dir() -> Option { None } pub fn audio_dir() -> Option { home_dir().map(|h| h.join("Music")) } diff --git a/src/wasm.rs b/src/wasm.rs index 2ead720..89c26b2 100644 --- a/src/wasm.rs +++ b/src/wasm.rs @@ -7,6 +7,7 @@ pub fn cache_dir() -> Option { None } pub fn config_dir() -> Option { None } pub fn data_dir() -> Option { None } pub fn data_local_dir() -> Option { None } +pub fn preference_dir() -> Option { None } pub fn runtime_dir() -> Option { None } pub fn executable_dir() -> Option { None } pub fn audio_dir() -> Option { None } diff --git a/src/win.rs b/src/win.rs index a62e95b..c39097a 100644 --- a/src/win.rs +++ b/src/win.rs @@ -8,6 +8,7 @@ pub fn data_local_dir() -> Option { dirs_sys::known_folder_local_app_da pub fn cache_dir() -> Option { data_local_dir() } pub fn config_dir() -> Option { data_dir() } pub fn executable_dir() -> Option { None } +pub fn preference_dir() -> Option { data_dir() } pub fn runtime_dir() -> Option { None } pub fn audio_dir() -> Option { dirs_sys::known_folder_music() } pub fn desktop_dir() -> Option { dirs_sys::known_folder_desktop() }