Proposal

Problem statement

The standard library references the XDG Base Directories specification in std::env::home_dir's documentation, but provides no API to retrieve it other than std::env::var[_os].

Motivating examples or use cases

Providing a full Project Directories API that handles differing multi-platform conventions, as suggested in #387 (comment) by libs-api, is a desirable end state to aim for. However, this will take a great deal of research and bikeshedding before it can be made generally usable, and it's still not clear whether this full surface is something that should live in std.

Current users are thus left to either have to evaluate and compare multiple potential libraries providing this functionality or re-implement project directory discovery themselves, potentially overlooking cases that don't show up in their testing.

Even if std provides a fuller API surface in the future, it will still need to know how to interpret XDG paths to do so, and since it does, it make sense to provide that functionality to users. Providing it under std::os::unix will additionally further nudge developers towards considering whether they should be porting XDG behavior to other platforms or adopting more platform-native conventions.

Furthermore, a fully multi-platform API is unlikely to capture the specific nuance of any one platform's suggested split between files. Providing platform-specific API enables programs that want to go that extra mile to further specialize their filesystem usage to match the specific host platform's conventions instead of just the conventions that map well to most platforms.

Solution sketch

// in std::os::unix::xdg (new module)

/// A base directory relative to which user-specific data files should be written.
pub fn data_home_dir() -> PathBuf;
/// A base directory relative to which user-specific configuration files should be written.
pub fn config_home_dir() -> PathBuf;
/// A base directory relative to which user-specific state data should be written.
pub fn state_home_dir() -> PathBuf;
/// A base directory relative to which user-specific non-essential caches should be written.
pub fn cache_home_dir() -> PathBuf;

/// A set of preference ordered directories relative to which data files should be searched.
pub fn data_dirs() -> impl Iterator<Item = PathBuf>;
/// A set of preference ordered directories relative to which configuration files should be searched.
pub fn config_dirs() -> impl Iterator<Item = PathBuf>;

/// A base directory relative to which user-specific runtime files should be placed.
pub fn runtime_dir() -> PathBuf;

The use if "a" instead of "the" in the short docs is very deliberate, both to match the wording in the upstream XDG specification and to hint again that XDG is not the only directory layout that applications should consider.

Alternatives

• A multi-platform application directories API. This ACP does not preclude adopting such later, and neither does adopting such preclude the usefulness of this ACP.
• Instead of std::os::unix::xdg, these could be provided in std::os::xdg (as XDG is technically a spec that can be supported on non-unix platforms), std::os::linux (as Linux is the only Unix-like that has decent adoption of XDG path conventions), or std::os::unix::env (representing these functions as being Unix-specific extensions to std::env) instead.
• Just let the ecosystem solve this problem. It is the ACP author's opinion that the API proposed here is both a common recurring need in the ecosystem and has one widely agreed-upon but nontrivial "correct" solution, and as such that the standard library should provide the solution.

Links and related work

• Config file management rust-cli/team#7
• https://crates.io/crates/etcetera
• https://crates.io/crates/xdg
• more than is reasonably viable to backlink here

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.