Skip to content

Files - #3

Merged
colemancda merged 10 commits into
masterfrom
feature/files
Nov 16, 2026
Merged

colemancda merged 10 commits into
masterfrom
feature/files

Conversation

@colemancda

Copy link
Copy Markdown
Member

Implements AppRuntime's Files contract (Files.md) on Linux: the app's own directories, and the files in its bundle.

ExampleFiles on Linux

How

AppRuntime's RuntimeHost already has HostFiles, the whole contract over POSIX calls. LinuxFiles, in LinuxHost, decides where the app's directories are, configures HostFiles to answer on the host's main loop (MainLoop.post, from its queue), and registers it.

Directory LINUXAPPRUNTIME_CONTAINER set Otherwise (XDG)
documents <container>/Documents $XDG_DATA_HOME/<id>/Documents
data <container>/Data $XDG_DATA_HOME/<id>/Data
caches <container>/Caches $XDG_CACHE_HOME/<id>
temporary <container>/tmp $XDG_RUNTIME_DIR/<id>, or /tmp/<id>-<uid>
bundle the bundle's resources/ the same
  • <id> is the bundle identifier. It must name a single directory.
  • Defaults. XDG_DATA_HOME and XDG_CACHE_HOME fall back to ~/.local/share and ~/.cache when unset or relative, as the spec says.
  • temporary is always the app's own, since HostFiles empties it at every start.
  • Failures. If the directories can't be decided (no HOME, a bad identifier, a relative container), the host logs why, and every operation fails through its callback.
  • PortMaster ports set LINUXAPPRUNTIME_CONTAINER="$GAMEDIR/conf", where ports keep what's theirs.
  • Registration. The host app registers the module, and the packager checks apps against the contract.

Tested

On Debian 13 in Docker, all suites pass.

  • LinuxFilesTests, 5 tests:
    • XDG directories, with their variables and defaults;
    • a container, including a relative one refused;
    • identifiers that can't name a directory;
    • the contract end to end on MainLoop.shared: a bundle read, a replace and an append, list, attributes, a copy out of the bundle, a write to the bundle refused (readOnly), and a path that escapes refused (invalidPath).
  • The other suites: Host 12, LinuxUI 43 (1 skipped, as before), Packager 21, Graphics 10, WebKit 13.

End to end: AppRuntime's ExampleFiles was built as a linux-arm64 slice with a welcome.txt resource. It ran in linux-app-host with a container holding two notes, and the screenshot above is the result: the welcome text from the bundle, and the notes listed from documents/notes.

Not in this PR

  • Defaults, which AppRuntime added next to it (HostDefaults, FileDefaultsStorage). It can go in the same Data directory.
  • A launcher sandbox that would bind /data (AppRuntime's §7.8). Such a launcher would pass that path as the container.

@colemancda
colemancda merged commit e2648c9 into master Nov 16, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant