dirs

A tiny low-level library that provides platform-specific standard locations of directories for config, cache and other data on Linux, Windows, macOS and Redox by leveraging the mechanisms defined by the XDG base/user directory specifications on Linux, the Known Folder API on Windows, and the Standard Directory guidelines on macOS

Design Goals

The dirs library is a low-level crate designed to provide the paths to standard directories
as defined by operating systems rules or conventions. If your requirements are more complex,
e. g. computing cache, config, etc. paths for specific applications or projects, consider using
directories instead.

This library does not create directories or check for their existence. The library only provides
information on what the path to a certain directory should be. How this information is used is
a decision that developers need to make based on the requirements of each individual application.

This library is intentionally focused on providing information on user-writable directories only.
There is no discernible benefit in returning a path that points to a user-level, writable
directory on one operating system, but a system-level, read-only directory on another, that would
outweigh the confusion and unexpected failures such an approach would cause.

executable_dir is specified to provide the path to a user-writable directory for binaries.
As such a directory only commonly exists on Linux, it returns None on macOS and Windows.

font_dir is specified to provide the path to a user-writable directory for fonts.
As such a directory only exists on Linux and macOS, it returns None on Windows.

runtime_dir is specified to provide the path to a directory for non-essential runtime data.
It is required that this directory is created when the user logs in, is only accessible by the
user itself, is deleted when the user logs out, and supports all filesystem features of the
operating system.
As such a directory only commonly exists on Linux, it returns None on macOS and Windows.

Features

If you want to compute the location of cache, config or data directories for your own application or project,
use ProjectDirs of the directories project instead.

Function name

Value on Linux/Redox

Value on Windows

Value on macOS

home_dir

Some($HOME)

Some({FOLDERID_Profile})

Some($HOME)

cache_dir

Some($XDG_CACHE_HOME) or Some($HOME/.cache)

Some({FOLDERID_LocalAppData})

Some($HOME/Library/Caches)

config_dir

Some($XDG_CONFIG_HOME) or Some($HOME/.config)

Some({FOLDERID_RoamingAppData})

Some($HOME/Library/Preferences)

data_dir

Some($XDG_DATA_HOME) or Some($HOME/.local/share)

Some({FOLDERID_RoamingAppData})

Some($HOME/Library/Application Support)

data_local_dir

Some($XDG_DATA_HOME) or Some($HOME/.local/share)

Some({FOLDERID_LocalAppData})

Some($HOME/Library/Application Support)

executable_dir

Some($XDG_BIN_HOME/../bin) or Some($XDG_DATA_HOME/../bin) or Some($HOME/.local/bin)

None

None

runtime_dir

Some($XDG_RUNTIME_DIR) or None

None

None

audio_dir

Some(XDG_MUSIC_DIR) or None

Some({FOLDERID_Music})

Some($HOME/Music/)

desktop_dir

Some(XDG_DESKTOP_DIR) or None

Some({FOLDERID_Desktop})

Some($HOME/Desktop/)

document_dir

Some(XDG_DOCUMENTS_DIR) or None

Some({FOLDERID_Documents})

Some($HOME/Documents/)

download_dir

Some(XDG_DOWNLOAD_DIR) or None

Some({FOLDERID_Downloads})

Some($HOME/Downloads/)

font_dir

Some($XDG_DATA_HOME/fonts/) or Some($HOME/.local/share/fonts/)

None

Some($HOME/Library/Fonts/)

picture_dir

Some(XDG_PICTURES_DIR) or None

Some({FOLDERID_Pictures})

Some($HOME/Pictures/)

public_dir

Some(XDG_PUBLICSHARE_DIR) or None

Some({FOLDERID_Public})

Some($HOME/Public/)

template_dir

Some(XDG_TEMPLATES_DIR) or None

Some({FOLDERID_Templates})

None

video_dir

Some(XDG_VIDEOS_DIR) or None

Some({FOLDERID_Videos})

Some($HOME/Movies/)

Comparison

There are other crates in the Rust ecosystem that try similar or related things.
Here is an overview of them, combined with ratings on properties that guided the design of this crate.

Please take this table with a grain of salt: a different crate might very well be more suitable for your specific use case.
(Of course my crate achieves my design goals better than other crates, which might have had different design goals.)

License

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.