Research: content that needs a different build per platform

[averageksp]

Research: content that needs a different build per platform

Raised on Discord on 2026-09-22 by Kiwi Shark, about gatOS: the mod needs a different build depending on the host OS, Windows or Linux. purrTTY has no such problem, so this is about content whose files differ per platform, not about the loader.

What the index has today

• compatibility.os says which platforms a release works on. It filters, it does not select.
• RFC 0067 covers per-platform launch, but only for a mod-loader's [provides], so StarMap can say it runs dotnet StarMap.dll on Linux. It says nothing about files that differ.
• A release has exactly one archive, with one sha256 and one size, which the watcher stamps and clients verify.
• RFC 0035 names the gap as unresolved question 5: "Per-platform install shapes. RFC 0031 has os; this section has nothing equivalent, and a loader whose layout differs on Linux currently cannot say so."

What an author can do today

Two listings on one repository. Ids gatOS and gatOS-Linux, each with its own compatibility.os. It works now: when a GitHub release carries several zips, the watcher takes the one named after the listing id, trying <id>.zip, <id>-<tag>.zip and <id>_<tag>.zip with the leading v stripped from the tag (tools/hosts.py, GitHubHost._asset). Anything it cannot match it reports instead of guessing.

Costs: two ids for one mod, two listing files, two forums links, and every release has to carry both assets or one listing fails to stamp.

One archive with both builds. Nothing in the index changes. Costs: every player downloads both, and it only works when the extra files are harmless or the mod picks at runtime.

Options

1. Per-platform install root inside one archive. The archive carries windows/ and linux/, and the install descriptor says which one is the install root on which platform. One release, one hash, one download, one listing. This is RFC 0035's question 5, and it is the smallest change: the watcher stamps what it already stamps, and only a manager's install step learns something new. Cost to the player: they download the other platform's files too.

2. Per-platform downloads inside one release. The release file carries a download per platform, each with its own url, hash and size. Players download only what they need. This is the largest change: it touches what a release is, so the watcher, the release checks, the snapshot and every client change with it. It also raises questions this discussion should not answer yet: is it still one release when two archives are stamped, what happens when a platform's asset is missing from one release, and how does a download count add up.

3. Leave it as it is and document the two-listing pattern as the supported answer.

What would help

• Other content with the same problem, or is gatOS the only case?
• For gatOS: would one archive with both builds be acceptable, or is the size a problem?
• Does anything else need per-platform files, for example native libraries next to managed code?

Option 1 looks like the cheapest thing that solves the actual case, and it closes an open question RFC 0035 already carries. Option 2 is worth it only if downloading the other platform's files is really a problem, which is a question about sizes rather than about the format.

[Maximilian-Nesslauer]

I took a look at the real archives of gatOS and purrTTY.

What gatOS ships today

The release tip-20260915-021843 carries gatOS-linux-...zip (96 MB) and gatOS-windows-...zip (138 MB).
I let Claude compare the two file by file:

• All 35 files of the Linux archive are also in the Windows archive, byte for byte the same.
• The Windows archive adds 113 files under qemu/win-x64/, about 42 MB compressed, which is the bundled QEMU.
• Nothing else differs.

@https://github.com/alex-sherwin as far as i undersand gatOS already decides at run time which QEMU it uses: QemuLocator takes the bundled qemu/win-x64/ on Windows and the system QEMU from the PATH on Linux and macOS.
So the Windows archive is already a universal build: on Linux the qemu/win-x64/ folder is simply never used.

purrTTY, from the same author, does the same thing already: its one archive carries libghostty-vt.so, libghostty-vt.dylib and ghostty-vt.dll side by side.

I first thought about how we handle loaders different per OS but the loader case is different

RFC 0067 lets a mod-loader say which file to start on which platform, StarMap.exe or dotnet StarMap.dll.
It selects a start file inside one archive and never selects files or archives, so it does not answer this question, and it is limited to loaders on purpose.

The options

Two listings (gatOS and gatOS-Linux) I would not recommend.
The id is the folder name, and the game takes a mod's id from its folder (Mod.MakeUsing), so these are two different mods to the game and to every dependency.
A mod that depends on gatOS finds nothing on Linux, and nothing stops both from being installed in one instance.
It also needs an authored [install] root in the second listing, because both archives hold a gatOS/ folder and a derived root has to match the listing id.

Option 1 (a per-platform install root in one archive) does not help gatOS.
The root selects one folder, so the 35 shared files would have to be in a windows/ and a linux/ folder each, and the archive would grow from 138 MB to about 234 MB.
Code can always decide at run time, as gatOS and purrTTY already do, so I do not see a case today that needs it.
RFC 0035 keeps this as its open question 5, which is the right place for it until a loader needs it.

Option 2 (a download per platform in one release) is the only one that saves a download.
For gatOS the saving is 42 MB for a Linux player.
It changes what a release is: the watcher, the release file, the checks, the snapshot, the download counts and every client.
It would also work on GitHub only, because SpaceDock keeps one file per version.

@https://github.com/alex-sherwin as long as there is only gatOS that needs it would not put the effort to do that yet but i think that it would make sense eventually.

If a second case come, handling an <id>-<os>.zip next to <id>.zip would make sense.

My proposal only for the temporary solution: option 3, but with one universal archive instead of two listings.
We document "one archive for all platforms, and the mod picks at run time" as the supported way, and come back to option 2 when a real case needs it.

What gatOS needs to be listed

None of this is about platforms, but it is what stops gatOS today:

1. A version in the tag. tip-20260915-021843 is not a version, so the watcher refuses it (RFC 0031, and RFC: Shorter version forms on a release tag #72 does not change that). v0.1.0-tip-20260915-021843 is valid SemVer, keeps the date, and sorts by it. A pre-release on GitHub stamps as a test release, so a player sees it only on a test channel.
2. One archive named after the listing. gatOS.zip or gatOS-<tag>.zip, which is the Windows archive of today. The watcher takes the archive named after the id and reports instead of guessing when it cannot match one.
3. compatibility.os, when gatOS is known not to run somewhere. os = ["windows", "linux"] makes a manager warn on macOS and still let the player install.
4. The system QEMU on Linux as an install step, for example steps = ["On Linux, install QEMU (qemu-system-x86_64) with your package manager."] under [install] (RFC 0035). FYI Borea does not show install steps to players yet, which Show the install and uninstall steps of a listing to the player Borea#560 adds.
5. purrTTY as a recommends dependency, if gatOS is meant to be used with it, once purrTTY is listed.