docs: regenerate the README

fix: retry a file list the network cut short
fix: check --target for every platform first
2026-10-18 09:23:26 -05:00 · 2026-10-18 16:00:44 +02:00 · 2026-10-18 15:40:59 +02:00 · 2026-10-18 15:39:49 +02:00 · 2026-10-18 15:35:45 +02:00 · 2026-10-18 15:31:28 +02:00
570 changed files with 370527 additions and 165956 deletions
@@ -39,6 +39,11 @@ body:
        - EmuDeck
        - Lakka
        - RetroPie
        - RetroDECK
        - RomM
        - ROCKNIX
        - BizHawk
        - MiSTer FPGA
        - Other
    validations:
      required: true
@@ -8,26 +8,24 @@ on:
      - "emulators/**"
      - "provenance/**"
      - "wiki/**"
-      # Every script the build runs or imports (tests/test_workflow_paths.py).
+      # Every script the build runs or imports, and no other
      # (tests/test_workflow_paths.py).
      - "scripts/artifacts.py"
      - "scripts/auto_fetch.py"
      - "scripts/common.py"
      - "scripts/cross_reference.py"
      - "scripts/crypto_verify.py"
-      - "scripts/deterministic_zip.py"
+      - "scripts/derivations.py"
      - "scripts/dumpcatalog.py"
      - "scripts/generate_pack.py"
      - "scripts/generate_readme.py"
      - "scripts/generate_site.py"
      - "scripts/hashing.py"
      - "scripts/largefiles.py"
-      - "scripts/list_platforms.py"
+      - "scripts/mkdocs_hooks.py"
      - "scripts/nativemode.py"
      - "scripts/packextras.py"
      - "scripts/packpaths.py"
      - "scripts/packreadme.py"
      - "scripts/packresolve.py"
      - "scripts/packverify.py"
      - "scripts/profile_sync.py"
      - "scripts/provenance_report.py"
      - "scripts/refresh_data_dirs.py"
@@ -39,7 +37,6 @@ on:
      - "scripts/siterender.py"
      - "scripts/sitesources.py"
      - "scripts/sitewrite.py"
      - "scripts/slot.py"
      - "scripts/slots.py"
      - "scripts/split_pack.py"
      - "scripts/truth.py"
@@ -50,12 +47,12 @@ on:
      - "scripts/verify.py"
      - "scripts/ziptools.py"
      - "schemas/**"
      - "tests/**"
      - "docs_assets/**"
      - "install/**"
      - "install.py"
      - "database.json"
      - "release.json"
      - "derivable.json"
      - "mkdocs.yml"
      - ".github/workflows/deploy-site.yml"
  workflow_dispatch:
@@ -117,17 +117,66 @@ jobs:
      - name: Validate platform configs and emulator profiles
        run: python scripts/validate_schemas.py --source-only
-  run-tests:
+  # A profile written from a clone can cite lines that do not hold the value
  # it declares; schemas and tests pass it. Each profile a change adds is
  # confronted with its upstream, both roads into main. An edited profile is
  # not held to it: the backlog of older refs is reviewed by hand.
  check-new-profiles:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
        with:
          fetch-depth: 0
      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7
        with:
          python-version: "3.12"
      - name: Install dependencies
-        run: pip install pyyaml "jsonschema[format-nongpl]==4.26.0"
+        run: pip install pyyaml
      - name: Confront added profiles with their upstream
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BEFORE: ${{ github.event.before }}
        run: |
          # A pull request is checked out as a merge commit whose first
          # parent is the base; a push names the commit it moved main from.
          if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then
            base=HEAD^1
          elif [ -z "$BEFORE" ] || [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
            echo "first push of the branch: no base to diff against"
            exit 0
          else
            base=$BEFORE
          fi
          status=0
          for file in $(git diff --name-only --diff-filter=A "$base" HEAD -- 'emulators/*.yml'); do
            name=$(basename "$file" .yml)
            echo "::group::$name"
            python scripts/profile_sync.py --emulator "$name" --strict || status=1
            echo "::endgroup::"
          done
          exit $status
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
      # install.py stays on Python 3.8: the suite runs it end to end under a
      # real 3.8 interpreter, which import-only and grammar checks miss. The
      # last version listed is the default python.
      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7
        with:
          python-version: |
            3.8
            3.12
      # markdown: the site validation test renders a wiki line to prove the
      # heading guard's premise, and skipped on every run without it.
      - name: Install dependencies
        run: pip install pyyaml "jsonschema[format-nongpl]==4.26.0" "markdown==3.10.2"
      # The exporter fidelity cases compare what we hand back against the
      # file each platform publishes, so they need those files. They skip
@@ -137,8 +186,21 @@ jobs:
        continue-on-error: true
        run: python scripts/export_native.py --all --fetch --output-dir "$RUNNER_TEMP/native"
      # A pack built without its data directories exits non-zero: it is not
      # the pack a user gets. Tests that build packs need the same trees a
      # release build has, as deploy-site.yml fetches them.
      - name: Fetch the data directories
        run: python scripts/refresh_data_dirs.py
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Run test suite
-        run: python -m unittest discover tests -v
+        # No test downloads a release asset: 252 MB files fetched into the
        # shared cache filled the runner's disk and changed what later tests
        # resolved. The download tests mock the network and clear it.
        env:
          RETROBIOS_OFFLINE: "1"
        run: python -m unittest discover -s tests -t . -v
  label-pr:
    runs-on: ubuntu-latest
@@ -41,11 +41,20 @@ Full walkthrough: [profiling guide](https://abdess.github.io/retrobios/wiki/prof
 ## Before opening a PR
 The checks CI runs on a pull request (Python 3.12 or newer):
 ```bash
-python -m unittest discover tests
+pip install pyyaml "jsonschema[format-nongpl]"
-python scripts/pipeline.py --offline
+python scripts/validate_pr.py --changed          # the BIOS files the branch adds
 python scripts/validate_schemas.py --source-only # profiles and platform files
 python -m unittest discover -s tests -t .
 ```
 The full pipeline is not needed for a contribution: it rebuilds every pack
 (about 35 GB in `dist/`) and needs the data directories fetched first
 (`python scripts/refresh_data_dirs.py`), which is why maintainers run it
 before a release.
 ## PR validation
 CI computes SHA1/MD5/CRC32 for every new file, checks them against the platform
@@ -32,7 +32,7 @@ The script auto-detects your platform, downloads only missing files, and verifie
 ## Download BIOS packs
-One pack per platform, and it holds everything the platform runs: its own BIOS list plus every file its emulator cores load. Pick your platform, download the ZIP, extract to the BIOS path. The installer above does the same file by file, and `--target` narrows it to one machine; for a region or a bare minimum, build your own pack below.
+One pack per platform, and it holds everything the platform runs: its own BIOS list plus every file its emulator cores load. Pick your platform, download the ZIP, extract to the BIOS path. The installer above does the same file by file. At a terminal it asks whether to install everything or to choose systems, cores and regions, and `--system`, `--core`, `--region` and `--target` make the same choice without questions; for a bare minimum, build your own pack below.
 Files is how many the pack holds once extracted, the figure a file manager shows for the folder. It differs from one platform to the next because a pack carries only what that platform's emulators load. The size is what the files occupy once extracted; the ZIP itself downloads smaller.
 A pack over 2 GB comes in several parts, and every part is needed. How to open them depends on their name:
@@ -68,17 +68,17 @@ These are the files an emulator loads from disk instead of carrying inside itsel
 Each file is checked the way your platform checks it. Most compare a checksum, the fingerprint of a file's contents, which catches a corrupt or unexpected copy. RetroArch, Lakka and RetroPie only look for the filename, because that is all their code does: the Coverage table says which applies to you. Independently of that, the collection records five fingerprints per file, and wherever an emulator's code states an expected size or hash, that value is read from its source and rechecked here.
- **392 files** the platforms' emulators load are still to be found, and 51 more cannot be sourced at all (per-user keys, user-filled slots, dumps nobody has made); both are named in the [gap analysis](https://abdess.github.io/retrobios/gaps/)
+- **425 files** the platforms' emulators load are still to be found, and 55 more cannot be sourced at all (per-user keys, user-filled slots, dumps nobody has made); both are named in the [gap analysis](https://abdess.github.io/retrobios/gaps/)
 - **12 platforms** supported with platform-specific verification
- **506 emulators** profiled from source (RetroArch cores + standalone)
+- **530 emulators** profiled from source (RetroArch cores + standalone)
- **546 systems** handled by those emulators (NES, SNES, PlayStation, Saturn, Dreamcast, ...)
+- **550 systems** handled by those emulators (NES, SNES, PlayStation, Saturn, Dreamcast, ...)
- **19,002 files in the collection**, each with its SHA1, MD5, SHA256, CRC32 and Adler-32 fingerprints: 5,266 system files, 2,808 arcade ROM sets, 10,928 game and engine data files. That is every platform and emulator together, so no pack holds them all: each carries what its own emulators load, counted in the download table
+- **19,079 files in the collection**, each with its SHA1, MD5, SHA256, CRC32 and Adler-32 fingerprints: 5,337 system files, 2,813 arcade ROM sets, 10,929 game and engine data files. That is every platform and emulator together, so no pack holds them all: each carries what its own emulators load, counted in the download table
- **562 of 5,266 system files** matched to dump-preservation catalogs (No-Intro, Redump, TOSEC); arcade sets and engine data fall outside what those catalogs index
+- **562 of 5,337 system files** matched to dump-preservation catalogs (No-Intro, Redump, TOSEC); arcade sets and engine data fall outside what those catalogs index
- **16687 MB** total collection size
+- **16755 MB** total collection size
 ## Supported systems
-NES, SNES, Nintendo 64, GameCube, Wii, Game Boy, Game Boy Advance, Nintendo DS, Nintendo 3DS, Switch, PlayStation, PlayStation 2, PlayStation 3, PSP, PS Vita, Mega Drive, Saturn, Dreamcast, Game Gear, Master System, Neo Geo, Atari 2600, Atari 7800, Atari Lynx, Atari ST, MSX, PC Engine, TurboGrafx-16, ColecoVision, Intellivision, Commodore 64, Amiga, ZX Spectrum, Arcade (MAME), and 512+ more.
+NES, SNES, Nintendo 64, GameCube, Wii, Game Boy, Game Boy Advance, Nintendo DS, Nintendo 3DS, Switch, PlayStation, PlayStation 2, PlayStation 3, PSP, PS Vita, Mega Drive, Saturn, Dreamcast, Game Gear, Master System, Neo Geo, Atari 2600, Atari 7800, Atari Lynx, Atari ST, MSX, PC Engine, TurboGrafx-16, ColecoVision, Intellivision, Commodore 64, Amiga, ZX Spectrum, Arcade (MAME), and 516+ more.
 Full list with per-file details: **[https://abdess.github.io/retrobios/](https://abdess.github.io/retrobios/)**
@@ -86,18 +86,18 @@ Full list with per-file details: **[https://abdess.github.io/retrobios/](https:/
 | Platform | On its BIOS list | Files its emulators load | Checked by |
 |----------|-----------------:|-------------------------:|------------|
-| Batocera | 353/353 | 12,287/12,718 | MD5 hash |
+| Batocera | 353/353 | 12,353/12,787 | MD5 hash |
-| BizHawk | 118/118 | 800/801 | SHA1 hash |
+| BizHawk | 118/118 | 754/755 | SHA1 hash |
-| EmuDeck | 168/168 | 430/432 | MD5 hash |
+| EmuDeck | 168/168 | 451/453 | MD5 hash |
-| Lakka | 526/526 | 5,256/5,286 | file presence |
+| Lakka | 532/532 | 5,266/5,296 | file presence |
 | MiSTer FPGA | 81/81 | - | MD5 hash |
-| ROCKNIX | 38/38 | 5,695/5,725 | MD5 hash |
+| ROCKNIX | 38/38 | 5,925/6,002 | MD5 hash |
-| Recalbox | 351/351 | 2,721/2,729 | MD5 hash |
+| Recalbox | 351/351 | 2,787/2,805 | MD5 hash |
-| RetroArch | 526/526 | 5,256/5,286 | file presence |
+| RetroArch | 526/526 | 5,278/5,308 | file presence |
-| RetroBat | 348/348 | 11,875/12,305 | MD5 hash |
+| RetroBat | 348/348 | 7,260/7,419 | MD5 hash |
-| RetroDECK | 2,008/2,008 | 5,387/5,437 | MD5 hash |
+| RetroDECK | 2,008/2,008 | 5,326/5,376 | MD5 hash |
-| RetroPie * | 526/526 | 9,171/9,313 | file presence |
+| RetroPie * | 532/532 | 9,196/9,338 | file presence |
-| RomM | 381/381 | 746/752 | MD5 hash |
+| RomM | 383/383 | 773/780 | MD5 hash |
 Each fraction is what the pack has over what is needed, counting required and optional files alike since both ship. The first column is the BIOS list the platform publishes. The second counts files its emulators load that this list never mentions, found by reading their source code, and it is routinely several times larger. A short fraction means files are still missing, and they are named in the [gap analysis](https://abdess.github.io/retrobios/gaps/).
 That second number is a floor, not a ceiling: an emulator that accepts any file handed to it names none in its code, so nothing there can be counted.
@@ -131,7 +131,7 @@ python scripts/verify.py --emulator flycast
 python scripts/verify.py --platform retroarch --verbose  # emulator ground truth
 ```
-Only dependency: Python 3 + `pyyaml`.
+Requires Python 3.12 and `pyyaml`. The one-line installer alone runs on Python 3.8.
 ## Documentation site
@@ -141,7 +141,7 @@ The [documentation site](https://abdess.github.io/retrobios/) provides:
 - **Per-emulator profiles** with source code references for every file
 - **Per-system pages** showing which emulators and platforms cover each console
 - **Gap analysis** identifying missing files and undeclared core requirements
- **Cross-reference** mapping files across 12 platforms and 506 emulators
+- **Cross-reference** mapping files across 12 platforms and 530 emulators
 - **Versioned data access** through JSON, CSV and SQLite exports with published SHA-256 checksums
 ## How it works
@@ -180,4 +180,4 @@ The scripts and tooling are released under the [MIT License](LICENSE).
 The BIOS and firmware files are not covered by that license: they are third-party system software, preserved and provided for personal backup, archival, and interoperability with emulation software. [NOTICE](NOTICE) sets out their status and how to ask for a file to be removed.
 The reasoning, and where it is weakest, is in the [FAQ](https://abdess.github.io/retrobios/wiki/faq/#is-this-legal).
-*Auto-generated on 2026-10-09T23:59:06Z*
+*Auto-generated on 2026-10-18T13:59:53Z*