Struct `HomeDirs`

pub struct HomeDirs { pub(crate) cache: Option<PathBuf>, pub(crate) config: Option<PathBuf>, pub(crate) data: Option<PathBuf>, pub(crate) state: Option<PathBuf>, pub(crate) extra: ExtraHomeDirs }

Common user directory paths used for user-specific application files.

It is not required that the user directories are accessible by the current user, nor that there is a directory at that path. A robust application should handle the case where user directories are incorrectly configured.

Even when configured correctly, multiple paths may point to the same location. You should not assume that a file written relative to one directory will not conflict with the same relative path in a different home directory.

Platform-specific behavior

As the filesystem conventions for discovering directories varies between operating systems, constructors for HomeDirs that use the host platform's conventions are provided as extension traits under the std::os module.

Fields

cache: Option<PathBuf>
config: Option<PathBuf>
data: Option<PathBuf>
state: Option<PathBuf>
extra: ExtraHomeDirs

Implementations

`impl HomeDirs`

fn set_cache_home(&mut self, path: PathBuf) -> &mut Self

Set the path for [Self::cache_home].

Panics

Panics if the provided path is not absolute.

fn set_config_home(&mut self, path: PathBuf) -> &mut Self

Set the path for [Self::config_home].

Panics

Panics if the provided path is not absolute.

fn set_data_home(&mut self, path: PathBuf) -> &mut Self

Set the path for [Self::data_home].

Panics

Panics if the provided path is not absolute.

fn set_state_home(&mut self, path: PathBuf) -> &mut Self

Set the path for [Self::state_home].

Panics

Panics if the provided path is not absolute.

`impl HomeDirs`

fn empty() -> Self

Create a known user directory set with no known directories.

This is useful with the builder set_* methods to create a HomeDirs with exactly the directories you want, without any other defaults.

fn cache_home(&self) -> Option<&Path>

A base directory relative to which user-specific non-essential cache data files should be stored.

"Cache" files are temporary data that can be used to cache redundant work of an application, but which can be discarded arbitrarily and recreated as necessary. Files in this directory may potentially be automatically purged any time they are not currently open, or they may not, depending on system configuration. A robust application should ensure that its caches do not grow without a reasonable bound.

This is the same directory for all applications. Applications should use a subdirectory for application-specific cache files.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	`${XDG_CACHE_HOME:-$HOME/.cache}`
Darwin (macOS)	`NSCachesDirectory` (`$HOME/Library/Caches`)
Windows	`{FOLDERID_LocalAppData}` (`%LOCALAPPDATA%`)

Other paths can be configured via set_cache_home.

fn config_home(&self) -> Option<&Path>

A base directory relative to which user-specific configuration files should be stored.

"Config" files are configuration managed by the user, either by editing the files directly or through a managing application. Configuration is generally expected to be meaningful to the user and portable enough to back up and synchronize across the same user's account on multiple systems.

This is the same directory for all applications. Applications should use a subdirectory for application-specific configuration files.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	`${XDG_CONFIG_HOME:-$HOME/.config}`
Darwin (macOS)	`NSApplicationSupportDirectory` (`$HOME/Library/Application Support`)
Windows	`{FOLDERID_RoamingAppData}` (`%APPDATA%`)

Other paths can be configured via set_config_home.

fn data_home(&self) -> Option<&Path>

A base directory relative to which user-specific data files should be stored.

"Data" files are application-specific data that is meaningful to the user in some way and does not implicitly rely on system configuration or details of how the application is installed otherwise irrelevant to the user. As such, data makes sense to back up and synchronize between the same user's account on multiple systems. If a file is specific to a single machine, it's probably state.

This is the same directory for all applications. Applications should use a subdirectory for application-specific data files.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	`${XDG_DATA_HOME:-$HOME/.local/share}`
Darwin (macOS)	`NSApplicationSupportDirectory` (`$HOME/Library/Application Support`)
Windows	`{FOLDERID_RoamingAppData}` (`%APPDATA%`)

Other paths can be configured via set_data_home.

fn state_home(&self) -> Option<&Path>

A base directory relative to which user-specific state files should be stored.

"State" files are data that should persist between application restarts, but which is not important nor portable enough to the user to synchronize between multiple systems like data are. Common examples include history (such as logs, recently used files, etc) and any current state of the application that should be reused (such as view, layout, open files, undo history, etc).

This is the same directory for all applications. Applications should use a subdirectory for application-specific state files.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	`${XDG_STATE_HOME:-$HOME/.local/state}`
Darwin (macOS)	`NSApplicationSupportDirectory` (`$HOME/Library/Application Support`)
Windows	`{FOLDERID_LocalAppData}` (`%LOCALAPPDATA%`)