From b0607d23cdcc42b0f820a0da7cc0e20481ce54ad Mon Sep 17 00:00:00 2001 From: Emma Thorpe Date: Tue, 1 Sep 2026 10:27:36 +0100 Subject: [PATCH] docs(console): separate the two Steam picker faults The library-folder picker does open and Steam does create the directory structure; the library simply never appears in the Storage UI. That rules out the portal FileChooser for this symptom and points at the write-and-execute probe Steam runs before recording the folder in libraryfolders.vdf (ValveSoftware/steam-for-linux#8450). Document how to reproduce that probe inside Steam's FHS sandbox with steam-run, and keep library_folder_add as the route that reports a reason. The Add a Non-Steam Game dialog is a separate symptom and keeps the portal explanation. Co-Authored-By: Claude Opus 5 (1M context) --- docs/hosts/console.md | 81 +++++++++++++++++++++++++++++++------------ 1 file changed, 59 insertions(+), 22 deletions(-) diff --git a/docs/hosts/console.md b/docs/hosts/console.md index e7483b5..97cc814 100644 --- a/docs/hosts/console.md +++ b/docs/hosts/console.md @@ -150,13 +150,12 @@ Steam titles. Added as Steam shortcuts they appear in Big Picture and inherit Steam Input, so the controller works in them without further configuration. Steam's own **Games → Add a Non-Steam Game** is the documented route and is also -the one that tends not to work. Both that dialog's **Browse** button and the -library-folder picker below go through the XDG desktop portal `FileChooser` -interface; when the portal is unreachable the client silently falls back to a -legacy chooser that is blank or inert — Valve -[#9447](https://github.com/ValveSoftware/steam-for-linux/issues/9447) and -[#10415](https://github.com/ValveSoftware/steam-for-linux/issues/10415), neither -fixed. Check the portal side before blaming the client: +the one that does not work here: the dialog never appears at all. That dialog's +file browsing goes through the XDG desktop portal `FileChooser` interface, and +when the portal is unreachable the client falls back to a legacy chooser that is +blank or inert — Valve +[#9447](https://github.com/ValveSoftware/steam-for-linux/issues/9447), not fixed. +Check the portal side before blaming the client: ```sh busctl --user introspect org.freedesktop.portal.Desktop \ @@ -297,22 +296,56 @@ RetroArch is pointed at these paths declaratively. The other two have to be told once, in their own UIs: - **Steam** — Settings → Storage → the `+` control → add `/srv/games/steam` as a - library folder. Games installed there survive a reinstall of the OS. That - picker is the broken one described under - [Adding non-Steam titles to Big Picture](#adding-non-steam-titles-to-big-picture); - when it comes up blank, use Steam's own console instead — open Steam with - `steam -console`, pick the **CONSOLE** tab and run: - - ``` - library_folder_add /srv/games/steam - ``` - - The directory must already exist and be writable by the user Steam runs as, - which `systemd.tmpfiles` guarantees. The command does not create it. + library folder. Games installed there survive a reinstall of the OS. See + [When Steam will not register the library folder](#when-steam-will-not-register-the-library-folder) + below; it does not currently take. - **Clone Hero** — set the song library path to `/srv/games/clonehero/songs` from its settings screen. Clone Hero keeps its own config in `~/.clonehero`. +### When Steam will not register the library folder + +Current behaviour on this host: the file picker opens, Steam creates the +directory structure at `/srv/games/steam`, and the library then never appears in +the Storage UI. So this is not the portal problem the non-Steam-game dialog has +— the picker works and Steam can write. The failure is in the validation Steam +runs before it records the folder in `libraryfolders.vdf`. + +That validation is a write-and-execute probe: Steam drops a +`.steam_exec_test.sh` in the candidate folder, marks it executable and runs it. +If either step fails the folder is silently dropped, which is +[#8450](https://github.com/ValveSoftware/steam-for-linux/issues/8450) and is +usually a `noexec` mount or an ownership problem — neither of which is obviously +true here, since `/srv` is on the ext4 root and the tree is +`lyrathorpe:users` 2775. + +Reproduce the probe **inside Steam's FHS sandbox**, which is where the client +actually runs it — `steam-run` is installed by the steam module for exactly this +kind of thing: + +```sh +steam-run sh -c ' + printf "#!/bin/sh\nexit 0\n" > /srv/games/steam/.steam_exec_test.sh && + chmod +x /srv/games/steam/.steam_exec_test.sh && + /srv/games/steam/.steam_exec_test.sh && + echo "probe ok" +' +rm -f /srv/games/steam/.steam_exec_test.sh +``` + +Then ask the client directly. Steam's console reports a reason where the UI +says nothing — open Steam with `steam -console`, pick the **CONSOLE** tab and +run: + +``` +library_folder_add /srv/games/steam +``` + +The directory must already exist and be writable by the user Steam runs as, +which `systemd.tmpfiles` guarantees; the command does not create it. Whatever it +prints, plus `~/.steam/steam/logs/content_log.txt`, is the evidence to work +from. + ## Steam and Proton `programs.steam.enable` already arranges most of what Proton needs, and it is @@ -407,9 +440,13 @@ The machine is installed and Sway works. Still outstanding: and `__GLX_VENDOR_LIBRARY_NAME=nvidia`, the standard fix, but the combination has a history of needing more. Read `journalctl -b -t steam-session` first — see [When the television lands on ReGreet instead of Steam](#when-the-television-lands-on-regreet-instead-of-steam). -- **Steam's file pickers do not open** — both the non-Steam-game **Browse** - dialog and the library-folder picker. Upstream client bugs with usable - workarounds; see the two sections above. +- **Steam will not register `/srv/games/steam` as a library folder.** The picker + opens and the directory structure gets created; the library never appears in + the Storage UI. Not the portal — see + [When Steam will not register the library folder](#when-steam-will-not-register-the-library-folder). +- **Steam's Add a Non-Steam Game dialog never appears.** Separate symptom, + probably the portal `FileChooser`; `steamtinkerlaunch` writes the shortcuts + without it in the meantime. - **Boot into Big Picture has not been exercised**, since autologin has not run. - **Television resolution and refresh.** gamescope takes the output's native mode by default. Add `gamescopeSession.args = [ "-W" "3840" "-H" "2160" "-r"