Mirror packages
Portable ROM packages
A project publishes one ROM zip. A mirror repackages that same ROM for each desktop, with the flashing tool for that desktop beside it. This page explains what is in those files and how a download from the firmware archive lands on the right one.
What a mirror package is
Flashing a ROM needs a tool that can talk to the player over USB. The tool is different on Windows, macOS, Intel Linux and ARM64 Linux, and a single ROM zip cannot carry all four. A mirror repository takes each release of a project, unpacks the ROM, and publishes one archive per platform with the matching tool inside.
Every package holds the same ROM. What changes is the tool beside it, which is why the archive for your computer is the one to download rather than the project's original zip.
How the archive picks one for you
A project names its mirror in slidia_manifest.xml, on the portable_zips attribute, written as author/repo:
<package name="Rockbox" repo="rockbox-y1/rockbox" portable_zips="y1-community/rockbox-mirror" device="Y1" />
When you click a ROM zip on the firmware page, the page reads that mirror's index.json, looks for the same release tag and the same ROM file inside it, and keeps only the entry built for your operating system and processor. The mirror's own GitHub release is then checked to confirm the file exists and is not an empty placeholder. If any of that fails, the click keeps the project's original zip, which is always a real file.
The file is saved under the release's own name, so the mirror's rom_y2-linux-arm64.zip arrives in your Downloads folder as rom_y2.zip. You can see the same choice without clicking anything by hovering the link, or from the release page at release_view.html, which lists a software install zip per platform next to the original file.
The package names
Mirrors follow one naming pattern, with the release's own file name at the front and the platform at the end:
| Name | Platform |
|---|---|
<rom>-windows.zip | Windows 10 and 11 on Intel or AMD |
<rom>-windows-arm64.zip | Windows on ARM |
<rom>-windows-legacy.zip | Windows XP through 8.1, and 32-bit Windows, where the current application cannot run |
<rom>-macos.zip | macOS on Intel and Apple silicon |
<rom>-linux.zip | Linux on Intel or AMD |
<rom>-linux-arm64.zip | Linux on ARM64, including Raspberry Pi and ARM laptops |
Each mirror publishes the list of platforms it builds for in its own index.json, so the exact set can differ between mirrors. Where a platform is missing, the original ROM is served instead.
Running the executable inside a package
Unpack the archive into its own folder and keep the folder together. The tool reads files beside itself, so a lone executable moved out of the folder will not find its scatter file or its payload.
- Windows: unzip the archive, open the folder, and run the tool's
.exein it. Windows may warn about an unsigned program the first time. - macOS: unzip the archive and open the tool in it. If macOS blocks the first launch, approve it in System Settings, Privacy & Security, with Open Anyway.
- Linux: unpack the archive, then make the tool executable and run it:
unzip rom_y2-linux-arm64.zip -d rom_y2 cd rom_y2 chmod +x ./* ./flash_tool
- Then: point the tool at the ROM in the same folder, choose Firmware Upgrade or Download Only, power the player off, and connect it only when the tool asks.
The executable's own name varies between mirrors. List the folder first, and run the program in it rather than a name taken from this page.
Making an AppImage from a software install zip
An AppImage is an AppDir packed into one file, and an AppDir is a folder with an AppRun entry point, a desktop entry and an icon. A software install zip already holds the program, so it can be wrapped.
- Unpack the archive into a folder, for example
AppDir. - Add
AppDir/AppRun, an executable script that starts the tool with the ROM beside it:#!/bin/sh here=$(dirname "$(readlink -f "$0")") exec "$here/flash_tool" "$@"
- Add a desktop entry at
AppDir/innioasis-flash.desktopand an icon beside it, so the file has a name and a picture in a file manager. - Pack the folder:
appimagetool AppDir Innioasis-Flash.AppImage
Do this on the processor you are packaging for. An AppImage built on an ARM64 machine runs on ARM64 machines, and the Intel and AMD package has to be built on an Intel or AMD machine.
Building the application itself, rather than wrapping a package, is covered on AppImages, tarballs and software install zips.
When a package does not appear
A mirror builds after the project publishes, so a release that appeared minutes ago may not have its packages yet. The archive serves the project's original zip in that case, and the software install zip appears once the mirror has published it.
A ROM that is listed in the feeds but not in the manifest has no mirror at all. Its row downloads the project's own zip, which is the only file that exists for it.