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

[CAD97]

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: ACP: std::fs::UserDirs or similar libs-team#830
• Implementation: Add std::fs::{Home|Media}Dirs #158936
• Final comment period (FCP)¹
• 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 Tracking Issue for std::fs::MediaDirs (feature(fs_media_dirs)) #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.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[djc]

From the ACP:

I explicitly avoided Default/new because the user expectation may be for the default constructor to use the "default platform conventions," whatever those are. This is the behavior of the directories crate, for example. Naming the portable constructor empty IMHO creates a pit of success in that it creates an affordance for the user to discover that there isn't a consistent answer for "default platform conventions" and to consider what conventions they want to use explicitly.

Can you expand on this? I don't fully understand what you're going for with this.

Also, feels like the _home suffixes on methods of HomeDirs are a little stuttery? What's the rationale for this?

[CAD97]

expand on Default

When I, as a developer, see HomeDirs::new() or HomeDirs::default() in the source code, there are two things I could intuit this as providing:

• A default initialization that is consistent across platforms. This is the behavior of HomeDirs::empty().
• The default home directories for the current platform. This is the behavior of ::directories::BaseDirs::new().

Because the "default" for HomeDirs is not trivially one or the other, I posit that asking the user to write HomeDirs::empty() or the appropriate cfg_select! creates a "pit of success" by forcing them to consider what they actually want. Note also that "default platform conventions" is not always perfectly clear without further context (e.g. GUI tools on macOS should use sysdir but CLI tools often use xdg) nor are they necessarily stable across new versions of the platform.

_home suffixes on methods

This could go either way. The main reason to keep them is that these directories are the directory for all applications to share. It's out of scope for this issue¹, but we could imagine another method .with_app_subpath(impl AsRef<Path>) -> AppDirs, and that struct's methods wouldn't have the _home suffixes.

But underneath, this is inherited from the split between XDG_XX_HOME and XDG_XX_DIRS.

Footnotes

1. Largely because platforms disagree what the "app subpath" should look like. ↩

[djc]

Makes sense, thanks for explaining!