Struct directories::ProjectDirs

pub struct ProjectDirs { /* fields omitted */ }

ProjectDirs computes the location of cache, config or data directories for a specific application, which are derived from the standard directories and the name of the project/organization.

Examples

All examples on this page are computed with a user named Alice, and a ProjectDirs struct created with ProjectDirs::from("com", "Foo Corp", "Bar App").

use directories::ProjectDirs;
if let Some(proj_dirs) = ProjectDirs::from("com", "Foo Corp",  "Bar App") {
    proj_dirs.config_dir();
    // Linux:   /home/alice/.config/barapp
    // Windows: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App
    // macOS:   /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
}

Implementations

impl ProjectDirs

pub fn from_path(project_path: PathBuf) -> Option<ProjectDirs>

Creates a ProjectDirs struct directly from a PathBuf value. The 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.

Use ProjectDirs::from instead.

pub fn from(
    qualifier: &str,
    organization: &str,
    application: &str
) -> Option<ProjectDirs>

Creates a ProjectDirs struct from values describing the project.

The returned value depends on the operating system and is either

• Some, containing project directory paths based on the state of the system’s paths at the time new() was invoked, or
• None, if no valid home directory path could be retrieved from the operating system.

To determine whether a system provides a valid $HOME path, please refer to BaseDirs::new

The use of ProjectDirs::from (instead of ProjectDirs::from_path) is strongly encouraged, as its results will follow operating system standards on Linux, macOS and Windows.

Parameters

• qualifier – The reverse domain name notation of the application, excluding the organization or application name itself.
  An empty string can be passed if no qualifier should be used (only affects macOS).
  Example values: "com.example", "org", "uk.co", "io", ""
• organization – The name of the organization that develops this application, or for which the application is developed.
  An empty string can be passed if no organization should be used (only affects macOS and Windows).
  Example values: "Foo Corp", "Alice and Bob Inc", ""
• application – The name of the application itself.
  Example values: "Bar App", "ExampleProgram", "Unicorn-Programme"

pub fn project_path(&self) -> &Path

Returns the project path fragment used to compute the project’s cache/config/data directories. The value is derived from the ProjectDirs::from call and is platform-dependent.

pub fn cache_dir(&self) -> &Path

Returns the path to the project’s cache directory.

Platform	Value	Example
Linux	$XDG_CACHE_HOME/_project_path_ or $HOME/.cache/_project_path_	/home/alice/.cache/barapp
macOS	$HOME/Library/Caches/_project_path_	/Users/Alice/Library/Caches/com.Foo-Corp.Bar-App
Windows	{FOLDERID_LocalAppData}\_project_path_\cache	C:\Users\Alice\AppData\Local\Foo Corp\Bar App\cache

pub fn config_dir(&self) -> &Path

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/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 data_dir(&self) -> &Path

Returns the path to the project’s data directory.

Platform	Value	Example
Linux	$XDG_DATA_HOME/_project_path_ or $HOME/.local/share/_project_path_	/home/alice/.local/share/barapp
macOS	$HOME/Library/Application Support/_project_path_	/Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
Windows	{FOLDERID_RoamingAppData}\_project_path_\data	C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\data

pub fn data_local_dir(&self) -> &Path

Returns the path to the project’s local data directory.

Platform	Value	Example
Linux	$XDG_DATA_HOME/_project_path_ or $HOME/.local/share/_project_path_	/home/alice/.local/share/barapp
macOS	$HOME/Library/Application Support/_project_path_	/Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
Windows	{FOLDERID_LocalAppData}\_project_path_\data	C:\Users\Alice\AppData\Local\Foo Corp\Bar App\data

pub fn preference_dir(&self) -> &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 runtime_dir(&self) -> Option<&Path>

Returns the path to the project’s runtime directory.

The runtime directory contains transient, non-essential data (like sockets or named pipes) that is expected to be cleared when the user’s session ends.

Platform	Value	Example
Linux	$XDG_RUNTIME_DIR/_project_path_	/run/user/1001/barapp
macOS	–	–
Windows	–	–

pub fn state_dir(&self) -> Option<&Path>

Returns the path to the project’s state directory.

The state directory contains data that should be retained between sessions (unlike the runtime directory), but may not be important/portable enough to be synchronized across machines (unlike the config/preferences/data directories).

The returned value depends on the operating system and is either a Some, containing a value from the following table, or a None.

Platform	Value	Example
Linux	$XDG_STATE_HOME/_project_path_ or $HOME/.local/state/_project_path_	/home/alice/.local/state/barapp
macOS	–	–
Windows	–	–

Trait Implementations

impl Clone for ProjectDirs

fn clone(&self) -> ProjectDirs

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ProjectDirs

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.