devoncarew / app_dirs Goto Github PK

A library to locate common directories using platform-specific conventions.

This library follows platform-specific conventions to locate common directories. For example, the correct directory to use for application configuration files might be $HOME/.config/my-app on Linux, $HOME/Library/Application Support/My App on Macos, and %APPDATA%\My App\config on Windows.

To use:

var appDirs = getAppDirs(application: 'FooBar App');

// Use this directory for general application configuration files.
var configDir = appDirs.config;
...

// Use this directory for cached information.
var cacheDir = appDirs.cache;
...

See also our API docs.

For MacOS defaults, we follow Apple's

• Standard Directories docs. This generally puts files in subdirectories of $HOME/Library, which is appropriate for most Mac apps.

API clients can opt into a separate set of file location convetions for Macos. This is done via the preferUnixConventions flag:

var appDirs = getAppDirs(
  application: 'FooBar App',
  preferUnixConventions: true,
);

This will opt that tool into using Unix style directory conventions - for example, putting config files into $HOME/.config/foobar-app. While not the Macos standard file locations, this could better match user expectations for things like command-line tools.

On Unix OSes, we follow the XDG Base Directory Specification. This is generally creating directories under the user's $HOME directory, but respecting various $XDG_* environment variable overrides.

On Windows, we follow the standard Windows directory structure convention (docuented here and elsewhere).

This is the table of directories returned for Directories.baseDirs. AppDirs - the recommended API for people to use - builds on top of this using information like the application name, qualifier (org, com, ...) and organization name.

Specifications and documentation:

• https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
• developer.apple.com/library/archive/documentation/FileManagement
• https://pureinfotech.com/list-environment-variables-windows-10/

Similar libraries for other platforms:

• https://github.com/dirs-dev/directories-jvm
• https://github.com/dirs-dev/directories-rs

For information about our publishing automation and release process, see https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.