mirror of
https://github.com/Abdess/retroarch_system.git
synced 2026-11-22 01:27:52 -06:00
chore: merge site and docs batch
This commit is contained in:
commit
4ee0fd67a2
48 files changed
+1366
-332
No files matched your search
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 |
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
Reference in new issue
Block a user