Repository navigation
Tracking Issue for xdg_basedir #157515
Description
Feature gate: #![feature(xdg_basedir)]
This is a tracking issue for API providing the XDG Base Directories in std::os::unix::xdg.
- Superseded by Add
std::fs::{Home|Media}Dirs#158936
Public API
// in std::os::unix::xdg (new module)
pub fn data_home_dir() -> PathBuf;
pub fn config_home_dir() -> PathBuf;
pub fn state_home_dir() -> PathBuf;
pub fn cache_home_dir() -> PathBuf;
#[derive(Debug, Clone)]
pub struct XdgDirsIter { /* ... */ };
impl Iterator for XdgDirsIter { /* ... */ }
pub fn data_dirs() -> XdgDirsIter;
pub fn config_dirs() -> XdgDirsIter;Steps / History
(Remember to update the S-tracking-* label when checking boxes.)
- ACP: ACP: Add XDG Basedirs API to
std::os::unix::xdglibs-team#805 - Implementation: Add xdg_basedir API #157518
- Superseded by Add
std::fs::{Home|Media}Dirs#158936
Unresolved Questions
- Should we provide
runtime_dir(doesn't have a specified default) and/orbin_home_dir(has a specified default but the environment variable override is a common non-XDG-standard extension)?
Reacted by Nia Deckers, teor, Cloud, Josh Triplett and Nikolas Rimikis
Reacted by Luracasmus
Activity
joboet commentedon Jun 6, 2026
I do not think this is a good idea. Putting this API into the shared UNIX module does not make any sense to me, because platforms like macOS are never going to follow the XDG specification, making this API entirely useless there. In general,
stdshould not provide an API for something that is distribution- (and not target-)specific, and even then – is the target audience for this really large enough? We don't provide APIs for console colours or similar things either, not because they're not useful, but because it's out of scope.@rustbot label +I-libs-api-nominated
(as this was unilaterally approved by @BurntSushi)
ChrisDenton commentedon Jun 6, 2026
For bash and cli tools (git, docker, etc)? I think there is a lot of precedent there. The story is different for GUI apps of course but that doesn't mean it's never used.
joboet commentedon Jun 6, 2026
Well, half the CLI tools do use the Linux paths, but the other half doesn't. And the "proper" (in the sense that idiomatic applications use them) directories are not the XDG ones. See e.g. the
platform_dirslibrary which hardcodes the macOS directories. I don't thinkstdshould pick a side here.ChrisDenton commentedon Jun 6, 2026
It needn't pick a side. It could also have macos specific methods for
Library/CachesandLibrary/Application Support.BurntSushi commentedon Jun 7, 2026
FWIW, I approved the ACP knowing full well that there is some design work to figure out in terms of how to deal with macOS here. There are multiple ways of handling it, and I expect std to have something to say about that somewhere as part of this work. Indeed, std needn't pick a side, and should empower stakeholders (people who ship software to end users) to make the choice that best suits their needs. Moreover, the presence of an XDG implementation in std needn't be prescriptive itself. For example, some stakeholders may continue to elect to put dotfiles directly in
$HOMEand ignore XDG altogether.joboet commentedon Jun 7, 2026
That's a reasonable stance, but I think you could argue that
stdhaving this API at all is picking a side. I can well imagine someone going "where should my cache files go", then seeingcache_home_dirand not thinking twice about whether this is actually a good choice (which I don't think it is on macOS).CAD97 commentedon Jun 8, 2026
I do think it's a reasonable ask to have macOS's APIs available as well before stabilizing XDG paths in a location available to macOS, to avoid accidentally implying XDG as the only convention available.
tgross35 commentedon Jun 8, 2026
It feels weird excluding Windows but including MacOS, since (as mentioned) CLI tools on both of those platforms often use XDG paths. Could we just always provide them in
std::env::xdg?We could have separate modules at
std::os::{linux,darwin,windows}::base_directoriesfor the OS-specific directories with an API that fits.ChrisDenton commentedon Jun 8, 2026
For Windows, directly using XDG base directories is much less common (though does happen with some ported tools) and Windows isn't a Unix so some things make no sense at all if going by the spec (e.g.
XDG_DATA_DIRSandXDG_CONFIG_DIRS).That said, I would support having Windows specific functions that return
APPDATAandLOCALAPPDATA. We could document XDG equivalents. Something like:APPDATAXDG_CONFIG_HOMEXDG_STATE_HOMELOCALAPPDATAXDG_DATA_HOMEXDG_CACHE_HOMEprogrammerjake commentedon Jun 8, 2026
on Android, XDG isn't usually a thing, but it is under Termux (a terminal emulator app that has a custom Linux distro that runs out of
/data/data/com.termux/files/, e.g.HOME=/data/data/com.termux/files/home)orlp commentedon Jun 8, 2026
I concur with @joboet and don't think this should be added, I've expanded my thoughts on the ACP: rust-lang/libs-team#805 (comment).
I also don't know why the ACP was accepted unilaterally.
14 remaining items
CAD97 commentedon Aug 31, 2026
xdg_basedir#157515std::fs::{Home|Media}Dirs#158936 / Revert "Rollup merge of #157518 - CAD97:xdg_basedir, r=aapoalas" #162492Rollup merge of rust-lang#162492 - CAD97:rm-xdg, r=ChrisDenton
Rollup merge of rust-lang#162492 - CAD97:rm-xdg, r=ChrisDenton
Unrolled build for #162492 in rollup 162622
Rollup merge of rust-lang#158936 - CAD97:dirs, r=aapoalas
Auto merge of #158936 - CAD97:dirs, r=aapoalas
Rollup merge of rust-lang#158936 - CAD97:dirs, r=aapoalas
Rollup merge of rust-lang#158936 - CAD97:dirs, r=aapoalas
Rollup merge of rust-lang#158936 - CAD97:dirs, r=aapoalas
Rollup merge of rust-lang#158936 - CAD97:dirs, r=aapoalas
Unrolled build for #158936 in rollup 163522