Release version 3.0.0 – BREAKING CHANGE: configDir on macOS

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name        = "directories"
-version     = "2.0.2"
+version     = "3.0.0"
 authors     = ["Simon Ochsenreither <[email protected]>"]
 description = "A tiny mid-level library that provides platform-specific standard locations of directories for config, cache and other data on Linux, Windows and macOS 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,7 +11,7 @@ keywords    = ["xdg", "basedir", "app_dirs", "path", "folder"]
 
 [dependencies]
 cfg-if = "=0.1.9"
-dirs-sys = "0.3.4"
+dirs-sys = "0.3.5"
 
 [dev-dependencies]
 bencher = "0.1.5"

README.md

@@ -1,7 +1,7 @@
 [![crates.io](https://img.shields.io/crates/v/directories.svg)](https://crates.io/crates/directories)
 [![API documentation](https://docs.rs/directories/badge.svg)](https://docs.rs/directories/)
 ![actively developed](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg)
-[![TravisCI status](https://img.shields.io/travis/soc/directories-rs/master.svg?label=Linux/macOS%20build)](https://travis-ci.org/soc/directories-rs)
+[![TravisCI status](https://img.shields.io/travis/dirs-dev/directories-rs/master.svg?label=Linux/macOS%20build)](https://travis-ci.org/dirs-dev/directories-rs)
 [![AppVeyor status](https://img.shields.io/appveyor/ci/soc/directories-rs/master.svg?label=Windows%20build)](https://ci.appveyor.com/project/soc/directories-rs/branch/master)
 ![License: MIT/Apache-2.0](https://img.shields.io/badge/license-MIT%2FApache--2.0-orange.svg)
 
@@ -37,11 +37,13 @@ A version of this library running on the JVM is provided by [directories-jvm](ht
 Add the library as a dependency to your project by inserting
 
 ```toml
-directories = "2.0"
+directories = "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:
@@ -54,7 +56,7 @@ if let Some(proj_dirs) = ProjectDirs::from("com", "Foo Corp",  "Bar App") {
     proj_dirs.config_dir();
     // Lin: /home/alice/.config/barapp
     // Win: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config
-    // Mac: /Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App
+    // Mac: /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
 }
 
 if let Some(base_dirs) = BaseDirs::new() {
@@ -75,15 +77,16 @@ if let Some(user_dirs) = UserDirs::new() {
 ## Design Goals
 
 - The _directories_ library is designed to provide an accurate snapshot of the system's state at
-  the point of invocation of `BaseDirs::new`, `UserDirs::new` or `ProjectDirs::from`. Subsequent
-  changes to the state of the system are not reflected in values created prior to such a change.
+  the point of invocation of `BaseDirs::new`, `UserDirs::new` or `ProjectDirs::from`.<br/>
+  Subsequent changes to the state of the system are not reflected in values created prior to such a change.
 - 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/>
@@ -107,10 +110,11 @@ If you want to compute the location of cache, config or data directories for you
 | ---------------- | ----------------------------------------------------------------------------------------------- | --------------------------- | ----------------------------------- |
 | `home_dir`       | `$HOME`                                                                                         | `{FOLDERID_Profile}`        | `$HOME`                             |
 | `cache_dir`      | `$XDG_CACHE_HOME`              or `$HOME`/.cache                                                | `{FOLDERID_LocalAppData}`   | `$HOME`/Library/Caches              |
-| `config_dir`     | `$XDG_CONFIG_HOME`             or `$HOME`/.config                                               | `{FOLDERID_RoamingAppData}` | `$HOME`/Library/Preferences         |
+| `config_dir`     | `$XDG_CONFIG_HOME`             or `$HOME`/.config                                               | `{FOLDERID_RoamingAppData}` | `$HOME`/Library/Application Support |
 | `data_dir`       | `$XDG_DATA_HOME`               or `$HOME`/.local/share                                          | `{FOLDERID_RoamingAppData}` | `$HOME`/Library/Application Support |
 | `data_local_dir` | `$XDG_DATA_HOME`               or `$HOME`/.local/share                                          | `{FOLDERID_LocalAppData}`   | `$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` | `$XDG_CONFIG_HOME`             or `$HOME`/.config                                               | `{FOLDERID_RoamingAppData}` | `$HOME`/Library/Preferences         |
 | `runtime_dir`    | `Some($XDG_RUNTIME_DIR)`       or `None`                                                        | `None`                      | `None`                              |
 
 ### `UserDirs`
@@ -139,9 +143,10 @@ which are derived from the standard directories.
 | Function name    | Value on Linux                                                                     | Value on Windows                                    | Value on macOS                                       |
 | ---------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------- |
 | `cache_dir`      | `$XDG_CACHE_HOME`/`<project_path>`        or `$HOME`/.cache/`<project_path>`       | `{FOLDERID_LocalAppData}`/`<project_path>`/cache    | `$HOME`/Library/Caches/`<project_path>`              |
-| `config_dir`     | `$XDG_CONFIG_HOME`/`<project_path>`       or `$HOME`/.config/`<project_path>`      | `{FOLDERID_RoamingAppData}`/`<project_path>`/config | `$HOME`/Library/Preferences/`<project_path>`         |
+| `config_dir`     | `$XDG_CONFIG_HOME`/`<project_path>`       or `$HOME`/.config/`<project_path>`      | `{FOLDERID_RoamingAppData}`/`<project_path>`/config | `$HOME`/Library/Application Support/`<project_path>` |
 | `data_dir`       | `$XDG_DATA_HOME`/`<project_path>`         or `$HOME`/.local/share/`<project_path>` | `{FOLDERID_RoamingAppData}`/`<project_path>`/data   | `$HOME`/Library/Application Support/`<project_path>` |
 | `data_local_dir` | `$XDG_DATA_HOME`/`<project_path>`         or `$HOME`/.local/share/`<project_path>` | `{FOLDERID_LocalAppData}`/`<project_path>`/data     | `$HOME`/Library/Application Support/`<project_path>` |
+| `preference_dir` | `$XDG_CONFIG_HOME`/`<project_path>`       or `$HOME`/.config/`<project_path>`      | `{FOLDERID_RoamingAppData}`/`<project_path>`/config | `$HOME`/Library/Preferences/`<project_path>`         |
 | `runtime_dir`    | `Some($XDG_RUNTIME_DIR`/`_project_path_)`                                          | `None`                                              | `None`                                               |
 
 The specific value of `<project_path>` is computed by the
@@ -164,6 +169,7 @@ results in the following values:
 
 The `ProjectDirs::from_path` function allows the creation of `ProjectDirs` structs directly from a `PathBuf` value.
 This argument is used verbatim and is not adapted to operating system standards.
+
 The use of `ProjectDirs::from_path` is strongly discouraged, as its results will not follow operating system standards on at least two of three platforms.
 
 ## Comparison
@@ -210,6 +216,22 @@ cargo build --target=x86_64-unknown-redox
 
 ## Changelog
 
+### 3
+
+- **BREAKING CHANGE** The behavior of the `BaseDirs::config_dir` and `ProjectDirs::config_dir`
+    on macOS has been adjusted (thanks to [everyone involved](https://github.com/dirs-dev/directories-rs/issues/62)):
+  - The existing `config_dir` functions have been changed to return the `Application Support`
+    directory on macOS, as suggested by Apple documentation.
+  - The behavior of the `config_dir` functions on non-macOS platforms has not been changed.
+  - If you have used the `config_dir` functions 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` functions to uses of the `preference_dir` functions
+    to retain the old behavior.)
+- The newly added `BaseDirs::preference_dir` and `ProjectDirs::preference_dir` functions 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

@@ -50,7 +50,7 @@ cfg_if! {
 ///     base_dirs.config_dir();
 ///     // Linux:   /home/alice/.config
 ///     // Windows: C:\Users\Alice\AppData\Roaming
-///     // macOS:   /Users/Alice/Library/Preferences
+///     // macOS:   /Users/Alice/Library/Application Support
 /// }
 /// ```
 #[derive(Debug, Clone)]
@@ -64,6 +64,7 @@ pub struct BaseDirs {
     data_dir:       PathBuf,
     data_local_dir: PathBuf,
     executable_dir: Option<PathBuf>,
+    preference_dir: PathBuf,
     runtime_dir:    Option<PathBuf>,
 }
 
@@ -114,7 +115,7 @@ pub struct UserDirs {
 ///     proj_dirs.config_dir();
 ///     // Linux:   /home/alice/.config/barapp
 ///     // Windows: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App
-///     // macOS:   /Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App
+///     // macOS:   /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
 /// }
 /// ```
 #[derive(Debug, Clone)]
@@ -126,6 +127,7 @@ pub struct ProjectDirs {
     config_dir:     PathBuf,
     data_dir:       PathBuf,
     data_local_dir: PathBuf,
+    preference_dir: PathBuf,
     runtime_dir:    Option<PathBuf>
 }
 
@@ -180,11 +182,11 @@ impl BaseDirs {
     }
     /// Returns the path to the user's config directory.
     ///
-    /// |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(&self) -> &Path {
         self.config_dir.as_path()
     }
@@ -218,6 +220,16 @@ impl BaseDirs {
     pub fn executable_dir(&self) -> Option<&Path> {
         self.executable_dir.as_ref().map(|p| p.as_path())
     }
+    /// Returns the path to the user's preference directory.
+    ///
+    /// |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(&self) -> &Path {
+        self.preference_dir.as_path()
+    }
     /// Returns the path to the user's runtime directory.
     ///
     /// |Platform | Value              | Example         |
@@ -397,11 +409,11 @@ impl ProjectDirs {
     }
     /// Returns the path to the project's config directory.
     ///
-    /// |Platform | Value                                                                   | Example                                                |
-    /// | ------- | ----------------------------------------------------------------------- | ------------------------------------------------------ |
-    /// | Linux   | `$XDG_CONFIG_HOME`/`_project_path_` or `$HOME`/.config/`_project_path_` | /home/alice/.config/barapp                             |
-    /// | macOS   | `$HOME`/Library/Preferences/`_project_path_`                            | /Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App  |
-    /// | Windows | `{FOLDERID_RoamingAppData}`\\`_project_path_`\\config                   | C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config |
+    /// |Platform | Value                                                                   | Example                                                        |
+    /// | ------- | ----------------------------------------------------------------------- | -------------------------------------------------------------- |
+    /// | Linux   | `$XDG_CONFIG_HOME`/`_project_path_` or `$HOME`/.config/`_project_path_` | /home/alice/.config/barapp                                     |
+    /// | macOS   | `$HOME`/Library/Application Support/`_project_path_`                    | /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App  |
+    /// | Windows | `{FOLDERID_RoamingAppData}`\\`_project_path_`\\config                   | C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config         |
     pub fn config_dir(&self) -> &Path {
         self.config_dir.as_path()
     }
@@ -425,6 +437,16 @@ impl ProjectDirs {
     pub fn data_local_dir(&self) -> &Path {
         self.data_local_dir.as_path()
     }
+    /// Returns the path to the project's preference directory.
+    ///
+    /// |Platform | Value                                                                   | Example                                                |
+    /// | ------- | ----------------------------------------------------------------------- | ------------------------------------------------------ |
+    /// | Linux   | `$XDG_CONFIG_HOME`/`_project_path_` or `$HOME`/.config/`_project_path_` | /home/alice/.config/barapp                             |
+    /// | macOS   | `$HOME`/Library/Preferences/`_project_path_`                            | /Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App  |
+    /// | Windows | `{FOLDERID_RoamingAppData}`\\`_project_path_`\\config                   | C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config |
+    pub fn preference_dir(&self) -> &Path {
+        self.preference_dir.as_path()
+    }
     /// Returns the path to the project's runtime directory.
     ///
     /// |Platform | Value                               | Example               |

src/lin.rs

@@ -13,8 +13,9 @@ pub fn base_dirs() -> Option<BaseDirs> {
         let config_dir     = env::var_os("XDG_CONFIG_HOME").and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".config"));
         let data_dir       = env::var_os("XDG_DATA_HOME")  .and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".local/share"));
         let data_local_dir = data_dir.clone();
+        let preference_dir = config_dir.clone();
         let runtime_dir    = env::var_os("XDG_RUNTIME_DIR").and_then(dirs_sys::is_absolute_path);
-        let executable_dir = 
+        let executable_dir =
             env::var_os("XDG_BIN_HOME").and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| {
                 let mut new_dir = data_dir.clone(); new_dir.pop(); new_dir.push("bin"); new_dir });
 
@@ -25,6 +26,7 @@ pub fn base_dirs() -> Option<BaseDirs> {
             data_dir:       data_dir,
             data_local_dir: data_local_dir,
             executable_dir: Some(executable_dir),
+            preference_dir: preference_dir,
             runtime_dir:    runtime_dir
         };
         Some(base_dirs)
@@ -63,6 +65,7 @@ pub fn project_dirs_from_path(project_path: PathBuf) -> Option<ProjectDirs> {
         let config_dir     = env::var_os("XDG_CONFIG_HOME").and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".config")).join(&project_path);
         let data_dir       = env::var_os("XDG_DATA_HOME")  .and_then(dirs_sys::is_absolute_path).unwrap_or_else(|| home_dir.join(".local/share")).join(&project_path);
         let data_local_dir = data_dir.clone();
+        let preference_dir = config_dir.clone();
         let runtime_dir    = env::var_os("XDG_RUNTIME_DIR").and_then(dirs_sys::is_absolute_path).map(|o| o.join(&project_path));
 
         let project_dirs = ProjectDirs {
@@ -71,6 +74,7 @@ pub fn project_dirs_from_path(project_path: PathBuf) -> Option<ProjectDirs> {
             config_dir:     config_dir,
             data_dir:       data_dir,
             data_local_dir: data_local_dir,
+            preference_dir: preference_dir,
             runtime_dir:    runtime_dir
         };
         Some(project_dirs)