Tracking Issue for `std::fs::HomeDirs` (`feature(fs_home_dirs)`)

Feature gate: #![feature(fs_home_dirs)]

This is a tracking issue for std::fs::HomeDirs and related functionality.

Sister feature tracking issue: std::fs::MediaDirs

HomeDirs exposes common user directory paths useful for user application files. This supersedes the XDG APIs.

Public API

// mod std::fs
pub struct HomeDirs { /* ... */ }
impl HomeDirs {
    fn empty() -> Self;

    pub fn config_home(&self) -> Option<&Path>;
    pub fn data_home(&self) -> Option<&Path>;
    pub fn state_home(&self) -> Option<&Path>;
    pub fn cache_home(&self) -> Option<&Path>;

    pub fn set_config_home(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_data_home(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_state_home(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_cache_home(&mut self, path: PathBuf) -> &mut Self;
}

// mod std::os::darwin::fs
impl HomeDirsExt for HomeDirs { /* ... */ }
pub impl(self) trait HomeDirsExt {
    fn sysdir() -> io::Result<Self>;
}

// mod std::os::unix::fs
impl HomeDirsExt for HomeDirs { /* ... */ }
pub impl(self) trait HomeDirsExt {
    fn xdg() -> io::Result<Self>;

    fn runtime_home(&self) -> Option<&Path>;
    fn config_dirs(&self) -> Option<XdgDirs<'_>>;
    fn data_dirs(&self) -> Option<XdgDirs<'_>>;

    fn set_runtime_home(&mut self, path: PathBuf) -> &mut Self;
    fn set_config_dirs(&mut self, paths: OsString) -> &mut Self;
    fn set_data_dirs(&mut self, paths: OsString) -> &mut Self;
}

pub struct XdgDirs<'a> { /* ... */ }
impl Iterator for XdgDirs<'a> {
    type Item = &'a Path;
    /* ... */
}

// mod std::os::windows::fs
impl HomeDirsExt for HomeDirs { /* ... */ }
pub impl(self) trait HomeDirsExt {
    fn appdata_env() -> io::Result<Self>;
    fn known_folders() -> io::Result<Self>;
}

Steps / History

(Remember to update the S-tracking-* label when checking boxes.)

• ACP: https://github.com/rust-lang/libs-team/issues/830
• Implementation: https://github.com/rust-lang/rust/pull/158936
• Final comment period (FCP)^1
• Stabilization PR

Unresolved Questions

• Is this API sufficiently platform-agnostic and resilient to new OS developments to live in std?
  • The author believes so. T-libs-api has approved in-tree experimentation.
• I (@CAD97) think that a fn take(&mut self) -> Self method would be useful for builder-API style usage of the set_* methods. T-libs-api agreed we don't. I will defer to T-libs-api here, but want to log this note.
  • #t-libs/api-changes > MediaDirs::take
• Should the Unix HomeDirsExt provide fn bin_home(&self) -> Option<&Path>? The XDG spec defines a bin home path to specifically $HOME/.local/bin and $XDG_BIN_HOME is a non-standard extension.
• Should the Windows HomeDirsExt provide access to more of the PERUSER KNOWNFOLDERIDs?
• The XDG base directories spec is technically platform-agnostic as of the (unversioned) update to specify directory lists in terms of how PATH is handled instead of mandating : as a separator. Should HomeDirs::xdg() be platform agnostic or limited to the Unix extension trait?
  • This has bearing on whether XdgDirs can iterate &Path or if it needs to iterate PathBuf like env::split_paths does.
• APIs for media dirs are out of scope for this tracking issue; for those, see https://github.com/rust-lang/rust/issues/162083.
• APIs for app dirs (which are subdirs of the home dirs) is explicitly out of scope for this tracking issue and should get a new ACP.