Release version 3.0.0 – BREAKING CHANGE: configDir on macOS

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name        = "dirs"
-version     = "2.0.2"
+version     = "3.0.0"
 authors     = ["Simon Ochsenreither <simon@ochsenreither.de>"]
 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"

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.<br/>
+  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.<br/>
+  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.<br/>
+  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.<br/>
     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.<br/>
@@ -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.<br/>
+    (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/)

src/lib.rs

@@ -81,11 +81,11 @@ pub fn cache_dir() -> Option<PathBuf> {
 ///
 /// 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<PathBuf> {
     sys::config_dir()
 }
@@ -125,6 +125,18 @@ pub fn data_local_dir() -> Option<PathBuf> {
 pub fn executable_dir() -> Option<PathBuf> {
     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<PathBuf> {
+    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());

src/lin.rs

@@ -7,7 +7,8 @@ pub fn home_dir()       -> Option<PathBuf> { dirs_sys::home_dir() }
 pub fn cache_dir()      -> Option<PathBuf> { 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<PathBuf> { 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<PathBuf> { 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<PathBuf> { data_dir().clone() }
+pub fn data_local_dir() -> Option<PathBuf> { data_dir() }
+pub fn preference_dir() -> Option<PathBuf> { config_dir() }
 pub fn runtime_dir()    -> Option<PathBuf> { env::var_os("XDG_RUNTIME_DIR").and_then(dirs_sys::is_absolute_path) }
 pub fn executable_dir() -> Option<PathBuf> {
     env::var_os("XDG_BIN_HOME").and_then(dirs_sys::is_absolute_path).or_else(|| {

src/mac.rs

@@ -4,9 +4,10 @@ use std::path::PathBuf;
 
 pub fn home_dir()       -> Option<PathBuf> { dirs_sys::home_dir() }
 pub fn cache_dir()      -> Option<PathBuf> { home_dir().map(|h| h.join("Library/Caches")) }
-pub fn config_dir()     -> Option<PathBuf> { home_dir().map(|h| h.join("Library/Preferences")) }
+pub fn config_dir()     -> Option<PathBuf> { home_dir().map(|h| h.join("Library/Application Support")) }
 pub fn data_dir()       -> Option<PathBuf> { home_dir().map(|h| h.join("Library/Application Support")) }
 pub fn data_local_dir() -> Option<PathBuf> { data_dir() }
+pub fn preference_dir() -> Option<PathBuf> { home_dir().map(|h| h.join("Library/Preferences")) }
 pub fn executable_dir() -> Option<PathBuf> { None }
 pub fn runtime_dir()    -> Option<PathBuf> { None }
 pub fn audio_dir()      -> Option<PathBuf> { home_dir().map(|h| h.join("Music")) }

src/wasm.rs

@@ -7,6 +7,7 @@ pub fn cache_dir()      -> Option<PathBuf> { None }
 pub fn config_dir()     -> Option<PathBuf> { None }
 pub fn data_dir()       -> Option<PathBuf> { None }
 pub fn data_local_dir() -> Option<PathBuf> { None }
+pub fn preference_dir() -> Option<PathBuf> { None }
 pub fn runtime_dir()    -> Option<PathBuf> { None }
 pub fn executable_dir() -> Option<PathBuf> { None }
 pub fn audio_dir()      -> Option<PathBuf> { None }

src/win.rs

@@ -8,6 +8,7 @@ pub fn data_local_dir() -> Option<PathBuf> { dirs_sys::known_folder_local_app_da
 pub fn cache_dir()      -> Option<PathBuf> { data_local_dir() }
 pub fn config_dir()     -> Option<PathBuf> { data_dir() }
 pub fn executable_dir() -> Option<PathBuf> { None }
+pub fn preference_dir() -> Option<PathBuf> { data_dir() }
 pub fn runtime_dir()    -> Option<PathBuf> { None }
 pub fn audio_dir()      -> Option<PathBuf> { dirs_sys::known_folder_music() }
 pub fn desktop_dir()    -> Option<PathBuf> { dirs_sys::known_folder_desktop() }