From 917988587abc228ccf063026feb810297725c87a Mon Sep 17 00:00:00 2001 From: Douglas Teles Date: Tue, 23 Jun 2026 16:25:04 -0300 Subject: [PATCH] FHS F6: Class E via umbrella bridge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Same playbook as F5, applied to user data. /storage/roms appears in 117 files in projects/ArchR and refactoring every reference in one shot would be a huge diff over the directory where the user's games library lives. Bad risk-reward. Two new umbrella bridges in the archr meta-package: /var/lib/archr/games -> /storage/roms /var/lib/archr/backup -> /storage/backup ARCHR_GAMES flipped to the FHS path; man page mirrors it. The other Class E paths (screenshots, recordings, downloads, music, pictures, videos, tvshows) audit as zero references in projects/ArchR; they are LibreELEC top-level heritage and not used at ArchR runtime. /storage/.ssh stays as is. busybox/package.mk sets the root user's HOME to /storage, so /storage/.ssh is literally $HOME/.ssh — FHS already. Moving to /root/.ssh would require flipping the HOME of root to /root first, which has knock-on effects (cd ~, every script that assumes cwd at login, etc) outside the FHS scope. No data migration script: nothing on disk moves. ROMs and saves keep exactly the same bytes; the FHS path is just another way to address them. Co-Authored-By: Claude Opus 4.7 --- docs/fhs-mapping.md | 40 ++++++++++++------- projects/ArchR/packages/archr/package.mk | 9 +++++ .../packages/archr/profile.d/010-archr-fhs | 4 +- .../ArchR/packages/archr/sources/man/archr.7 | 10 +++-- 4 files changed, 42 insertions(+), 21 deletions(-) diff --git a/docs/fhs-mapping.md b/docs/fhs-mapping.md index a8990967f8..7dc637760d 100644 --- a/docs/fhs-mapping.md +++ b/docs/fhs-mapping.md @@ -173,23 +173,32 @@ Resultado: do ponto de vista de qualquer ferramenta inspecionando o sistema roda **Per-emulator data dirs (`/storage/.local/share/`):** mesma estratégia. Dolphin, Duckstation, m8c, gmu acessam via `/var/lib/archr/data/` ou via o path legacy; ambos resolvem para o mesmo conteúdo. -### Fase 6 — Class E: dados do usuário (70 paths) +### Fase 6 — Class E: dados do usuário -**Objetivo:** mover ROMs, saves, screenshots, recordings. **Fase de maior risco.** +**Status: concluída (2026-06-23) via bridge umbrella.** Mesma decisão de F5, ainda mais consequente aqui: `/storage/roms` aparece em **117 arquivos** de `projects/ArchR/` (scripts de emulador, quirks por device, setsettings.sh, runemu.sh, smb.conf shares). Refatorar 117 arquivos numa única release seria diff massivo e ainda mais perigoso porque o substrato é onde a biblioteca de jogos do usuário reside. -- `/storage/roms` → `/var/lib/archr/games` (rom library) -- `/storage/screenshots` → `/var/lib/archr/games/screenshots` -- `/storage/recordings` → `/var/lib/archr/games/recordings` -- `/storage/downloads` → `/var/lib/archr/downloads` -- `/storage/music`, `/storage/pictures`, `/storage/videos`, `/storage/tvshows` → `/var/lib/archr/media/` -- `/storage/.ssh` → `/root/.ssh` (FHS-correto pra root) -- `/storage/backup` → `/var/lib/archr/backup` +**Decisão final:** +1. `archr` meta-package instala dois bridges: + - `/var/lib/archr/games` → `/storage/roms` + - `/var/lib/archr/backup` → `/storage/backup` +2. `ARCHR_GAMES` em `/etc/profile.d/010-archr-fhs` flipa para `/var/lib/archr/games`. +3. `archr(7)` ENVIRONMENT atualizado. -**Pré-requisitos antes desta fase:** -1. Todas as fases anteriores em produção há pelo menos uma release. -2. Migration script tem validação por checksum de cada arquivo migrado. -3. Fallback de rollback documentado. -4. Aviso ao usuário no upgrade ("vai mover ROMs, tempo estimado X"). +**Análise dos demais paths Class E:** + +| Path | Refs em projects/ArchR | Decisão | +|------|------------------------|---------| +| `/storage/roms` | 117 | umbrella bridge | +| `/storage/backup` | 1 (tmpfiles) | umbrella bridge | +| `/storage/screenshots` | 0 | herança LibreELEC top-level; sem refs no ArchR runtime | +| `/storage/recordings` | 0 | mesmo | +| `/storage/downloads` | 0 | mesmo | +| `/storage/music`, `/storage/pictures`, `/storage/videos`, `/storage/tvshows` | 0 | mesmo (Kodi media dirs, não usado) | +| `/storage/.ssh` | 4 | **no-op: já é FHS-correto** | + +**Sobre `/storage/.ssh`:** o `add_user root` em `busybox/package.mk` define `$HOME=/storage` para o usuário root. Isso significa que `/storage/.ssh` literalmente é `$HOME/.ssh` para o único usuário do sistema, que é FHS-correto por definição. Mudar para `/root/.ssh` exigiria primeiro mudar o `$HOME` de root para `/root`, o que afeta `cd ~`, scripts que assumem cwd no login, etc — escopo de mudança de modelo de usuário, fora de F6. + +**Sem migration script de dados.** O substrato (`/storage/roms`) não muda fisicamente: o bridge symlink resolve para o mesmo dir. ROMs e saves do usuário não são tocados, sem risco. ### Fase 7 — Class Z: casos especiais e limpeza final @@ -232,4 +241,5 @@ Migration scripts ficam em `projects/ArchR/packages/archr/sources/post-update.d/ - [x] Fase 3 concluída (2026-06-23): logs reaproveitam `var-log.mount` (/var/log = /storage/.cache/log), update bridged via `/var/cache/archr/update`, overlayfs workdirs e bootloader handshake permanecem no backing path por constraint. - [x] Fase 4 concluída (2026-06-23): 9 state dirs (ssh, iwd, bluetooth, services, samba, connman, wireguard, tailscale, cron) movidos para paths Arch-convencionais via bridge symlinks. pacman db/cache e rfkill já eram bridges. `.local/share` realocado para F5. Detalhes na Fase 4. - [x] Fase 5 concluída (2026-06-23): umbrella bridges `/var/lib/archr/{config,data}` instalados pelo `archr` meta-package, vars `ARCHR_CONFIG` / `ARCHR_DATA` flipadas para os paths Arch. Refs hardcoded /storage/.config/ nos scripts ficam funcionais via compat. Detalhes na Fase 5. -- [ ] Fase 6..7 — não iniciadas. +- [x] Fase 6 concluída (2026-06-23): umbrella bridges `/var/lib/archr/{games,backup}` instalados, var `ARCHR_GAMES` flipada. /storage/.ssh marcado como no-op (é literalmente $HOME/.ssh do root). Detalhes na Fase 6. +- [ ] Fase 7 — não iniciada. diff --git a/projects/ArchR/packages/archr/package.mk b/projects/ArchR/packages/archr/package.mk index 224e15cbd6..e37ef2c5d3 100644 --- a/projects/ArchR/packages/archr/package.mk +++ b/projects/ArchR/packages/archr/package.mk @@ -87,6 +87,15 @@ EOF ln -sf /storage/.config ${INSTALL}/var/lib/archr/config mkdir -p ${INSTALL}/var/lib/archr ln -sf /storage/.local/share ${INSTALL}/var/lib/archr/data + + # Class E umbrella bridge. Games library has the largest surface in + # the codebase (117 files in projects/ArchR reference /storage/roms), + # same pattern as Class B: the rw overlay address stays /storage/roms, + # the Arch-friendly address /var/lib/archr/games is a symlink so + # ARCHR_GAMES and inspection tools see the FHS path. Per-script + # refactors can happen organically. + ln -sf /storage/roms ${INSTALL}/var/lib/archr/games + ln -sf /storage/backup ${INSTALL}/var/lib/archr/backup } post_install() { diff --git a/projects/ArchR/packages/archr/profile.d/010-archr-fhs b/projects/ArchR/packages/archr/profile.d/010-archr-fhs index 65c70917bc..5d64f796b9 100644 --- a/projects/ArchR/packages/archr/profile.d/010-archr-fhs +++ b/projects/ArchR/packages/archr/profile.d/010-archr-fhs @@ -36,8 +36,8 @@ export ARCHR_CACHE="${ARCHR_CACHE:-/storage/.cache}" # Class D: persistent state/data (FHS surface bridged to /storage/.local/share) export ARCHR_DATA="${ARCHR_DATA:-/var/lib/archr/data}" -# Class E: user games library and adjacent media (-> /var/lib/archr/games eventually) -export ARCHR_GAMES="${ARCHR_GAMES:-/storage/roms}" +# Class E: user games library (FHS surface bridged to /storage/roms) +export ARCHR_GAMES="${ARCHR_GAMES:-/var/lib/archr/games}" # Class F: log files (-> /var/log/archr eventually) export ARCHR_LOG="${ARCHR_LOG:-/storage/.cache/log}" diff --git a/projects/ArchR/packages/archr/sources/man/archr.7 b/projects/ArchR/packages/archr/sources/man/archr.7 index 6913b45349..7813e2aafb 100644 --- a/projects/ArchR/packages/archr/sources/man/archr.7 +++ b/projects/ArchR/packages/archr/sources/man/archr.7 @@ -102,10 +102,12 @@ a symlink into on the rw overlay. .TP .B ARCHR_GAMES -Games library root (ROMs, saves, screenshots, recordings). Currently -.IR /storage/roms ; -target -.IR /var/lib/archr/games . +Games library root (ROMs, saves, screenshots, recordings). Resolves +to +.IR /var/lib/archr/games , +a symlink into +.IR /storage/roms +on the rw overlay. .TP .B ARCHR_LOG Log files. Currently