Skip to content
This repository was archived by the owner on Feb 18, 2025. It is now read-only.

Commit 0ec6dad

Browse files
socsoc
committed
BREAKING CHANGES: Migrate from io.github.soc to dev.dirs, ...
... change behavior of `configDir` on macOS, release version 20.
1 parent 1df8219 commit 0ec6dad

File tree

10 files changed

+218
-123
lines changed

10 files changed

+218
-123
lines changed

‎README.md‎

Lines changed: 51 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
[![Maven Central](https://img.shields.io/maven-central/v/io.github.soc/directories.svg)](https://search.maven.org/#search|gav|1|g%3A%22io.github.soc%22%20AND%20a%3A%22directories%22)
2-
[![API documentation](http://javadoc.io/badge/io.github.soc/directories.svg)](http://javadoc.io/doc/io.github.soc/directories)
3-
![actively developed](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg)
1+
[![Maven Central](https://img.shields.io/maven-central/v/dev.dirs/directories.svg)](https://search.maven.org/#search|gav|1|g%3A%22dev.dirs%22%20AND%20a%3A%22directories%22)
2+
[![API documentation](http://javadoc.io/badge/dev.dirs/directories.svg)](http://javadoc.io/doc/dev.dirs/directories)
3+
![actively developed](https://img.shields.io/badge/maintenance-actively_developed-brightgreen.svg)
44
[![TravisCI status](https://img.shields.io/travis/dirs-dev/directories-jvm/master.svg?label=Linux%20build)](https://travis-ci.org/dirs-dev/directories-jvm)
55
[![AppVeyor status](https://img.shields.io/appveyor/ci/soc/directories-jvm/master.svg?label=Windows%20build)](https://ci.appveyor.com/project/soc/directories-jvm/branch/master)
66
[![License: MPL-2.0](https://img.shields.io/github/license/dirs-dev/directories-jvm.svg)](LICENSE)
@@ -25,7 +25,7 @@ The library provides the location of these directories by leveraging the mechani
2525

2626
This library is written in Java, and runs on the JVM (≥ 6).
2727

28-
A version of this library implemented in Rust is provided by [directories-rs](https://github.com/soc/directories-rs).
28+
A version of this library implemented in Rust is provided by [directories-rs](https://github.com/dirs-dev/directories-rs).
2929

3030
## Usage
3131

@@ -36,19 +36,19 @@ Add the library as a dependency to your project:
3636
##### Maven
3737
```xml
3838
<dependency>
39-
<groupId>io.github.soc</groupId>
39+
<groupId>dev.dirs</groupId>
4040
<artifactId>directories</artifactId>
41-
<version>12</version>
41+
<version>20</version>
4242
</dependency>
4343
```
4444
##### Gradle
4545
```groovy
46-
compile 'io.github.soc:directories:12'
46+
compile 'dev.dirs:directories:20'
4747
```
4848

4949
##### SBT
5050
```scala
51-
"io.github.soc" % "directories" % "12"
51+
"dev.dirs" % "directories" % "20"
5252
```
5353

5454
The library itself is built against Java 6 to allow for the widest possible usage scenarios.
@@ -59,14 +59,14 @@ It can be used on any Java version >= 6.
5959
Library run by user Alice:
6060

6161
```java
62-
import io.github.soc.directories.ProjectDirectories;
63-
import io.github.soc.directories.BaseDirectories;
64-
import io.github.soc.directories.UserDirectories;
62+
import dev.dirs.ProjectDirectories;
63+
import dev.dirs.BaseDirectories;
64+
import dev.dirs.UserDirectories;
6565

6666
ProjectDirectories myProjDirs = ProjectDirectories.from("com", "Foo Corp", "Bar App");
6767
myProjDirs.configDir;
6868
// Lin: /home/alice/.config/barapp
69-
// Mac: /Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App
69+
// Mac: /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
7070
// Win: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config
7171

7272
BaseDirectories baseDirs = BaseDirectories.get();
@@ -114,15 +114,16 @@ that have been defined according to the conventions of the operating system the
114114

115115
If you want to compute the location of cache, config or data folders for your own application or project, use `ProjectDirectories` instead.
116116

117-
| Field name | Value on Linux / BSD | Value on Windows | Value on macOS |
118-
| --------------- | ---------------------------------------------------------------- | --------------------------------- | ----------------------------------- |
119-
| `homeDir` | `$HOME` | `{FOLDERID_UserProfile}` | `$HOME` |
120-
| `cacheDir` | `$XDG_CACHE_HOME` or `$HOME`/.cache | `{FOLDERID_LocalApplicationData}` | `$HOME`/Library/Caches |
121-
| `configDir` | `$XDG_CONFIG_HOME` or `$HOME`/.config | `{FOLDERID_ApplicationData}` | `$HOME`/Library/Preferences |
122-
| `dataDir` | `$XDG_DATA_HOME` or `$HOME`/.local/share | `{FOLDERID_ApplicationData}` | `$HOME`/Library/Application Support |
123-
| `dataLocalDir` | `$XDG_DATA_HOME` or `$HOME`/.local/share | `{FOLDERID_LocalApplicationData}` | `$HOME`/Library/Application Support |
124-
| `executableDir` | `$XDG_BIN_HOME` or `$XDG_DATA_HOME`/../bin or `$HOME`/.local/bin | `null` | `null` |
125-
| `runtimeDir` | `$XDG_RUNTIME_DIR` or `null` | `null` | `null` |
117+
| Field name | Value on Linux / BSD / Solaris | Value on Windows | Value on macOS |
118+
| -------------- | ---------------------------------------------------------------- | --------------------------------- | ----------------------------------- |
119+
| `homeDir` | `$HOME` | `{FOLDERID_UserProfile}` | `$HOME` |
120+
| `cacheDir` | `$XDG_CACHE_HOME` or `$HOME`/.cache | `{FOLDERID_LocalApplicationData}` | `$HOME`/Library/Caches |
121+
| `configDir` | `$XDG_CONFIG_HOME` or `$HOME`/.config | `{FOLDERID_ApplicationData}` | `$HOME`/Library/Application Support |
122+
| `dataDir` | `$XDG_DATA_HOME` or `$HOME`/.local/share | `{FOLDERID_ApplicationData}` | `$HOME`/Library/Application Support |
123+
| `dataLocalDir` | `$XDG_DATA_HOME` or `$HOME`/.local/share | `{FOLDERID_LocalApplicationData}` | `$HOME`/Library/Application Support |
124+
| `executableDir`| `$XDG_BIN_HOME` or `$XDG_DATA_HOME`/../bin or `$HOME`/.local/bin | `null` | `null` |
125+
| `preferenceDir`| `$XDG_CONFIG_HOME` or `$HOME`/.config | `{FOLDERID_ApplicationData}` | `$HOME`/Library/Preferences |
126+
| `runtimeDir` | `$XDG_RUNTIME_DIR` or `null` | `null` | `null` |
126127

127128
### `UserDirectories`
128129

@@ -147,13 +148,14 @@ that have been defined according to the conventions of the operating system the
147148
The intended use-case for `ProjectDirectories` is to compute the location of cache, config or data folders for your own application or project,
148149
which are derived from the standard directories.
149150

150-
| Field name | Value on Linux / BSD | Value on Windows | Value on macOS |
151-
| -------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------- |
152-
| `cacheDir` | `$XDG_CACHE_HOME`/`<project_path>` or `$HOME`/.cache/`<project_path>` | `{FOLDERID_LocalApplicationData}`/`<project_path>`/cache | `$HOME`/Library/Caches/`<project_path>` |
153-
| `configDir` | `$XDG_CONFIG_HOME`/`<project_path>` or `$HOME`/.config/`<project_path>` | `{FOLDERID_ApplicationData}`/`<project_path>`/config | `$HOME`/Library/Preferences/`<project_path>` |
154-
| `dataDir` | `$XDG_DATA_HOME`/`<project_path>` or `$HOME`/.local/share/`<project_path>` | `{FOLDERID_ApplicationData}`/`<project_path>`/data | `$HOME`/Library/Application Support/`<project_path>` |
155-
| `dataLocalDir` | `$XDG_DATA_HOME`/`<project_path>` or `$HOME`/.local/share/`<project_path>` | `{FOLDERID_LocalApplicationData}`/`<project_path>`/data | `$HOME`/Library/Application Support/`<project_path>` |
156-
| `runtimeDir` | `$XDG_RUNTIME_DIR`/`<project_path>` | `null` | `null` |
151+
| Field name | Value on Linux / BSD | Value on Windows | Value on macOS |
152+
| --------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------- |
153+
| `cacheDir` | `$XDG_CACHE_HOME`/`<project_path>` or `$HOME`/.cache/`<project_path>` | `{FOLDERID_LocalApplicationData}`/`<project_path>`/cache | `$HOME`/Library/Caches/`<project_path>` |
154+
| `configDir` | `$XDG_CONFIG_HOME`/`<project_path>` or `$HOME`/.config/`<project_path>` | `{FOLDERID_ApplicationData}`/`<project_path>`/config | `$HOME`/Library/Application Support/`<project_path>` |
155+
| `dataDir` | `$XDG_DATA_HOME`/`<project_path>` or `$HOME`/.local/share/`<project_path>` | `{FOLDERID_ApplicationData}`/`<project_path>`/data | `$HOME`/Library/Application Support/`<project_path>` |
156+
| `dataLocalDir` | `$XDG_DATA_HOME`/`<project_path>` or `$HOME`/.local/share/`<project_path>` | `{FOLDERID_LocalApplicationData}`/`<project_path>`/data | `$HOME`/Library/Application Support/`<project_path>` |
157+
| `preferenceDir` | `$XDG_CONFIG_HOME`/`<project_path>` or `$HOME`/.config/`<project_path>` | `{FOLDERID_ApplicationData}`/`<project_path>`/config | `$HOME`/Library/Preferences/`<project_path>` |
158+
| `runtimeDir` | `$XDG_RUNTIME_DIR`/`<project_path>` | `null` | `null` |
157159

158160
The specific value of `<project_path>` is computed by the
159161

@@ -185,7 +187,24 @@ The version number of this library consists of a whole number, which is incremen
185187

186188
## Changelog
187189

188-
### 12 – current stable version
190+
### 20 – current stable `dev.dirs:directories` release
191+
192+
- **BREAKING CHANGE** The behavior of `configDir` on macOS has been adjusted:
193+
- `BaseDirectories#configDir` and `ProjectDirectories#configDir` have been changed to use the `Application Support` directory,
194+
[as suggested by Apple documentation](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html).
195+
- If you have used `BaseDirectories#configDir` or `ProjectDirectories#configDir` to store files,
196+
it may be necessary to write code that migrates the files to the new location.
197+
(Alternative: change usages of `configDir` to `preferenceDir` to keep the old (pre-v20) behavior.)
198+
- The behavior of `configDir` on non-macOS platforms has not been changed.
199+
- `BaseDirectories#preferenceDir` and `ProjectDirectories#preferenceDir` have been added:
200+
- They use the `Preferences` directory on macOS, like `configDir` did before version 20.
201+
– `preferenceDir` behaves identical to `configDir` on non-macOS platforms.
202+
203+
### 19-13 – Reserved for bug fixes on `soc.github.io`
204+
205+
### 12 – current stable legacy `soc.github.io` release
206+
207+
_Please refer to [the legacy branch](https://github.com/dirs-dev/directories-jvm/tree/legacy) for the documentation and artifact coordinates of the `soc.github.io` artifact._
189208

190209
- Adjust library to deal with breaking changes in Java caused by CVE-2019-2958 (see JDK-8221858). Thanks @alexarchambault!
191210
- Support Solaris. Thanks @tomasjura!
@@ -267,3 +286,6 @@ The version number of this library consists of a whole number, which is incremen
267286
- Changes to the directory for executables:
268287
- Support for `executableDir` has been dropped on macOS.
269288
- The value of `executableDir` considers `$XDG_BIN_HOME` now, before falling back to `$XDG_DATA_HOME/../bin` and `$HOME/.local/bin`.
289+
290+
### 5-1 – Unpublished beta releases
291+

‎build.sbt‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
lazy val root = (project in file("."))
22
.settings(
33
name := "directories",
4-
organization := "io.github.soc",
4+
organization := "dev.dirs",
55
managedScalaInstance := false,
66
crossPaths := false,
7-
version := "12",
8-
homepage := Some(url("https://github.com/soc/directories-jvm")),
7+
version := "20",
8+
homepage := Some(url("https://github.com/dirs-dev/directories-jvm")),
99
licenses := Seq("Mozilla Public License 2.0" -> url("https://opensource.org/licenses/MPL-2.0")),
1010
fork := true,
1111
// The javaHome setting can be removed if building against the latest installed version of Java is acceptable.
@@ -25,14 +25,14 @@ lazy val root = (project in file("."))
2525
packageOptions in (Compile, packageBin) += {
2626
import java.util.jar.{Attributes, Manifest}
2727
val manifest = new Manifest
28-
manifest.getMainAttributes.put(new Attributes.Name("Automatic-Module-Name"), "io.github.soc.directories")
28+
manifest.getMainAttributes.put(new Attributes.Name("Automatic-Module-Name"), "dev.dirs")
2929
Package.JarManifest(manifest)
3030
},
3131
pomIncludeRepository := { _ => false },
3232
pomExtra :=
3333
<scm>
34-
<url>git@github.com:soc/directories-jvm.git</url>
35-
<connection>scm:git:git@github.com:soc/directories-jvm.git</connection>
34+
<url>git@github.com:dirs-dev/directories-jvm.git</url>
35+
<connection>scm:git:git@github.com:dirs-dev/directories-jvm.git</connection>
3636
</scm>
3737
<developers>
3838
<developer>

‎src/main/java/io/github/soc/directories/BaseDirectories.java‎ renamed to ‎src/main/java/dev/dirs/BaseDirectories.java‎

Lines changed: 50 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
package io.github.soc.directories;
1+
package dev.dirs;
22

3-
import static io.github.soc.directories.Util.*;
3+
import static dev.dirs.Util.*;
44

55
/** {@code BaseDirectories} provides paths of user-invisible standard directories, following the conventions of the operating system the library is running on.
66
* <p>
@@ -73,7 +73,7 @@ public final class BaseDirectories {
7373
*/
7474
public final String cacheDir;
7575

76-
/** Returns the path to the user's config directory.
76+
/** Returns the path to the user's configuration directory.
7777
* <br><br>
7878
* <table border="1" cellpadding="1" cellspacing="0">
7979
* <tr>
@@ -88,8 +88,8 @@ public final class BaseDirectories {
8888
* </tr>
8989
* <tr>
9090
* <td>macOS</td>
91-
* <td>{@code $HOME}/Library/Preferences</td>
92-
* <td>/Users/Alice/Library/Preferences</td>
91+
* <td>{@code $HOME}/Library/Application Support</td>
92+
* <td>/Users/Alice/Library/Application Support</td>
9393
* </tr>
9494
* <tr>
9595
* <td>Windows</td>
@@ -181,6 +181,33 @@ public final class BaseDirectories {
181181
*/
182182
public final String executableDir;
183183

184+
/** Returns the path to the user's preference directory.
185+
* <br><br>
186+
* <table border="1" cellpadding="1" cellspacing="0">
187+
* <tr>
188+
* <th align="left">Platform</th>
189+
* <th align="left">Value</th>
190+
* <th align="left">Example</th>
191+
* </tr>
192+
* <tr>
193+
* <td>Linux/BSD</td>
194+
* <td>{@code $XDG_CONFIG_HOME} or {@code $HOME}/.config</td>
195+
* <td>/home/alice/.config</td>
196+
* </tr>
197+
* <tr>
198+
* <td>macOS</td>
199+
* <td>{@code $HOME}/Library/Preferences</td>
200+
* <td>/Users/Alice/Library/Preferences</td>
201+
* </tr>
202+
* <tr>
203+
* <td>Windows</td>
204+
* <td>{@code {FOLDERID_RoamingAppData}}</td>
205+
* <td>C:\Users\Alice\AppData\Roaming</td>
206+
* </tr>
207+
* </table>
208+
*/
209+
public final String preferenceDir;
210+
184211
/** Returns the path to the user's runtime directory.
185212
* <br><br>
186213
* <table border="1" cellpadding="1" cellspacing="0">
@@ -230,15 +257,17 @@ private BaseDirectories() {
230257
dataDir = defaultIfNullOrEmpty(System.getenv("XDG_DATA_HOME"), homeDir, "/.local/share");
231258
dataLocalDir = dataDir;
232259
executableDir = linuxExecutableDir(homeDir, dataDir);
260+
preferenceDir = configDir;
233261
runtimeDir = linuxRuntimeDir(null);
234262
break;
235263
case MAC:
236264
homeDir = System.getProperty("user.home");
237265
cacheDir = homeDir + "/Library/Caches/";
238-
configDir = homeDir + "/Library/Preferences/";
239-
dataDir = homeDir + "/Library/Application Support/";
240-
dataLocalDir = dataDir;
266+
configDir = homeDir + "/Library/Application Support/";
267+
dataDir = configDir;
268+
dataLocalDir = configDir;
241269
executableDir = null;
270+
preferenceDir = homeDir + "/Library/Preferences/";
242271
runtimeDir = null;
243272
break;
244273
case WIN:
@@ -249,6 +278,7 @@ private BaseDirectories() {
249278
configDir = dataDir;
250279
cacheDir = dataLocalDir;
251280
executableDir = null;
281+
preferenceDir = configDir;
252282
runtimeDir = null;
253283
break;
254284
default:
@@ -259,13 +289,14 @@ private BaseDirectories() {
259289
@Override
260290
public String toString() {
261291
return "BaseDirectories (" + operatingSystemName + "):\n" +
262-
" homeDir = '" + homeDir + "'\n" +
263-
" cacheDir = '" + cacheDir + "'\n" +
264-
" configDir = '" + configDir + "'\n" +
265-
" dataDir = '" + dataDir + "'\n" +
266-
" dataLocalDir = '" + dataLocalDir + "'\n" +
267-
" executableDir = '" + executableDir + "'\n" +
268-
" runtimeDir = '" + runtimeDir + "'\n";
292+
" homeDir = '" + homeDir + "'\n" +
293+
" cacheDir = '" + cacheDir + "'\n" +
294+
" configDir = '" + configDir + "'\n" +
295+
" dataDir = '" + dataDir + "'\n" +
296+
" dataLocalDir = '" + dataLocalDir + "'\n" +
297+
" executableDir = '" + executableDir + "'\n" +
298+
" preferenceDir = '" + preferenceDir + "'\n" +
299+
" runtimeDir = '" + runtimeDir + "'\n";
269300
}
270301

271302
@Override
@@ -287,7 +318,9 @@ public boolean equals(Object o) {
287318
return false;
288319
if (executableDir != null ? !executableDir.equals(that.executableDir) : that.executableDir != null)
289320
return false;
290-
if (runtimeDir != null ? !runtimeDir .equals(that.runtimeDir) : that.runtimeDir != null)
321+
if (preferenceDir != null ? !preferenceDir.equals(that.preferenceDir) : that.preferenceDir != null)
322+
return false;
323+
if (runtimeDir != null ? !runtimeDir .equals(that.runtimeDir) : that.runtimeDir != null)
291324
return false;
292325
return true;
293326
}
@@ -301,6 +334,7 @@ public int hashCode() {
301334
result = 31 * result + (dataDir != null ? dataDir .hashCode() : 0);
302335
result = 31 * result + (dataLocalDir != null ? dataLocalDir .hashCode() : 0);
303336
result = 31 * result + (executableDir != null ? executableDir.hashCode() : 0);
337+
result = 31 * result + (preferenceDir != null ? preferenceDir.hashCode() : 0);
304338
result = 31 * result + (runtimeDir != null ? runtimeDir .hashCode() : 0);
305339
return result;
306340
}

0 commit comments

Comments
 (0)