OpenROM Binaries (M5Devs/OpenROM-bins)

This repository holds metadata, scripts and GitHub workflows only. The pre-compiled binaries used by OpenROM are hosted on SourceForge (the openrom-binaries project) and are never committed to Git. Git holds manifest.json (the source of truth), checksums.sha256 and versions.json (both generated by scripts/gen_checksums.py), plus SOURCES.md (generated by scripts/gen_sources.py) and the automation that keeps them current.

1. Layout and URL schema

Binaries are addressed as {os}/{arch}/{file}. The supported platforms are windows/x86_64, linux/x86_64, linux/arm64, macos/x86_64, macos/arm64 and android/arm64-v8a.

https://downloads.sourceforge.net/project/openrom-binaries/{os}/{arch}/{file}

Example for Windows x86_64 chdman.exe:

https://downloads.sourceforge.net/project/openrom-binaries/windows/x86_64/chdman.exe

2. Consumer contract

• Paths are exactly the path values in manifest.json, i.e. {os}/{arch}/{basename}. Each platform entry also records sha256 and size.

• NKit is ONE file per platform: nkit (nkit.exe on Windows). There is no nkit/ subdirectory and no nkds; no sibling files are required.

• Checksums format: checksums.sha256 has one line per binary, sorted by path, in sha256sum format: 64 lowercase hex characters, two spaces, then the relative path.

• Download and verify with the provided scripts:

  ./scripts/fetch-bins.sh --os linux --arch x86_64 --target-dir ./bin

  .\scripts\fetch-bins.ps1 -Os windows -Arch x86_64 -TargetDir .\bin

  Both scripts download from downloads.sourceforge.net (override with OPENROM_BINS_BASE_URL), verify SHA-256 and size against manifest.json, and set the executable bit on Unix. Exit codes: 0 success, 1 invalid arguments or missing dependency, 2 manifest/checksum error or no matching tool, 3 download failed, 4 SHA-256 or size mismatch.

3. Pipeline

build-* / update-*  ->  publish-sourceforge.yml  ->  one manifest PR  ->  verify-sourceforge.yml
   (build or fetch)        (upload via rsync/SSH)     (commit hashes)       (re-download and compare)

• publish-sourceforge.yml — reusable workflow: uploads one artifact to SourceForge and opens/updates one manifest PR per run.
• build-saturn-patcher.yml — builds saturn-patcher from source for its platforms.
• build-xgdtool.yml — builds XGDTool from source for its platforms.
• fetch_android_bins.yml — fetches/builds the Android arm64-v8a binaries.
• update-chdman.yml — extracts chdman from the @emmercm/chdman-* npm packages.
• update-binary.yml — uploads a single operator-supplied binary.
• verify-sourceforge.yml — re-downloads published binaries and checks hashes.
• check-versions.yml / check-all-versions.yml — report newer upstream versions.
• ci.yml — runs manifest tests and the single-brace-expression guard.
• purge-history.yml — removes accidentally committed binary paths from history.

4. Trust model

• The checksums prove the bytes you download are the exact bytes the maintainer uploaded and that the manifest.json entry matches checksums.sha256.
• They do not prove the authenticity of the upstream project, that the binary was built from the claimed source, or that the SourceForge mirror was not tampered with. npm integrity is verified only in update-chdman.yml (the published tarball's dist.integrity); other tools are not verified against an upstream registry.

5. Required secrets

Publishing to SourceForge requires:

• SF_USER — SourceForge account username.
• SF_SSH_PRIVATE_KEY — SSH private key registered with the SourceForge account.

The pinned SSH host keys live in scripts/sourceforge_known_hosts and must be compared against SourceForge's published host-key fingerprints before use.

6. First use after merge

1. Add the SF_USER and SF_SSH_PRIVATE_KEY repository secrets.
2. Verify scripts/sourceforge_known_hosts against SourceForge's published fingerprints.
3. Run each build-* / update-* workflow once with dry_run=true.
4. Enable Allow GitHub Actions to create pull requests in repository settings, so publish-sourceforge.yml can open the manifest PR.
5. Run verify-sourceforge.yml to confirm the published hashes match.

7. Known limitations

• chdman is a legacy npm-package entry: no package/dist_integrity is recorded in the manifest, so validate_manifest.py --strict warns about it.
• nkit provenance is unverified (upstream-release, believed to come from the NKit CLI release zips); the binaries predate this manifest.
• saturn-patcher and xgdtool are built-from-source but unpinned until their first real build records a source_commit.
• The Android xdelta3 entry is not rebuilt: the upstream linux-arm64 asset is dynamically linked and would not run on Android.

License

Each tool is subject to its own upstream open-source license. See LICENSES/README.md and SOURCES.md.