Dire
Complete cross-platform solution for data and user directories discovery.
|
Classes | |
struct | BaseDirsBundle |
class | IReallyWantMyOwnPlatformProjectName |
class | PlatformProjectName |
struct | ProjectDirsBundle |
struct | UserDirsBundle |
Typedefs | |
using | Path = std::filesystem::path |
template<typename T > | |
using | Optional = std::optional< T > |
using dire::Optional = typedef std::optional<T> |
using dire::Path = typedef std::filesystem::path |
Typically used to store audio files, programs which download and/or work with audio files may also use it.
Platform | Method | Example |
---|---|---|
Linux | $XDG_MUSIC_DIR | /home/foo/Music |
Mac | home_dir() + "/Music" | /Users/Foo/Music |
Windows | Known Folder API FOLDERID_Music | C:\Users\Foo\Music |
A directory for program caches.
Only caches should be stored here (files safe to delete, i.e. download caches), not files that are meant to be persisted.
For configuration files: config_dir
, config_local_dir
or preference_dir
For state files: state_dir
(doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
)
For data files: data_dir
, data_local_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_CACHE_HOME or $HOME/.cache | /home/foo/.cache |
Mac | home_dir() + "/Library/Caches" | /Users/Foo/Library/Caches |
Windows | Known Folder API FOLDERID_LocalAppData | C:\Users\Foo\AppData\Local |
auto dire::cache_dir | ( | PlatformProjectName | project_name | ) | -> Optional< Path > |
A directory for program caches.
Only caches should be stored here (files safe to delete, i.e. download caches), not files that are meant to be persisted.
For configuration files: config_dir
, config_local_dir
or preference_dir
For state files: state_dir
(doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
)
For data files: data_dir
, data_local_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_CACHE_HOME or $HOME/.cache | /home/foo/.cache |
Mac | home_dir() + "/Library/Caches" | /Users/Foo/Library/Caches |
Windows | Known Folder API FOLDERID_LocalAppData | C:\Users\Foo\AppData\Local |
A directory for program configuration files.
Only configuration files should be stored here, as users often back up this directory.
On linux and macOS this is the same as config_local_dir
.
On windows this directory can be synchronized in a domain.
For applications that are meant for power users, developers, etc., prefer this. Otherwise, prefer preference_dir
.
This matters on macOS as it stores the configuration files in $HOME/.config
instead of $HOME/Library/Application Support
.
For cache files: cache_dir
For state files: state_dir
(doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
)
For data files: data_dir
, data_local_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_CONFIG_HOME or $HOME/.config | /home/foo/.config |
Mac | home_dir() + "/.config" | /Users/Foo/.config |
Windows | Known Folder API FOLDERID_RoamingAppData | C:\Users\Foo\AppData\Roaming |
auto dire::config_dir | ( | PlatformProjectName | project_name | ) | -> Optional< Path > |
A directory for program configuration files.
Only configuration files should be stored here, as users often back up this directory.
On linux and macOS this is the same as config_local_dir
.
On windows this directory can be synchronized in a domain.
For applications that are meant for power users, developers, etc., prefer this. Otherwise, prefer preference_dir
.
This matters on macOS as it stores the configuration files in $HOME/.config
instead of $HOME/Library/Application Support
.
For cache files: cache_dir
For state files: state_dir
(doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
)
For data files: data_dir
, data_local_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_CONFIG_HOME or $HOME/.config | /home/foo/.config |
Mac | home_dir() + "/.config" | /Users/Foo/.config |
Windows | Known Folder API FOLDERID_RoamingAppData | C:\Users\Foo\AppData\Roaming |
A directory for program configuration files for the current user only.
Only configuration files should be stored here, as users often back up this directory.
On linux and macOS this is the same as config_dir
.
On windows this directory cannot be synchronized in the domain as opposed to config_dir
.
For applications that are meant for power users, developers, etc., prefer this. Otherwise, prefer preference_dir
.
This matters on macOS as it stores the configuration files in $HOME/.config
instead of $HOME/Library/Application Support
.
For cache files: cache_dir
For state files: state_dir
(doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
)
For data files: data_dir
, data_local_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_CONFIG_HOME or $HOME/.config | /home/foo/.config |
Mac | home_dir() + "/.config" | /Users/Foo/.config |
Windows | Known Folder API FOLDERID_LocalAppData | C:\Users\Foo\AppData\Local |
auto dire::config_local_dir | ( | PlatformProjectName | project_name | ) | -> Optional< Path > |
A directory for program configuration files for the current user only.
Only configuration files should be stored here, as users often back up this directory.
On linux and macOS this is the same as config_dir
.
On windows this directory cannot be synchronized in the domain as opposed to config_dir
.
For applications that are meant for power users, developers, etc., prefer this. Otherwise, prefer preference_dir
.
This matters on macOS as it stores the configuration files in $HOME/.config
instead of $HOME/Library/Application Support
.
For cache files: cache_dir
For state files: state_dir
(doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
)
For data files: data_dir
, data_local_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_CONFIG_HOME or $HOME/.config | /home/foo/.config |
Mac | home_dir() + "/.config" | /Users/Foo/.config |
Windows | Known Folder API FOLDERID_LocalAppData | C:\Users\Foo\AppData\Local |
A directory for program data files.
Used for files inherently portable across machines like icons, fonts, desktop entries and such.
On linux and macOS this is the same as data_local_dir
.
On windows this directory can be synchronized in a domain.
For state files: state_dir
(doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
)
For cache files: cache_dir
For configuration files: config_dir
, config_local_dir
or preference_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_DATA_HOME or $HOME/.local/share | /home/foo/.local/share |
Mac | home_dir() + "/Library/Application Support" | /Users/Foo/Library/Application Support |
Windows | Known Folder API FOLDERID_RoamingAppData | C:\Users\Foo\AppData\Roaming |
auto dire::data_dir | ( | PlatformProjectName | project_name | ) | -> Optional< Path > |
A directory for program data files.
Used for files inherently portable across machines like icons, fonts, desktop entries and such.
On linux and macOS this is the same as data_local_dir
.
On windows this directory can be synchronized in a domain.
For state files: state_dir
(doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
)
For cache files: cache_dir
For configuration files: config_dir
, config_local_dir
or preference_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_DATA_HOME or $HOME/.local/share | /home/foo/.local/share |
Mac | home_dir() + "/Library/Application Support" | /Users/Foo/Library/Application Support |
Windows | Known Folder API FOLDERID_RoamingAppData | C:\Users\Foo\AppData\Roaming |
A directory for program data files for the current user only.
Used for files inherently portable across machines like icons, fonts, desktop entries and such.
On linux and macOS this is the same as data_dir
.
On windows this directory cannot be synchronized in the domain as opposed to data_dir
.
For state files: state_dir
(doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
)
For cache files: cache_dir
For configuration files: config_dir
, config_local_dir
or preference_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_DATA_HOME or $HOME/.local/share | /home/foo/.local/share |
Mac | home_dir() + "/Library/Application Support" | /Users/Foo/Library/Application Support |
Windows | Known Folder API FOLDERID_LocalAppData | C:\Users\Foo\AppData\Local |
auto dire::data_local_dir | ( | PlatformProjectName | project_name | ) | -> Optional< Path > |
A directory for program data files for the current user only.
Used for files inherently portable across machines like icons, fonts, desktop entries and such.
On linux and macOS this is the same as data_dir
.
On windows this directory cannot be synchronized in the domain as opposed to data_dir
.
For state files: state_dir
(doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
)
For cache files: cache_dir
For configuration files: config_dir
, config_local_dir
or preference_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_DATA_HOME or $HOME/.local/share | /home/foo/.local/share |
Mac | home_dir() + "/Library/Application Support" | /Users/Foo/Library/Application Support |
Windows | Known Folder API FOLDERID_LocalAppData | C:\Users\Foo\AppData\Local |
This is the directory whose contents are displayed on the desktop (on Linux desktops are not always available, which is typically the case for Tiling Window Managers).
Platform | Method | Example |
---|---|---|
Linux | $XDG_DESKTOP_DIR | /home/foo/Desktop |
Mac | home_dir() + "/Desktop" | /Users/Foo/Desktop |
Windows | Known Folder API FOLDERID_Desktop | C:\Users\Foo\Desktop |
Used mostly for plaintext and text processor documents. Lots of other programs may use it as well, especially ones made for designing.
Platform | Method | Example |
---|---|---|
Linux | $XDG_DOCUMENTS_DIR | /home/foo/Documents |
Mac | home_dir() + "/Documents" | /Users/Foo/Documents |
Windows | Known Folder API FOLDERID_Documents | C:\Users\Foo\Documents |
Mostly used by browsers for saved files. Some other programs may utilize it as well.
Platform | Method | Example |
---|---|---|
Linux | $XDG_DOWNLOAD_DIR | /home/foo/Downloads |
Mac | home_dir() + "/Downloads" | /Users/Foo/Downloads |
Windows | Known Folder API FOLDERID_Downloads | C:\Users\Foo\Downloads |
A user writable directory for binaries. This is not officialy supported by the XDG specification!
This directory doesn't exist on windows and macOS!
Platform | Method | Example |
---|---|---|
Linux | $XDG_BIN_HOME | /home/foo/.local/bin |
Mac | nullopt | nullopt |
Windows | nullopt | nullopt |
Directory for font files.
It doesn't exist on windows, as it doesn't have a one, standard directory for fonts.
They are typically put and found in \WINDIR%\Fonts
- typically C:\Windows\Fonts
or \LOCALAPPDATA%\Microsoft\Windows\Fonts\
- typically C:\Users\Foo\AppData\Local\Microsoft\Windows\Fonts
.
Platform | Method | Example |
---|---|---|
Linux | $XDG_DATA_HOME /fonts or $HOME/.local/share/fonts | /home/foo/Public |
Mac | home_dir() + "/Library/Fonts" | /Users/Foo/Library/Fonts |
Windows | nullopt | nullopt |
auto dire::name | ( | std::string | domain, |
std::string | org, | ||
std::string | app_name | ||
) | -> PlatformProjectName |
Used to obtain a platform specific PlatformProjectName
which is used for obtaining project specific directories for caches, configs and such.
If you want to override the name to your own one, initialize PlatformProjectName
directly with IReallyWantMyOwnPlatformProjectName
.
On linux only app_name
is used and produces a name that is lowercased and with spaces removed. On windows only app_name
and org
are used and produces a path like domain / name
without other modifications. On mac all three are used and produce a name like domain.org.app_name
with all free segments lowercased and spaces replaced with hyphens. e.g. dire::name("me", "dich0tomy", "dire")
will produce:
Platform | Result |
---|---|
Linux | dire |
Mac | me.dich0tomy.dire |
Windows | Dichotomy/Dire |
Typically used by programs for downloading and manipulating images.
Platform | Method | Example |
---|---|---|
Linux | $XDG_PICTURES_DIR | /home/foo/Pictures |
Mac | home_dir() + "/Pictures" | /Users/Foo/Pictures |
Windows | Known Folder API FOLDERID_Pictures | C:\Users\Foo\Pictures |
A directory for program configuration files.
Only configuration files should be stored here, as users often back up this directory.
For applications that are meant for ordinary users prefer this.
For applications meant for developers and power users prefer config_dir
or config_local_dir
.
This matters on macOS as it stores the configuration files in $HOME/Library/Application Support
instead of $HOME/.config
.
For cache files: cache_dir
For state files: state_dir
(doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
)
For data files: data_dir
, data_local_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_CACHE_HOME or $HOME/.cache | /home/foo/.cache |
Mac | home_dir() + "/Library/Caches" | /Users/Foo/Library/Caches |
Windows | Known Folder API FOLDERID_LocalAppData | C:\Users\Foo\AppData\Local |
auto dire::preference_dir | ( | PlatformProjectName | project_name | ) | -> Optional< Path > |
A directory for program configuration files.
Only configuration files should be stored here, as users often back up this directory.
For applications that are meant for ordinary users prefer this.
For applications meant for developers and power users prefer config_dir
or config_local_dir
.
This matters on macOS as it stores the configuration files in $HOME/Library/Application Support
instead of $HOME/.config
.
For cache files: cache_dir
For state files: state_dir
(doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
)
For data files: data_dir
, data_local_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_CACHE_HOME or $HOME/.cache | /home/foo/.cache |
Mac | home_dir() + "/Library/Caches" | /Users/Foo/Library/Caches |
Windows | Known Folder API FOLDERID_LocalAppData | C:\Users\Foo\AppData\Local |
A directory that all users have access to. This is especially useful for windows and mac which have native solutions for sharing these over network.
Platform | Method | Example |
---|---|---|
Linux | $XDG_PUBLICSHARE_DIR | /home/foo/Public |
Mac | home_dir() + "/Public" | /Users/Foo/Public |
Windows | Known Folder API FOLDERID_Public | C:\Users\Foo\Public |
Used for user-specific non-essential runtime files and other file objects (such as sockets, named pipes, ...)
This directory doesn't exist on windows and macOS!
Platform | Method | Example |
---|---|---|
Linux | $XDG_RUNTIME_DIR | /run/foo/1000 |
Mac | nullopt | nullopt |
Windows | nullopt | nullopt |
auto dire::runtime_dir | ( | PlatformProjectName | project_name | ) | -> Optional< Path > |
Used for user-specific non-essential runtime files and other file objects (such as sockets, named pipes, ...)
This directory doesn't exist on windows and macOS!
Platform | Method | Example |
---|---|---|
Linux | $XDG_RUNTIME_DIR | /run/foo/1000 |
Mac | nullopt | nullopt |
Windows | nullopt | nullopt |
A directory for state files - logs, history and such.
This directory doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
.
For cache files: cache_dir
For configuration files: config_dir
, config_local_dir
or preference_dir
For data files: data_dir
, data_local_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_STATE_HOME or $HOME/.local/state | /home/foo/.local/state |
Mac | nullopt | nullopt |
Windows | nullopt | nullopt |
auto dire::state_dir | ( | PlatformProjectName | project_name | ) | -> Optional< Path > |
A directory for state files - logs, history and such.
This directory doesn't exist on windows and macOS! Use bundle.state_dir.value_or(bundle.data_local_dir)
.
For cache files: cache_dir
For configuration files: config_dir
, config_local_dir
or preference_dir
For data files: data_dir
, data_local_dir
Platform | Method | Example |
---|---|---|
Linux | $XDG_STATE_HOME or $HOME/.local/state | /home/foo/.local/state |
Mac | nullopt | nullopt |
Windows | nullopt | nullopt |
Directory for user template files.
On linux users can drop all kinds of template files there, which the desktop environment then picks up and allows creating new documents based on them from a contextual menu.
On windows this folder is typically dependent on user programs, like the software from the Microsoft suite or its other alternatives - which means there's a bigger chance for it to fail!
Platform | Method | Example |
---|---|---|
Linux | $XDG_TEMPLATES_DIR | /home/foo/Templates |
Mac | nullopt | nullopt |
Windows | Known Folder API FOLDERID_Templates | C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Templates |
Typically used by programs for downloading videos.
Mac has a special case here and names the dir Movies
Platform | Method | Example |
---|---|---|
Linux | $XDG_VIDEOS_DIR | /home/foo/Videos |
Mac | home_dir() + "/Pictures" | /Users/Foo/Movies |
Windows | Known Folder API FOLDERID_Videos | C:\Users\Foo\Videos |