Add xdg_basedir API by CAD97 · Pull Request #157518 · rust-lang/rust

CAD97 · 2026-06-06T02:13:02Z

Implements an API providing easy access to the XDG Base Directories.

I chose to defer runtime_dir (XDG_RUNTIME_DIR) since the lack of a specified default (but specified expectation for applications to determine an alternative option somehow) makes the correct usage (and thus ideal API) less obvious.

Accepted ACP: ACP: Add XDG Basedirs API to std::os::unix::xdg libs-team#805
Tracking issue: Tracking Issue for xdg_basedir #157515

rustbot · 2026-06-06T02:13:07Z

r? @aapoalas

rustbot has assigned @aapoalas.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: @ChrisDenton, libs
@ChrisDenton, libs expanded to 11 candidates
Random selection from LawnGnome, Mark-Simulacrum, aapoalas, clarfonthey, jhpratt

CAD97 · 2026-06-06T02:16:10Z

cc @BurntSushi (+1 on ACP)

Kobzol · 2026-06-06T07:23:26Z

Might be interesting to @rami3l.

rami3l · 2026-06-06T07:28:26Z

@Kobzol Thanks for the ping!

Our current plan with @Cloud0310 regarding rust-lang/rustup#247 is slightly more complicated than this because it involves handling both old and new home definitions shared by rustup and cargo. That said, having std APIs for the XDG paths will definitely make this easier.

aapoalas

Looks good to me - I had a bunch of comments here and there but nothing that I'd consider blocking.

Let me know your thoughts on the comments and one we've handled them one way or another (made changes or decided to ignore) then we can put this on the train.

View changes since this review

CAD97

The bit of the doc comments that touch on installation rather than normal program execution are the last bit I'm not super confident in. Installation is a entirely separate can of worms that I'm not qualified to speak to, so the best I can do is try to recontectualize the GNU Make assuming spec to the Cargo build system here. (Which doesn't even have a concept of build or installation artifacts other than the executable bundle.)

View changes since this review

CAD97 · 2026-06-08T12:24:15Z

+///
+/// If an application defines a data file to be at `$XDG_DATA_DIRS/appid/file.name`, this means that:
+///
+/// - The initial data file should be installed to `{system_data_dir}/appid/file.name`.


{system_data_dir} here is our version of the XDG spec's

$datadir [...] with $datadir defaulting to /usr/share.

AIUI, $datadir doesn't refer to an environment variable like the other $XDG_* variables, but to a conventional GNU Make variable for installation directories. The build-system agnostic version of this would be "program installation data directory base" or similar.

It feels like a cop-out to provide the XDG paths API but still leave an undefined template variable here, but I don't know how we could do better. This specifically is a concern of the installer, not of the installed program, as a properly configured system will ensure that this path is in $XDG_DATA_DIRS so that the installed data is actually found during lookup.

Does this suggest that there should be an API to create an installer datadir path, given a $datadir template variable value?

The current API surface is deliberately not giving app-specific paths, only the base directories that the app-specific folders go in. So such an API would just spit $datadir back out unchanged. $sysconfdir would just append /xdg. In any case, installation isn't really part of the XDG basedir spec, and if application file lookup is a contentious floating target, installers is even more so.

Another way to put the difference is that only the program that creates installable packages or whatever delivery mechanism needs to understand the conventions for installation, whereas every program that isn't just a single stateless executable needs to understand how to access auxiliary files.

CAD97 · 2026-06-08T12:26:54Z

+///
+/// If an application defines a configuration file to be at `$XDG_CONFIG_DIRS/appid/file.name`, this means that:
+///
+/// - The initial configuration file should be installed to `{system_config_dir}/xdg/appid/file.name`.


{system_config_dir} here is our version of the XDG spec's

$sysconfdir [...] with $sysconfdir defaulting to /etc.

AIUI, $sysconfdir doesn't refer to an environment variable like the other $XDG_* variables, but to a conventional GNU Make variable for installation directories. The build-system agnostic version of this would be "program installation configuration directory base" or similar.

It feels like a cop-out to provide the XDG paths API but still leave an undefined template variable here, but I don't know how we could do better. This specifically is a concern of the installer, not of the installed program, as a properly configured system will ensure that this path is in $XDG_CONFIG_DIRS so that the installed data is actually found during lookup.

aapoalas

The $datadir and $sysconfdir points are interesting.

I'd be fine to merge this as-is, but do you think that is a good idea @CAD97 ? Also what's @orlp 's opinion?

View changes since this review

rustbot · 2026-06-11T17:57:05Z

Reminder, once the PR becomes ready for a review, use @rustbot ready.

orlp · 2026-06-11T19:38:43Z

@aapoalas My main concerns I expressed earlier are still unaddressed.

XDG basedirs is an unstable specification at 0.8, last updated ~5 years ago. It could change tomorrow but we can't update the Rust standard library.
There's no justification given why for example the xdg crate is insufficient for this purpose. I think inclusion in the standard library has a high bar which isn't met here.

Typically inclusion in the standard library is motivated through one of four forms (note, my observation - not official policy):

The standard library forms a lingua franca that lets code talk to each other in a common language. E.g. Future, Vec, String Error, Hash, Default, Borrow, Option, Result fall under this.
The functionality is fundamental for the language, e.g. UnsafeCell or Any.
The functionality provided abstracts over platform-specific details for commonly needed functionality. E.g. std::fs, std::net, GlobalAlloc, std::thread, std::time, etc.
The functionality is a platform-specific intrinsic or API. E.g. std::arch or std::os.
The functionality is just so common and universally used, it should be available out of the box. E.g. [T]::sort, str::contains, BinaryHeap, etc.

I just don't see this functionality really falling under any of the four categories. It doesn't form a common language, it's not fundamental, it doesn't provide an abstraction and isn't used all that commonly. The closest is nr. 4, but it's not really an API, more a convention, and it's not all that platform-specific even.

ChrisDenton · 2026-06-11T22:20:39Z

I think it is. It was version 0.6 in 2003, and then in 2010 0.7 came out, and in 2021 0.8 came out. There is no indication the standard is finalized. The standard has changed multiple times after appearing stable for a couple years.

That is misleading. The thing added in 0.8 is XDG_STATE_HOME but this is well within rust's normal stability guarantees. No existing application using XDG base directories would be broken by adding new XDG_ variables.

orlp · 2026-06-11T22:33:05Z

@ChrisDenton XDG Base Directory specification 0.8 also changed the separator of $XDG_DATA_DIRS and $XDG_CONFIG_DIRS. In 0.7 it was always :, in 0.8 it is the separator used for $PATH on the platform (typically this is a colon :). This is a breaking change.

ChrisDenton · 2026-06-11T22:44:53Z

@ChrisDenton XDG Base Directory specification 0.8 also changed the separator of $XDG_DATA_DIRS and $XDG_CONFIG_DIRS. In 0.7 it was always :, in 0.8 it is the separator used for $PATH on the platform (typically this is a colon :). This is a breaking change.

That is not in the published specification. It is in the repository but is explicitly noted as not being a breaking change: https://gitlab.freedesktop.org/xdg/xdg-specs/-/commit/22a6d100a1c28d5fb725fb1d3d2f872cf4308769

I don’t think this can be a backwards compatibility break, as due to colons being used for drive identifiers on Windows, it’s never really been possible to use colons as search path separators.

And this definitely won't be a breaking change for the rust standard library because the API lives in std::os::unix.

orlp · 2026-06-11T22:46:54Z

Is https://specifications.freedesktop.org/basedir/ not "published"? It's there and marked as version 0.8... If that's not version 0.8 it should be marked as 0.9-draft or whatever.

ChrisDenton · 2026-06-11T22:54:14Z

Oh huh, "0.8" and "latest" are different. Interesting. My other points still stands though.

aapoalas · 2026-06-13T11:41:20Z

@aapoalas My main concerns I expressed earlier are still unaddressed.

As I think I said in one comment, I believe these are worthwhile concerns for blocking stabilisation of the API but I don't see them as worthwhile blockers for this PR: now, I'm just a first-time libs reviewer and my understanding and "feel" for this is lacking indeed, but the way I see it is:

An ACP has been accepted, so opening a PR to test out the proposed API change is good and okay.
As the PR code-wise looks okay, as a libs reviewer I don't have reasons to block it (I do not believe it is my job to decide on whether the API is good or not).
The next steps after this are unstable experimentation on this API and gathering feedback, very much including yours, then an eventual stabilisation or revert of the ACP based on that feedback.

I do have some points that I agree with you on: if the eventual point is for the std to offer an OS-independent "minimal API", it does not necessarily mean that each os library would get its own "maximal API". ... Though eg. fs offers extensions per OS (eg. PermissionsExt), so maybe there is some reason to think that is normal? And it can absolutely be argued that the spec is not stable enough to be included in the std, and/or that it's not the kind of stuff that std should include. Those are absolutely things that we should discuss, but in the tracking issue and not in a PR introducing an unstable API for testing out :)

As a long-time Linux user, I'm personally also quite happy to see this stuff proposed: we'll make The Year of the Linux Desktop yet! :D

@bors r+ rollup

rust-bors · 2026-06-13T11:41:23Z

📌 Commit 378da80 has been approved by aapoalas

It is now in the queue for this repository.

🌲 The tree is currently closed for pull requests below priority 5. This pull request will be tested once the tree is reopened.

rust-bors · 2026-06-13T14:48:19Z

⌛ Testing commit 378da80 with merge 876e334...

Workflow: https://github.com/rust-lang/rust/actions/runs/27469971600

Add xdg_basedir API Implements an API providing easy access to the XDG Base Directories. I chose to defer `runtime_dir` (`XDG_RUNTIME_DIR`) since the lack of a specified default (but specified expectation for applications to determine an alternative option somehow) makes the correct usage (and thus ideal API) less obvious. - Accepted ACP: rust-lang/libs-team#805 - Tracking issue: #157515

JonathanBrouwer · 2026-06-13T14:51:13Z

@bors yield
Yielding to enclosing rollup

rust-bors · 2026-06-13T14:51:16Z

Auto build was cancelled. Cancelled workflows:

https://github.com/rust-lang/rust/actions/runs/27469971600

The next pull request likely to be tested is #157863.

…uwer Rollup of 5 pull requests Successful merges: - #157518 (Add xdg_basedir API) - #157752 (Rename `errors.rs` file to `diagnostics.rs` (6/N)) - #157769 (Match expressions had not been updated to also show the match_source,…) - #157825 (Emit retags in codegen to support BorrowSanitizer (part 3)) - #157861 (Rename `errors.rs` file to `diagnostics.rs` (7/N))

Rollup merge of #157518 - CAD97:xdg_basedir, r=aapoalas Add xdg_basedir API Implements an API providing easy access to the XDG Base Directories. I chose to defer `runtime_dir` (`XDG_RUNTIME_DIR`) since the lack of a specified default (but specified expectation for applications to determine an alternative option somehow) makes the correct usage (and thus ideal API) less obvious. - Accepted ACP: rust-lang/libs-team#805 - Tracking issue: #157515

…las" This reverts commit ac80064, reversing changes made to 8d6b380.

Revert "Rollup merge of rust-lang#157518 - CAD97:xdg_basedir, r=aapoalas" This reverts commit ac80064, reversing changes made to 8d6b380.  - rust-lang#157515 is superseded - This includes just the revert that's the first commit in rust-lang#158936

Rollup of 5 pull requests Successful merges: - #162270 (Update `windows-bindgen` to 0.100.0) - #162492 (Revert "Rollup merge of #157518 - CAD97:xdg_basedir, r=aapoalas") - #162607 (Basic cleanup in `rustc_transmute`) - #162514 (Simplify diagnostic levels) - #162613 (iter::repeat_with, iter::successors, iter::from_fn added as diagnostic items)

Revert "Rollup merge of rust-lang#157518 - CAD97:xdg_basedir, r=aapoalas" This reverts commit ac80064, reversing changes made to 8d6b380.  - rust-lang#157515 is superseded - This includes just the revert that's the first commit in rust-lang#158936

Rollup of 10 pull requests Successful merges: - #162270 (Update `windows-bindgen` to 0.100.0) - #162492 (Revert "Rollup merge of #157518 - CAD97:xdg_basedir, r=aapoalas") - #162607 (Basic cleanup in `rustc_transmute`) - #162619 (Add test for the missing Clone requirement for Cow slices) - #162172 (mention the opaque when its hidden type cannot be inferred) - #162514 (Simplify diagnostic levels) - #162546 (Use lld by default on `loongarch64-unknown-linux-gnu` nightly) - #162564 (yeet StabilityLevel) - #162613 (iter::repeat_with, iter::successors, iter::from_fn added as diagnostic items) - #162616 (regression test for async main diagnostic)

Rollup merge of #162492 - CAD97:rm-xdg, r=ChrisDenton Revert "Rollup merge of #157518 - CAD97:xdg_basedir, r=aapoalas" This reverts commit ac80064, reversing changes made to 8d6b380.  - #157515 is superseded - This includes just the revert that's the first commit in #158936

rustbot assigned aapoalas Jun 6, 2026

rustbot added O-unix Operating system: Unix-like S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jun 6, 2026

CAD97 mentioned this pull request Jun 6, 2026

Tracking Issue for xdg_basedir #157515

Closed

4 tasks

CAD97 force-pushed the xdg_basedir branch from 9e48634 to b64cf30 Compare June 6, 2026 02:18

This comment has been minimized.

Sign in to view

CAD97 force-pushed the xdg_basedir branch from b64cf30 to a75cbe2 Compare June 6, 2026 02:30

This comment has been minimized.

Sign in to view

Add xdg_basedir API

073e649

CAD97 force-pushed the xdg_basedir branch from a75cbe2 to 073e649 Compare June 6, 2026 03:14

aapoalas approved these changes Jun 6, 2026

View reviewed changes

CAD97 added 5 commits June 7, 2026 21:11

update module doc comment after review

9534d0f

reword xdg::cache_home_dir doc per review

2b3d273

remove unnecessary helper generics

7b46306

reduce byte shuffling in XdgDirsIter

593a847

remove unused import

6e670de

aapoalas reviewed Jun 8, 2026

View reviewed changes

Comment thread library/std/src/os/unix/xdg.rs

aapoalas reviewed Jun 8, 2026

View reviewed changes

Comment thread library/std/src/os/unix/xdg.rs

CAD97 commented Jun 8, 2026

View reviewed changes

orlp reviewed Jun 8, 2026

View reviewed changes

Comment thread library/std/src/os/unix/xdg.rs

aapoalas requested changes Jun 11, 2026

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 11, 2026

rust-bors Bot added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 13, 2026

aapoalas self-requested a review June 13, 2026 11:41

aapoalas approved these changes Jun 13, 2026

View reviewed changes

JonathanBrouwer mentioned this pull request Jun 13, 2026

Rollup of 5 pull requests #157863

Merged

rust-bors Bot merged commit ac80064 into rust-lang:main Jun 13, 2026
12 of 13 checks passed

rustbot added this to the 1.98.0 milestone Jun 13, 2026

CAD97 deleted the xdg_basedir branch June 13, 2026 23:03

CAD97 added a commit to CAD97/rust that referenced this pull request Jul 22, 2026

Revert "Rollup merge of rust-lang#157518 - CAD97:xdg_basedir, r=aapoa…

fed84bc

…las" This reverts commit ac80064, reversing changes made to 8d6b380.

CAD97 added a commit to CAD97/rust that referenced this pull request Sep 1, 2026

Revert "Rollup merge of rust-lang#157518 - CAD97:xdg_basedir, r=aapoa…

f290c98

…las" This reverts commit ac80064, reversing changes made to 8d6b380.

jhpratt mentioned this pull request Sep 10, 2026

Rollup of 5 pull requests #162617

Closed

jhpratt mentioned this pull request Sep 11, 2026

Rollup of 10 pull requests #162622

Merged

Uh oh!

Uh oh!

Conversation

CAD97 commented Jun 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jun 6, 2026

Uh oh!

CAD97 commented Jun 6, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

Kobzol commented Jun 6, 2026

Uh oh!

rami3l commented Jun 6, 2026

Uh oh!

aapoalas left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CAD97 left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CAD97 Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

aapoalas Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

CAD97 Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

CAD97 Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aapoalas left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustbot commented Jun 11, 2026

Uh oh!

orlp commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ChrisDenton commented Jun 11, 2026

Uh oh!

orlp commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ChrisDenton commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

orlp commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ChrisDenton commented Jun 11, 2026

Uh oh!

aapoalas commented Jun 13, 2026

Uh oh!

rust-bors Bot commented Jun 13, 2026

Uh oh!

rust-bors Bot commented Jun 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JonathanBrouwer commented Jun 13, 2026

Uh oh!

rust-bors Bot commented Jun 13, 2026

Uh oh!

CAD97 commented Jun 6, 2026 •

edited

Loading

aapoalas left a comment •

edited

Loading

CAD97 left a comment •

edited by rustbot

Loading

aapoalas left a comment •

edited

Loading

orlp commented Jun 11, 2026 •

edited

Loading

orlp commented Jun 11, 2026 •

edited

Loading

ChrisDenton commented Jun 11, 2026 •

edited

Loading

orlp commented Jun 11, 2026 •

edited

Loading

rust-bors Bot commented Jun 13, 2026 •

edited

Loading