Tracking Issue for `std::fs::MediaDirs` (`feature(fs_media_dirs)`)

[CAD97]

Feature gate: #![feature(fs_media_dirs)]

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

Sister feature tracking issue: std::fs::HomeDirs

MediaDirs exposes common user directory paths useful for storing media files.

Public API

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

    pub fn desktop(&self) -> Option<&Path>;
    pub fn documents(&self) -> Option<&Path>;
    pub fn downloads(&self) -> Option<&Path>;
    pub fn music(&self) -> Option<&Path>;
    pub fn pictures(&self) -> Option<&Path>;
    pub fn videos(&self) -> Option<&Path>;

    pub fn set_desktop(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_documents(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_downloads(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_music(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_pictures(&mut self, path: PathBuf) -> &mut Self;
    pub fn set_videos(&mut self, path: PathBuf) -> &mut Self;
}

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

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

    fn templates(&self) -> Option<&Path>;
    fn set_templates(&mut self, path: PathBuf) -> &mut Self;
}

// mod std::os::windows::fs
impl MediaDirsExt for MediaDirs { /* ... */ }
pub impl(self) trait MediaDirsExt {
    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, resilient to new OS developments, and generally useful to live in std?
  • The author believes so. T-libs-api has approved in-tree experimentation.
  • Should these paths be exposed by std or left to an external crate? CLI tools are likely to prefer using passed-in paths, and GUI apps are likely to have a GUI framework that could be a reasonable home for this functionality.
• 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 Windows MediaDirsExt provide access to more of the PERUSER KNOWNFOLDERIDs?
• APIs for home dirs are out of scope for this tracking issue; for those, see Tracking Issue for std::fs::HomeDirs (feature(fs_home_dirs)) #162082.
• 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 ↩

[joshtriplett]

As these paths should primarily be used in conjunction with a file picker, should the determination of file picker starting paths be left to the crate implementing the file picker?

I'm not sure what this is referencing. I'd expect these directories to be used with things other than a file picker. For instance, a music player might automatically index and present all the music from the music directory. A camera application might automatically put pictures and video into the appropriate places; ditto a screenshot application. A browser might automatically put downloads into the downloads directory, without presenting a file picker.

[joshtriplett]

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.

To be explicit, we thought that mem::replace(dirs, HomeDirs::empty()) would be sufficient for this use case.

[djc]

Aren't MediaDirs relative to the home dir on all platforms? Why is there a specific type for this?

[ChrisDenton]

Aren't MediaDirs relative to the home dir on all platforms? Why is there a specific type for this?

They are not. On Windows at least they are independent of any root directory. And in particular, getting the directories requires using the GUI shell APIs. And that requires being a GUI application (or specifically GDI handles), which has performance implications. This is something rust's std has tried to avoid.

Opting into it is better than paying a cost for something you don't use.