chore: merge site and docs batch

This commit is contained in:
Abdessamad Derraz committed 2026-11-05 14:37:10 +01:00
commit 4ee0fd67a2
48 files changed
+1366 -332

No files matched your search

+1 -1
View File
@@ -423,7 +423,7 @@ launchers:
| `fails_scope` | `emulator` when the failure needs every record of the emulator to come up empty |
| `depends_on_option` | Options or conditions that decide whether the record applies |
| `device` | Devices whose shipped config the record reads, set only where a package ships configs that differ between devices |
| `source_ref` | `path:lines` at the revision `source` pins |
| `source_ref` | `path:lines` in the repository and at the revision `source` pins, which the site links |
Batocera's generators are read with `ast`, RetroBat's C# generators as text.
ROCKNIX and EmuDeck launch from shell scripts and configs shipped with each
+25 -5
View File
@@ -169,11 +169,31 @@ The emulator's source code serves as ground truth for what files are needed,
what names they use, and what validation the emulator performs. Platform YAML
configs are scraped from upstream and record what each platform declares. A
list kept by hand can lag behind an emulator release. The emulator profiles complement the
platform data by documenting what the code actually loads. When the two disagree,
the profile takes precedence for pack generation: files the code needs are included
even if the platform does not declare them. Files the platform declares but no
profile references are kept as well (flagged during cross-reference), since the
upstream may cover cases not yet profiled.
platform data by documenting what the code actually loads. Files the code needs
are included even if the platform does not declare them. Files the platform
declares but no profile references are kept as well (flagged during
cross-reference), since the upstream may cover cases not yet profiled.
### When both layers claim one destination
A platform and an emulator profile can each name a different file for the same
place in the BIOS folder: RetroBat puts its own `ATARIOSB.ROM` at
`bios/ATARIOSB.ROM`, where atari800 reads another dump. A claim counts only when
it rests on content or on the path. A file found by its name alone claims
nothing. The pack then answers to whoever asked for it:
- A **platform pack** must leave the frontend's own check green, since a user
reading red concludes the pack is broken. Where the frontend only looks for
the name (`existence`), the emulator's file satisfies both, and the pack takes
it. Where the frontend checks an MD5 or SHA1, one path cannot hold both
answers: the platform's file stays, and the loss is reported. Only the
platform's own list can change what its frontend accepts there.
- A pack built with `--emulator` answers to that emulator, and takes its file.
`scripts/slots.py` prints each contested destination and the reason for its
winner (`python scripts/slots.py --platform retrobat`). `generate_pack.py` and
`verify.py` both decide through `slots.arbitrate()`, so the pack and the report
agree.
A platform YAML is regenerated by its scraper and never edited by hand: an
edit would be lost at the next scrape, and the file would stop describing the
+2 -2
View File
@@ -34,7 +34,7 @@ option.
## Zip or unzip? { #zip-or-unzip }
Unzip it into the folder your setup's page names. Keep
Unzip into the folder your setup's page names. Keep
inner ZIPs zipped, like `neogeo.zip`.
## Does a BIOS work on every setup?
@@ -57,7 +57,7 @@ Game sets must match the emulator's version:
- It stops if the installer does not match its expected fingerprint, and
checks each file.
- It writes in your BIOS folder, and some emulators' save folder.
- It fills the BIOS folder, some save folders and a games cache.
- It never touches games or saves.
- It keeps each file it replaces in `retrobios-backup`, for `--restore`.
+5 -1
View File
@@ -865,7 +865,9 @@ it. So does an arcade set the core does not know. **Only what starts**
(`--required-only`) leaves out the files the cores mark optional.
The games are read without hashing whole discs, and a cache keeps what was
read, so a second run over the same card reads only new files. Offline, with
read, so a second run over the same card reads only new files. It is a
`retrobios` folder in the system's cache folder (`RETROBIOS_CACHE`, see
[Environment overrides](#environment-overrides)), written by `--dry-run` too. Offline, with
no games index on this machine, the run keeps every file and says so.
### Firmware without game data
@@ -1826,6 +1828,8 @@ RetroArch folder that holds only `scph5501.bin`, in the order written:
| `RETROBIOS_PAD` | The buttons a handheld launcher's mapper sends to the full screen (`gptokeyb`, `gptokeyb_muxterm`, `muxterm`, `evmapy`, `miyoo`), so its hints name them. See [On a handheld](#on-a-handheld-the-retrobios-port) |
| `RETROBIOS_IDLE_EXIT` | Seconds the full screen waits for a first button, counted while nothing runs. With none pressed, it closes with exit status 2, as a quit, or with the code of the error or result screen it closed on |
| `RETROBIOS_NO_MOUSE` | Set to any value but `0` or an empty one: the full screen never asks the terminal for clicks, and the mouse selects text everywhere as it does outside the installer |
| `RETROBIOS_CACHE` | The folder that keeps the games index and what a run read of the games, for the next run. Defaults to `retrobios` in `$XDG_CACHE_HOME` (else `~/.cache`), `~/Library/Caches` on macOS, `%LOCALAPPDATA%` on Windows. Deleting it loses nothing |
| `RETROBIOS_DEBUG` | Set to anything: says why the games index could not be fetched or a cache file not written |
| `HTTPS_PROXY`, `NO_PROXY` | Honoured for every download through the standard library's default proxy handling: one names the proxy, the other the hosts to reach directly |
## When something goes wrong
+8 -6
View File
@@ -383,8 +383,9 @@ A few field conventions that protect the toolchain:
string (like emuscv's `635a978...` in memory.cpp), that goes in. If
the source embeds ROM data as byte arrays (like ep128emu's roms.hpp),
the bytes can be extracted and hashed. If the source performs no hash
check at all, the hash is omitted from the profile. The .info or docs
may list an MD5, but source confirmation makes it more reliable.
check at all, the hash is omitted from the profile. An MD5 the .info or
the docs alone give is not written: pokketstation's `.info` names a
revision no copy in circulation has.
A data file the build generates is rebuilt from the tree and compared
byte for byte with the official release before its hash is recorded
(PrBoom+ builds `prboom-plus.wad` with its own tool). A firmware URL that
@@ -493,9 +494,10 @@ and DSP firmware through different code paths. Checking the actual
code for each core avoids assumptions based on a related profile.
**Code over docs.** Wiki pages and README files sometimes reference
files from older versions or a different fork. If the source code
does not load a particular file, it can be left out of the profile
even if documentation mentions it.
files from older versions or a different fork. A file the source code
does not load is left out of the profile, even when documentation or the
`.info` mentions it (desmume2015's `.info` lists three firmware files its
code never opens).
## YAML field reference
@@ -517,7 +519,7 @@ reports the profile as uncheckable, and the CI job that runs
| `upstream` | no | original emulator repository URL |
| `profiled_date` | see above | date of source analysis. Quote it, or YAML parses it as a date object |
| `core_version` | every profile (`tests/test_version_basis.py`) | the version of the code at the pin, read where `version_basis` says. null when the code states none, never `Git`, `SVN` or a branch name. A dict keyed by build mode when the builds differ |
| `version_basis` | every profile (`tests/test_version_basis.py`) | where `core_version` is read: `file` (`path`, `pattern`, optional `format`), `tag` (the nearest `tag` in the pin's history and its `distance`, `core_version` in git describe's form), `alias` (`of`), `package` (`artifact`, the APK or binary read) or `none`. `repo` names `upstream` when the version is the upstream tree's. `profile_sync --verify-version` reads it again, and a pin advance rewrites `core_version` from it |
| `version_basis` | every profile (`tests/test_version_basis.py`) | where `core_version` is read, by `kind`: `file` (`path`, `pattern`, optional `format`, and `url` with its `commit` for a file outside the profile's repositories, such as the package file of a build a platform ships), `tag` (the nearest `tag` in the pin's history and its `distance`, `core_version` in git describe's form, `match` the glob a tag must fit), `alias` (`of`), `package` (`artifact`, the APK or binary read, `url` where it was obtained), `none` (the code states no version: `core_version` null) or `unverified` (no reading could be made: `core_version` stays as written and is reported unconfirmed, `why` says why: `no_pin`, `host_unsupported`, `host_gone`, `host_unreachable`, `pin_off_branch`, `no_artifact`, `no_source`). `repo` names `upstream` or `source_mirror` when the version is that tree's. `profile_sync --verify-version` reads it again, and a pin advance rewrites `core_version` from it |
| `source_commit` | see above | commit SHA of `source` the code was read at. Anchors every `source_ref` line number |
| `upstream_commit` | no | same, for `upstream` |
| `pin_frozen` | no | why `source_commit` is held on purpose rather than followed. The profile is then judged against its own revision, like one pinned to a superseded tag |
+6 -3
View File
@@ -107,9 +107,11 @@ RetroDECK: 2007/2008 OK, 1 untested [md5]
UNTESTED (required): nintendo-ds/dsifirmware.bin: declared hash contradicted by the local file
DISCREPANCY: nintendo-snes/sgb2.boot.rom: RetroDECK says OK but supersnes9x says size mismatch: got 524288, accepted [256]
supersnes9x [size]
Core files: 1795 in pack, 0 required missing, 27 optional missing (--verbose lists them)
Core files: 1795 in pack, 1 required missing, 27 optional missing (--verbose lists them)
Core files held but not packed: 154 (installed with its emulator)
MISSING (required): FinalBurn Neo needs sfiii2a.zip (1 file)
Game data: 5099 in pack, 38 missing (--verbose lists them)
Game data held but not packed: 30 (installed with its emulator)
No external files: 78 cores (--verbose lists them)
Ground truth: 96/2008 files have emulator validation (5%)
439 platform-only (no emulator profile)
@@ -117,8 +119,9 @@ RetroDECK: 2007/2008 OK, 1 untested [md5]
The run prints more `DISCREPANCY` lines than this excerpt shows. The core
and game data lines count what the emulator cores add beyond the platform's
own list. A file held but not packed is left out for the reason in parentheses, each
reason with its count when the files have several.
own list. A required core file the collection lacks is named under them, with
the emulator that needs it. A file held but not packed is left out for the
reason in parentheses, each reason with its count when the files have several.
`--verbose` also lists the passing entries that an emulator validates, with
the check and the source lines behind it:
+11 -14
View File
@@ -528,7 +528,8 @@ prose that the same pass would have moved is not reported as blocked. Drop
A moved pin also moves the links the site draws into the cited sources: a
path is linked only where `website/src/data/source-paths.json` records it in
the tree the profile pins. Refresh that record after a pin moves or a profile
is added, and commit it with the profiles:
is added, and commit it with the profiles. Every tree a run tries is recorded,
read or not, so `check_freshness.py` reports a pinned tree the record lacks:
```bash
python scripts/sitesources.py --fetch
@@ -593,9 +594,11 @@ shows added, removed and renamed files in the directories the refs point at.
says where it is read: a pattern in one file (`file`), the nearest tag and
the commits after it (`tag`, written in git describe's form), the profile an
alias follows (`alias`), an artefact read outside any source tree
(`package`), or `none` when the code states nothing, with `core_version`
null. `--verify-version` reads it again at the pin and exits 1 on a
difference or a missing basis. `--set-version` writes what the code states.
(`package`), `none` when the code states nothing, with `core_version`
null, or `unverified` when no reading can be made (a forge gone, a host the
tools cannot read, no artefact to read): `core_version` stays as written,
reported unconfirmed, and `why` names the reason. `--verify-version` reads
it again at the pin and exits 1 on a difference or a missing basis. `--set-version` writes what the code states.
A pin advance reads the version at the new pin in the same write and is
refused when it cannot: a package version moves by hand.
@@ -777,7 +780,6 @@ until a report without one. Exit codes: 0 for `ok`,
|-----|----------|--------------|
| `nightly` | 02:00 | `check_freshness.py --json` saved to a file, `refresh_stale.py --findings` on its `data` and `catalogs` rows, the MAME and FBNeo hash scrapers, then `pipeline.py --offline` as the gate. `database.json` and `install/*.json` are computed a second time and compared. Commits the hash profiles, the recipes and the regenerated records |
| `assets` | 04:30 | `sync_release_assets.py`, as a dry run |
| `campaign` | 06:00 | `campaign.py run --budget 150m` once the host is idle (up to two hours of waiting), gated by `campaign.py gate`. Commits the records, findings and pass line, then the profile fields the runs proved |
| `bios-integrity` | Sunday 08:30 | `bios_integrity.py --apply --json` in the main checkout, once the host is idle (up to four hours of waiting). Its report is kept in the job's status |
| `cleanup` | 05:30 | `cleanup_disk.py --apply --hours 72` in the main checkout |
| `disk-check` | hourly | `cleanup_disk.py --check`, without the lock |
@@ -1057,7 +1059,6 @@ python scripts/campaign.py findings # what waits for review
python scripts/campaign.py review beetle_psx/sony-playstation/scph5501.bin/validation \
--status applied --set on_mismatch=warn --reason "logs the SHA1 and loads (libretro.c:853-860)"
python scripts/campaign.py gate # the checks behind a commit
python scripts/campaign.py install-timer # opt-in: writes the autorun units, enables nothing
```
| Step | What happens |
@@ -1113,10 +1114,10 @@ checks. The campaign's own `evidence:` writes do not count as a profile change.
| Guard | Rule |
|-------|------|
| Lock | The host-wide autorun lock. Under the `campaign` job, autorun holds it and says so with `RETROBIOS_AUTO_LOCK_HELD` |
| Lock | The host-wide autorun lock. When a caller already holds it, `RETROBIOS_AUTO_LOCK_HELD` says so |
| Probe lock | Not held by the pass: each core_probe it starts takes the host probe lock for its own run, so the pass and other measurements (pack_probe, a core_probe loop) interleave. Two campaign passes still exclude each other through the automation lock, since they share `.cache/campaign/state.json`. Do not wrap `campaign.py run` in `flock` |
| Environment | `core_probe.py`, git and `make` get autorun's allowlist, romfetch the same plus its `ROMFETCH_*` settings. None sees a token or a password |
| Sandbox | Fails closed: without a working bubblewrap the pass is `refused` (exit 3) and nothing third-party runs, every probe is started with `--require-sandbox`, and a build is refused. `--allow-unsandboxed` overrides. Under autorun the refusal raises the `job:campaign` alert |
| Sandbox | Fails closed: without a working bubblewrap the pass is `refused` (exit 3) and nothing third-party runs, every probe is started with `--require-sandbox`, and a build is refused. `--allow-unsandboxed` overrides |
| Load | Before each run, waits while the 1-minute load is above a quarter of the CPUs, up to `--max-load-wait` seconds, then the pass stops as `paused` |
| Disk | Below `--min-free-gb` (default 30) the pass stops as `paused` |
| Budget | No check starts after `--budget` |
@@ -1134,12 +1135,8 @@ and campaign tests, `validate_schemas.py --source-only`, then `verify.py
--emulator` and `generate_pack.py --emulator` for each changed profile. A file
that had uncommitted changes before the pass is left alone.
A maintainer starts each pass. Scheduling is opt-in: a contributor who wants a
schedule on their own machine installs the timer with `campaign.py
install-timer`, which writes the autorun units and enables nothing unless
`--enable` is passed. The `campaign` autorun job then runs a 150-minute pass
in the automation worktree, gates it with `campaign.py gate` and commits with
its own rules, pushing only with `--push`.
A maintainer starts each pass, for a question that names its profiles. No
autorun job runs it on a schedule.
`review` closes an open finding once someone has read the core's code at the
profile's pin. `--status applied` writes each `--set FIELD=YAML` into the