kmoody/libretro
1
0 Fork 0
mirror of https://github.com/Abdess/retroarch_system.git synced 2026-10-31 16:17:19 -05:00
Code Issues Packages Projects Releases Wiki Activity

chore: merge the region reference frames

Browse Source
This commit is contained in:
Abdessamad Derraz committed 2026-10-27 23:07:23 +01:00
2 parents adf5e1b2ad c639a1b3e5
commit e6f7ea8f07
794 files changed
+14502 -1807
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

wiki/first-install.md
+8 -6
View File
@@ -88,10 +88,12 @@ Arrows move, Enter chooses, Esc goes back, as A and B on a handheld.
## 3. Install
The next screen counts missing files and free space.
It counts missing files and free space.
Press Enter on **Install**. **Choose systems** keeps the consoles you
play.
**Game data** (only a game reads it) has its own row.
**Old card?** In a card reader, choose **Copy the BIOS files from your old
card or a folder**, then the card.
@@ -102,11 +104,11 @@ Esc or Ctrl+C stops, B on a handheld. Run again to resume.
## 5. Read the result
- **Done**: all files are in place.
- **Finished with errors**: run the command again. It retries only those.
- **Finished with errors**: run it again. It retries only those.
- **Finished with files missing**: run it again online.
- **Nothing installed**: the screen says why. See [If it stops](#if-it-stops).
For questions line by line (screen readers), add `--plain`.
For line-by-line questions (screen readers), add `--plain`.
## What the command does
@@ -129,8 +131,8 @@ All good:
## Undo
Files it replaces go to a `retrobios-backup` folder beside your BIOS folder.
The result says how to restore them.
Replaced files go to `retrobios-backup` beside your BIOS folder. The result
says how to restore them.
## If it stops
@@ -166,7 +168,7 @@ You cannot write there. Do what the message says.
### The card is full
Nothing was written. Free some space, or choose another folder.
Nothing was written. Free some space there.
### The game still does not start
wiki/installer.md
+149 -29
View File
@@ -176,7 +176,7 @@ install starts.
| Back | Esc, Backspace | B, Select (B alone with muxterm's own keys, where Select shows its keyboard) |
| Options | `o`, Tab | Y |
| Filter a long list | `/` then type, Enter on a lone match chooses it | muxterm: Select shows a keyboard. Elsewhere none (the setup list puts the SD cards after RetroArch) |
| Keys of the screen | `?`, F1 | |
| Keys of the screen | `?`, F1 (F1 alone while typing a filter, where the help lists the keys that do not type) | |
| Stop an install | Esc, `q`, Ctrl+C | B, Select+Start (B alone with muxterm's own keys) |
| Quit | `q`, Ctrl+C | B on the first screen |
| Pause, back with `fg` (Linux, macOS) | Ctrl+Z | |
@@ -197,10 +197,17 @@ progress, and a second one stops at once. Select+Start on a handheld ends the
installer with a signal (SIGTERM), which stops it the same way. Either way the
result says how many files were installed, and it stays printed in the terminal
once the screen closes, with the command that repeats the run. A run that failed
keeps its log and names it, and every other run leaves nothing behind.
keeps its log and names it, and every other run leaves nothing behind. A path
or a command on the result is never split inside a word: one longer than the
window takes a line of its own, which the terminal folds, and a command breaks
only between its arguments. Every path a run names is spelled the way its BIOS
folder was named, the backup folder and the save directory included
(`/sdcard/RetroArch` on Android, not the `/storage/emulated/0` it links to).
It opens only for an install, at a terminal of at least 40 columns and 12 rows
(a smaller window says so, with its size) whose `TERM` is set, is not `dumb`
(a smaller window says so, with its size, before the first question:
`The window is 39x12: questions come line by line (40x12 for the full
screen).`) whose `TERM` is set, is not `dumb`
and can draw it: where the terminal's description
(terminfo) has no way to move the cursor, or moves it with other sequences
than the ANSI ones the screen writes (`TERM=vt52`), the questions come line by
@@ -213,11 +220,42 @@ given on the command line fill the screens in advance and are kept as they are.
menu shows it the same way, Enter keeping what `--system` named and `c`
choosing anew.
Colour is added to words, never put in their place. RetroBIOS in the title, the row in focus
and the key the bottom line names first are magenta, files installed or in place
green, files missing or left out yellow, failures and a refused folder red, and
secondary text dim. Only the 16 basic colours are used, the ones a handheld's
console has. `NO_COLOR` set to any value but an empty one turns colour off, as do
`TERM=dumb` or no `TERM`, a terminal whose description names fewer than 8 colours
and an output that is not a terminal. The text stays the same. The line-by-line
questions paint the end of a run the same way.
However the screen ends (Enter on the result, `q`, Ctrl+C, Ctrl+D, SIGTERM, a
hangup), the terminal is given back as the screen found it: the cursor shown,
the main screen back, echo and line editing on. Ctrl+Z, or SIGTSTP from
outside, gives it back the same way and stops the run, and `fg` redraws the
screen where it was.
screen where it was. Ctrl+Z stops it only when a shell with job control
started it, the one thing that can resume it: started from a terminal app's
`-e`, a desktop entry or a launcher's `sh -c`, the key is ignored and the bar
says why.
A mouse or a touch screen works too, beside the keys and buttons. A click or
a tap on a row moves the cursor there, and a second one on the row under the
cursor does what Enter does: one row of a terminal is far smaller than a
finger. The entries of the bottom line press their key, the line that says
which rows are in view shows the next page, and the wheel scrolls a list or a
text without moving the cursor unless it would leave the screen. Nothing
happens until the button or the finger comes up, and only where it went down.
The right and middle buttons do nothing. The installer asks the terminal for
clicks only on a terminal that reports them (`TERM` not `linux`, `dumb` or
unset), never on a handheld route (`RETROBIOS_PAD`) or with
`RETROBIOS_NO_MOUSE=1`, and gives them back on every way out, a stop with
Ctrl+Z included. On the result, the command line screen, any screen showing
a command and the screen where a path is typed, the terminal keeps the mouse,
so text is selected, copied and pasted as usual. Elsewhere, hold Shift while
selecting. `--plain` never asks for clicks. Clicks and taps were checked on
2026-10-27 in xterm, tmux, GNU screen 4.09, Windows Terminal (WSL) and Termux
on Android 17. macOS Terminal and iTerm2 are not checked yet, nor the key
they use to select over the installer.
- `--tui` asks for the full screen, and names the reason when it cannot open
(code 2).
@@ -260,6 +298,20 @@ file list is downloaded once and handed to each run.
[Files you already had](#files-you-already-had).
8. Copies into standalone emulator directories, only with `--standalone-copies`.
The file list names the version of the platform it was built for (Batocera
43.1, RetroBat 8.3.1). Where the system writes its own version in a file, the
installer reads it, and when the two differ it says so before the install and
again with the result: "This list was built for Batocera 43.1, this machine
runs 41. Batocera's own BIOS check may report some files as wrong though they
work." The install goes on. The files read are
`/usr/share/batocera/batocera.version` on Batocera, `/recalbox/recalbox.version`
on Recalbox (a release, not a branch build), `system\version.info` beside the
`bios` folder of RetroBat, and `VERSION_ID` in `/etc/os-release` on Lakka and
EmuELEC. Nothing is run to find it, and an unknown version says nothing:
RetroArch writes its version in no file, KNULLI writes a codename, ROCKNIX the
date of the build, and AmberELEC's prerelease tags are not matched to the version
its image writes.
Some cores read their system data below the frontend's save directory, not
below the BIOS folder: Azahar's keys, shared font and NAND files, Citra's
`sysdata`, Dolphin's `User` tree. The file list marks them `root: save`, and
@@ -288,17 +340,22 @@ names `~/Emulation/saves/retroarch/saves`. RetroPie, ROCKNIX, AmberELEC and
EmuELEC keep saves beside each game, and RomM keeps them in the browser: their
lists record these files as omitted.
A RetroArch run into an empty folder printed this on 2026-10-21:
A RetroArch dry run into an empty folder printed this on 2026-10-27:
```
Fetching file index for retroarch...
8069 files (6.5 GB)
Not installable: 11 files (1 required, not found: 11).
106 files read from RetroArch's save directory go to a folder per core under /home/me/.config/retroarch/saves
8358 files (6.6 GB)
3269 BIOS files (4.1 GB) and 5089 game data files (2.5 GB).
Not installable: 37 files (1 required, not found: 37).
Checking existing files...
0/8069 present (0 verified, 0 wrong hash)
0/8358 present (0 verified, 0 wrong hash)
```
The second line divides the first, and every later count of the run (the
menu, the plan, `--dry-run`, the result) is taken from the same list.
When the manifest leaves entries out (a file the collection cannot supply, or
one that failed its hash check), a `Not installable:` line under the index count
says how many and why. `--check` and the closing report also name the required
@@ -596,18 +653,30 @@ By default the installer fetches everything the platform runs. At a terminal,
the plan screen of the [full-screen interface](#the-full-screen-interface)
offers **Install**, **Choose systems** and **Options**. With `--plain`, or where
the full screen cannot open (a terminal smaller than 40x12, `TERM=dumb`), the
same choice comes as questions after detection:
same choice comes as questions after detection. A RetroArch run with `--plain`
printed this on 2026-10-27:
```
RetroArch: 8069 files, 6.5 GB.
RetroArch: 8358 files, 6.6 GB, and 2636 data files (38.5 MB).
3269 BIOS files (4.1 GB) and 5089 game data files (2.5 GB).
BIOS folder: /home/me/.config/retroarch/system
106 files read from RetroArch's save directory go to a folder per core under /home/me/.config/retroarch/saves
Enter) install everything
i) only what the installed cores read: 100 files, 44.2 MB
i) only what the installed cores read: 87 files, 43.8 MB
c) choose systems, cores and regions
f) copy from a folder or an old card
g) leave out the 5089 game data files (2.5 GB), game data: files a game or a game engine reads, of no use to the other cores
q) quit
```
A list that marks its game data counts it apart from the BIOS files, on the
plan, in this menu and on the result (`Installed: 3269 BIOS files, 5089 game
data files and 2636 data files.`), the parts adding up to the total. `g` leaves
the game data of the choice out, as `--no-game-data` does, and counts again
(`g` then keeps it). The plan screen has the same choice as a row of its own,
**Game data (5089 files, 2.5 GB): kept, leave out**, one press toggling it,
and Options keeps its **Game data** row too.
`i` appears for RetroArch, Lakka and RetroPie when cores are found installed,
and the line above is a RetroArch with Beetle PSX HW, Snes9x, mGBA, Genesis Plus GX
and FCEUmm.
@@ -615,7 +684,9 @@ It keeps what those cores read and drops the systems none of them emulates,
the rule `--installed-cores` applies.
`c` walks through three numbered lists, each answered with numbers such as
`1,4,7-9`, or Enter to keep everything on that axis.
`1,4,7-9`, or Enter to keep everything on that axis. The letter names the
lists it asks (`c) choose systems` with a MiSTer pack), and a list with one
answer is not asked.
- **Systems.** The consoles and computers the platform declares, titled and
ordered as the full screen's Choose systems lists them, the id `--system`
@@ -637,6 +708,16 @@ without questions, every other option of the run in it, for instance
--system sony-playstation --region north-america`. Enter then installs, and
`c` chooses again.
An option is refused by the axis the list does not record, with what works
instead. The MinUI, NextUI and MyMinUI lists record cores and regions and no
system: `--core` and `--region` narrow them, `--system` is refused with
`Run it without --system, or narrow with --core and --region`. A pack records
the systems of its files and what its platform's list narrows by: with the
pack alone, `--core` or `--region` names that list (`--manifest FILE`, a copy
of `install/minui.json`) only when it records them, and MiSTer FPGA's pack
says its list records no cores. A list from an older release records none of
the three, and the one-line installer fetches the current one.
The same choices on the command line:
```bash
@@ -746,7 +827,7 @@ what the options name, everything by default.
| <span id="option-list-cores"></span>`--list-cores` | Print the cores whose extra files a platform installs |
| <span id="option-list-emulators"></span>`--list-emulators` | Print every name `--emulator` accepts, each buildbot name beside the emulator it stands for |
| <span id="option-romm-firmware"></span>`--romm-firmware TEMPLATE` | RomM: where each platform's firmware goes in the library, as `filesystem.structure.firmware` in RomM's `config.yml` says (`{platform}/bios` for a library laid out as `{platform}/roms`). Read from `config.yml` beside the library when it is there. See [RomM firmware layout](#romm-firmware-layout) |
| <span id="option-no-input"></span>`--no-input` | Never ask a question, even at a terminal. A run whose output goes to a file or a pipe asks nothing either, and says so on stderr |
| <span id="option-no-input"></span>`--no-input` | Never ask a question, even at a terminal. A run whose output goes to a file or a pipe asks nothing either, and says so on stderr. It finds the setups and the mounted cards the screen finds: one is taken, as Enter takes it, and two stop the run with an `error` event (`stage` `detect`, `reason` `conflict`) naming each with its `--platform` and `--dest` |
| <span id="option-check"></span>`--check` | Report and exit without writing |
| <span id="option-dry-run"></span>`--dry-run` | Show what would be downloaded, the totals first, then by system and with sizes, without writing anything. A plan taller than the screen names the ten largest systems, and `--verbose` lists every system and file |
| <span id="option-yes"></span>`--yes`, `-y` | Do not ask before a download of 1 GB or more, nor anything else. Implies `--no-input`, so a run that needs an answer (nothing found here, two setups found) stops on what to name instead |
@@ -864,20 +945,42 @@ A card that holds a system's own files is read the same way, without
`--platform` or with the one that names its list, by the rules the table above
gives for the device, below the card's root instead of its mount point:
<!-- generated: card-markers -->
| On the card | System | Files go to |
|-------------|--------|-------------|
| `system/configs/emulationstation/about.info` holding the line `KNULLI` | KNULLI | `bios`, KNULLI's list |
| `system/batocera.conf` holding the line `system.hostname=KNULLI` | KNULLI | `bios`, KNULLI's list |
| `.config/system/configs/system.cfg` holding the line `root.password=rocknix` | ROCKNIX | `roms/bios`, ROCKNIX's list |
| `MUOS/` | muOS | `MUOS/bios`, RetroArch's list |
| `.tmp_update/onionVersion/version.txt` | Onion | `BIOS`, RetroArch's list |
| `spruce/` | spruceOS | `BIOS`, RetroArch's list |
| `System/usr/trimui/crossmix-version.txt` | CrossMix-OS | `BIOS`, RetroArch's list |
| `.tmp_update/onionVersion/version.txt` | Onion | `BIOS`, RetroArch's list |
| `.allium/` | Allium | `BIOS`, RetroArch's list |
| `Koriki/version.txt` | Koriki | `BIOS`, RetroArch's list |
| `system/batocera.conf` with `system.hostname=KNULLI`, as KNULLI's first boot writes its share | KNULLI | `bios`, KNULLI's list |
| `.config/system/configs/system.cfg` with `root.password=rocknix`, as ROCKNIX's first boot writes its storage | ROCKNIX | `roms/bios`, ROCKNIX's list |
| `system/batocera.conf` holding `system.hostname=BATOCERA` or no hostname line, and no KNULLI file above | Batocera SHARE drive | `bios`, Batocera's list |
| `system/recalbox.conf` | Recalbox SHARE drive | `bios`, Recalbox's list |
| `system/batocera.conf` with any other hostname, and no KNULLI file above, or the files of two SHARE drives | named by neither: the run says which systems it could be | the folder of the system named with `--platform` |
The full screen lists such a card on its first screen ("muOS SD card (E:\)").
<!-- /generated: card-markers -->
Each file is one the system writes. KNULLI is read by `about.info` first,
which no menu writes: its HOSTNAME row rewrites `system.hostname`, and a KNULLI
card renamed there was read as a Batocera SHARE drive. ROCKNIX's line changes
with its root password, and a card whose password was changed is named by
nothing, never by another system. A drive whose files fit two systems is named
by neither: the first screen and `--plain` say which systems it could be and
the two commands that name it, and a `--dest` named with one of them takes it
as that system's, with a note.
The full screen lists such a card on its first screen ("muOS SD card (E:\)"),
and a SHARE drive the same way ("Batocera SHARE drive (SHARE)"): its root, typed
or given with `--dest`, stands for its `bios` folder. Two cards of one system
say what their BIOS folder holds ("Onion SD card (OLDONION, 6 BIOS files)"),
the one holding fewer first.
Named by its system (`--platform muos`, `--platform knulli`), a `--dest` that
is another system's card is refused. One that holds none of the system's
is another system's card is refused, and so is another system's SHARE drive
for Batocera and Recalbox. One that holds none of the system's
files is refused where the card always carries them. For KNULLI, ROCKNIX and
the systems no file on the card names, it gets the system's folder below it
(`bios`, `roms/bios`), with a note. Named with a file list instead
@@ -1009,9 +1112,16 @@ and `--plain` gives the same list numbered, in the same order, with `--dest`
too. Both find the SD cards mounted here, the screen under **Found on this
machine**. With a setup found, the setup screen lists it with **Another setup
or folder**, and `--plain` asks the same: Enter takes the first, `o` opens the
numbered list and then the folder, `q` quits. A platform named, or read from
a list or a pack, and found nowhere gets its folder asked, its usual one under
Enter, the mounted drives numbered. A folder typed is read from the current
numbered list and then the folder, `q` quits. A platform named and found
nowhere gets its folder asked, its usual one under Enter, the mounted drives
numbered. A list or a pack read by card setups too (RetroArch's, read by Onion,
muOS, ArkOS and the others) opens the setup list instead, filtered to the
setups that read it, RetroArch first: Enter on it asks RetroArch's folder. At
that question a drive is numbered by the folder its system reads (`ONION:
BIOS`), a drive nothing names by its `bios` folder (`EASYROMS: bios`), never
by its root, which no setup reads. Another system's card or SHARE drive, and a
drive two systems fit, are left out, and a line names them: each is reached
through its own setup. A folder typed is read from the current
one when it is not a full path, and named in full after. `q` quits there too
(a folder named `q` is typed `./q`), and Enter with no default says what to
type. On a computer Batocera and Recalbox have no default: the drives are
@@ -1360,12 +1470,20 @@ That keeps the installer's questions working when the script is piped from
The manifest is fetched over the network and treated as untrusted input. Every
path it carries goes through one validator that refuses an absolute path, a
drive letter, a backslash, a null byte, a doubled separator, a trailing slash
and any `..` component, so a destination cannot climb out of the BIOS
directory. Manifest, target list and payloads each have a size cap, the file
drive letter, a backslash, a null byte or any other control character, a
doubled separator, a trailing slash and any `..` component, so a destination
cannot climb out of the BIOS directory and no file is named with a terminal
command. Manifest, target list and payloads each have a size cap, the file
list a count cap, and the sum of the declared sizes is checked against the
total the manifest claims.
Every other string from outside is shown, never obeyed: the names a list or
a pack records, a card's label and a folder a configuration names reach the
terminal, line by line or on the screen, and the `--events` stream with a `?`
for each control character. A folder a configuration names with one is not
taken: the run says so and asks for `--dest`, its default being no answer
for a setup that reads another folder.
Symbolic links met under the BIOS root are followed on purpose: they are the
user's own layout, and EmuDeck links `bios/shadps4/sys_modules` into shadPS4's
data directory where the emulator actually reads it. The boundary is lexical,
@@ -1419,7 +1537,7 @@ fields, the installer refuses to narrow rather than install everything.
| `0` | everything asked for is installed or already up to date |
| `1` | a failure: the one-liner could not download or verify `install.py`, or found no Python 3.8 (nothing was run), an unusable base URL, an unknown platform or target, `--installed-cores` with no core found, a manifest that fails validation, a fetch that never succeeded, no platform to install for in a non-interactive run, some files failed or were left out by `--offline` while others installed, `--check` found files to fetch, a `--from-pack` pack that cannot be read, lacks a part or is for another platform, a `--from` folder that does not exist or cannot be read, a `--dest` that is not the card of the system named (another system's card, a folder inside one, a drive with none of its files where its card always has them, or a folder that does not exist), `--restore` could not put a file back, or `--add-app` could not put every file of the app on the card |
| `2` | nothing was installed: every file the run tried failed (a BIOS folder that cannot be written, for one), or `--offline` left every file out, the drive has too little free space for the download (checked before any folder is created), or the question about a folder that does not exist, named with `--dest` or typed at the folder question, was answered no. Also an option the installer refused before any download: an unknown option, `--jobs` outside 1 to 32, `--target` with `--every-board` or `--from-pack`, `--target` or `--list-targets` with `--offline` (or `RETROBIOS_INSTALL_OFFLINE` set), which read a core list from the network, `--add-app` with `--check`, `--dry-run`, a listing, `--from-pack` or `--offline`. The message then starts with `install.py: error:`. Also `--add-app` for a folder on no card that takes the app, said in an `Error:` line and an `app` event before anything is written. With `--restore`, a folder that is not a dated folder inside `retrobios-backup` |
| `130` | stopped with Ctrl+C, or with `q`, Ctrl+C or Ctrl+D at a question, or the full screen closed with no button pressed (`RETROBIOS_IDLE_EXIT`) before an install. Run the same command again to carry on |
| `130` | stopped with Ctrl+C, or with `q`, Ctrl+C or Ctrl+D at a question, or the full screen closed with no button pressed (`RETROBIOS_IDLE_EXIT`) before an install. A quit chosen (`q`, **Quit**) is code `130` too, and the terminal keeps `RetroBIOS: quit. Nothing was installed.` where a stop keeps `stopped`. Run the same command again to carry on |
| `141` | the output was piped to a reader that closed early (`--list-platforms \| head`) |
<!-- /generated: exit-codes -->
@@ -1466,6 +1584,7 @@ other schemas under `api/v1/schemas/`.
| `detect` | `os`, `os_name`, `platforms` | Once the platforms are known. `os_name` comes from `/etc/os-release`. `platforms` lists `{platform, name, bios_dir}`, and is empty when nothing supported was found |
| `error` | `stage`, `reason`, `platform`, `message` | The file list could not be read (`stage` is `manifest`): `reason` is `network`, `not_found` or `invalid`, `clock` when the server's certificate was refused and the system clock reads a date before the installer was written, `no_ca` when the machine holds no list of trusted certificates (`SSL_CERT_FILE` names one), or `offline` when `--offline` forbids the request. A folder named with `--from` cannot be read (`stage` is `from`, `reason` `not_found`, `not_a_folder` for a file that is no ZIP, `unreadable`, or `system` for the root of the system, `/proc`, `/sys` or `/dev`). The BIOS folder sits under a folder this user cannot open (`stage` is `dest`, `reason` `unreadable`), and the run ends with code 1 before anything is written. The BIOS folder cannot be created (`stage` is `dest`, `reason` `not_writable`): a `summary` follows with what the run installed before it. Two systems are detected on one machine and no `--dest` names the folder (`stage` is `detect`, `reason` `conflict`). The platform named with `--platform` is found nowhere and no folder can be assumed for it: a card system with no card named, a portable emulator, Batocera or Recalbox named on a computer (their folder is the `bios` folder of their SHARE drive), or no usual folder on this system or one set aside behind a folder this user cannot open (`stage` is `detect`, `reason` `not_found`). A `--dest` refused as the card of the system named carries the same `stage` and `reason`: another system's card, a folder inside a card, a drive with none of the files its card always has, or a folder that does not exist. `message` says it in words, and is the only thing that tells these cases apart |
| `scanned` | `folder`, `files`, `truncated`, `other_drives` | Each folder named with `--from`, once read and before `detect`. `files` counts the files found, `truncated` is true when the search stopped at 200,000 of them, and `other_drives` lists the folders below it on another drive, which were not entered |
| `version` | `platform`, `list_version`, `installed_version`, `message` | Before `choices`, when the system here runs another version than the one the list was built for: `list_version` is the list's, `installed_version` the one the system's version file states, and `message` says it and what it means. Not written when either version is unknown. The run goes on |
| `choices` | `platform`, `systems` | Before `checking`: the systems the run's list lets one choose among, sorted by id, `other` last for the files no system names. The run's other options apply (`--core`, `--region`, `--no-game-data`, the files left out for an unknown save directory), `--system` does not: these are the systems a screen lists to choose from, and the count a `--system` is out of |
| `file` | `platform`, `dest`, `systems`, `size`, `state` | Each file of the list after the check. `state` is `present` (hash verified), `wrong_hash` or `missing` |
| `system` | `platform`, `system`, `name`, `files`, `present`, `missing`, `wrong_hash`, `bytes_needed` | Each system, sorted by id, and with `--system` only the systems named. Files with no system count under `other`. `name` is the platform's own name for it |
@@ -1475,7 +1594,7 @@ other schemas under `api/v1/schemas/`.
| `data` | `platform`, `files`, `bytes` | Right after `declared`: the data-tree files to fetch (the `data_missing` of `check`) and the bytes they write once in place |
| `found` | `platform`, `dest`, `folder`, `path`, `member`, `reason` | Each file to install that this machine already holds, after `check` and before anything is written, in `--check` and `--dry-run` too. `folder` is the `--from` folder as given, or the `bios_dir` of the check when the BIOS folder holds the file at another place, and then `reason` says where in words (`nested folder: ...` for a misplaced file, `the same file is at ...` for one the list installs there too). `path` is the file, and `member` the ZIP member holding the bytes when `path` is an archive, an empty string otherwise. Its copy is reported by a `downloaded` event |
| `unreadable` | `platform`, `folder`, `path`, `member`, `reason` | Each file in a `--from` folder that could not be read and may be one the run still needs, right after the `found` events: its size is that of a file no copy was found for, or unknown (a folder that could not be listed, a ZIP that would not open). `member` names the ZIP member, or is empty. `reason` says why in words (`Permission denied`, `it is encrypted, a password is needed`) |
| `saves` | `platform`, `files`, `folder` | After `choices` and before `checking`, when the files the run installs (once `--system` and the other choices narrowed the list) hold some read from the frontend's save directory and that directory is known: how many, and the `folder` they go to, where `<system>` and `<core>` stand for one folder per system or per core. When it is not known, the files are counted in the summary's `skipped` instead (`no_save_directory`) |
| `saves` | `platform`, `files`, `folder` | After `choices` and before `checking`, when the files the run installs (once `--system` and the other choices narrowed the list) hold some read from the frontend's save directory and that directory is known: how many, and the `folder` they go to, where `<system>` and `<core>` stand for one folder per system or per core (the screen and `--plain` say it in words: "a folder per core under /sdcard/RetroArch/saves"). When it is not known, the files are counted in the summary's `skipped` instead (`no_save_directory`) |
| `download` | `platform`, `files`, `bytes` | Before the downloads start. Counts the files copied from this machine too |
| `progress` | `files_done`, `files_total`, `bytes_done`, `bytes_total` | At most every half second while bytes arrive |
| `transfer` | `bytes_local`, `bytes_network` | Right after each `progress` event, and once when the files of a `download` event are done. It splits `bytes_done`: `bytes_local` came from this machine (a copy found by `--from` or in the BIOS folder, the pack, a partial copy resumed), `bytes_network` from the network. A download speed is `bytes_network` over the time elapsed |
@@ -1486,7 +1605,7 @@ other schemas under `api/v1/schemas/`.
<!-- /generated: events -->
Schema 1 can gain a kind (`found` came with `--from`, `declared` with `--declared-only`, `unsearched` with the search that goes on past a closed folder, `app` with `--add-app`, `data` with the size of the data trees), never a key of an
Schema 1 can gain a kind (`found` came with `--from`, `declared` with `--declared-only`, `unsearched` with the search that goes on past a closed folder, `app` with `--add-app`, `data` with the size of the data trees, `version` with the list's version), never a key of an
existing kind: a reader skips a kind it does not know. An option refused
before the run starts (`install.py: error:`, code 2) writes
no event at all. A program reads a missing `end` as that case, or as a
@@ -1510,19 +1629,20 @@ RetroArch folder that holds only `scph5501.bin`, in the order written:
|----------|--------|
| `RETROBIOS_REF` | Branch or tag the file list and the files committed to the repository are read from. Defaults to `main`. Files the manifest marks `release_asset` always come from the `large-files` release, whatever the ref, and that release replaces an asset in place when it is rebuilt. Each release deletes the previous release tags, so a tag holds a file list until the next release. For contributors: [release process](release-process.md#cutting-a-release) |
| `RETROBIOS_BASE_URL` | Base URL for the manifest and the files it declares. HTTPS only, plain HTTP allowed to loopback for end-to-end tests. Whoever controls this base controls the expected hashes, hence the check. A file list that cannot be fetched names the address, and this variable when it is set |
| `RETROBIOS_INSTALL_OFFLINE` | Set to anything but `0`: no network request, as with `--offline`. The runs the full-screen interface starts inherit it. `RETROBIOS_OFFLINE` is the build scripts' own and leaves the installer alone |
| `RETROBIOS_INSTALL_OFFLINE` | Set to anything but `0`: no network request, as with `--offline`. The runs the full-screen interface starts inherit it. The words then name the variable (`not fetched (RETROBIOS_INSTALL_OFFLINE=1)`, `run it with RETROBIOS_INSTALL_OFFLINE unset`), and `--offline` where the option was given. `RETROBIOS_OFFLINE` is the build scripts' own and leaves the installer alone |
| `RETROBIOS_OS` | Names the host outright (`linux`, `wsl`, `windows`, `darwin`, `android`) instead of detecting it |
| `EXTERNAL_STORAGE` | Android only, the shared storage root RetroArch builds its default directories from. Defaults to `/storage/emulated/0` |
| `RETROBIOS_INSTALL_URL` | Where the bootstrap fetches `install.py`. HTTPS only |
| `RETROBIOS_INSTALL_SHA256` | The SHA-256 the bootstrap requires of that installer, 64 hex characters. When either of these two is set and the fingerprint does not match, the error names the variable instead of suggesting a retry |
| `RETROBIOS_BOOTSTRAP` | Set by `install.sh` (`sh`) and `install.ps1` (`ps1`) for the temporary installer they run, so that its hints give back the one-line command rather than `python3 install.py` |
| `NO_COLOR` | Plain text, no colour, even at a terminal, when set to any value but an empty one. `TERM=dumb`, or no `TERM` outside Windows, also turns the live progress line and the colour off, as does a terminal whose description moves no cursor the ANSI way (`TERM=vt52`). The full screen draws no colour at all: the row in focus is marked with `>` as well as reverse video, and every state is written in words |
| `NO_COLOR` | Plain text, no colour, even at a terminal, when set to any value but an empty one. `TERM=dumb`, or no `TERM` outside Windows, also turns the live progress line and the colour off, as does a terminal whose description moves no cursor the ANSI way (`TERM=vt52`). A description naming fewer than 8 colours keeps the live line and drops the colour. The full screen then draws the same text without colour: the row in focus is marked with `>` as well as reverse video, and every state is written in words |
| `TERM`, `TERMINFO`, `TERMINFO_DIRS` | Decide whether the full screen opens. `TERM` unset or `dumb` (outside Windows) gives the questions line by line. Otherwise the terminal's description is read where ncurses reads it: `TERMINFO`, then `~/.terminfo`, then each folder of `TERMINFO_DIRS`, then the system's own. A description whose cursor moves are not the ANSI ones the screen writes (`TERM=vt52`) gives the questions too, and `--tui` there stops with the reason |
| `FORCE_COLOR`, `CLICOLOR_FORCE` | Colour even when the output is a pipe or a file, set to any value but `0` or an empty one. `NO_COLOR` wins over both, and the progress line stays one line per file |
| `SSL_CERT_FILE`, `SSL_CERT_DIR` | The trusted certificates to check servers with, for a Python that finds none of its own |
| `RETROBIOS_PLAIN`, `ACCESSIBLE` | Set to anything but `0`: the questions come line by line, as with `--plain`, instead of the full-screen interface |
| `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 130, or with the code of the error or result screen it closed on |
| `RETROBIOS_NO_MOUSE` | Set to anything but `0`: the full screen never asks the terminal for clicks, and the mouse selects text everywhere as it does outside the installer |
| `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
wiki/profiling.md
+7 -2
View File
@@ -278,7 +278,11 @@ core_classification: community_fork
source: https://github.com/libretro/dolphin
upstream: https://github.com/dolphin-emu/dolphin
profiled_date: 2026-03-25
core_version: 5.0-21264
core_version: "2609-437-g3aac3f0"
version_basis:
kind: tag
tag: "2609"
distance: 437
systems:
- nintendo-gamecube
- nintendo-wii
@@ -509,7 +513,8 @@ reports the profile as uncheckable, and the CI job that runs
| `source` | no | libretro core repository URL. A dict when the core ships under several repos |
| `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` | no | version analyzed |
| `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 |
| `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` |
| `source_branch` | no | branch `source` was read from when it is not the default one (a port living on a pull request branch). profile_sync follows it |
wiki/technical-faq.md
+21 -19
View File
@@ -124,38 +124,40 @@ per catalog and the full list of catalogued dumps still missing.
Your game sets and BIOS sets must come from the same version as your arcade
emulator.
<!-- generated: romsets -->
| Emulator, as RetroArch names it | Sets from |
|---|---|
| MAME 2000 | MAME 0.37b5 |
| MAME 2003, MAME 2003 Midway | MAME 0.78 |
| MAME 2003-Plus | MAME 0.78, with later fixes |
| MAME 2003-Plus | MAME 0.78 (plus backports) |
| MAME 2009 | MAME 0.135u4 |
| MAME 2010 | MAME 0.139 |
| MAME 2014, MAME 2015 | MAME 0.160 |
| MAME 2014, MAME 2015 | MAME 0.159 |
| MAME 2016 | MAME 0.174 |
| MAME/MESS | MAME 0.287 |
| MAME, MAME/Arcade | MAME 0.289 |
| FB Alpha 2012 CPS-1, FB Alpha 2012 CPS-2 | FB Alpha 0.2.97.28 |
| FB Alpha 2012, FB Alpha 2012 CPS-3, FB Alpha 2012 Neo Geo | FB Alpha 0.2.97.29 |
| FB Alpha 2019 | FB Alpha 0.2.97.44 |
| FinalBurn Neo, FinalBurn Neo (Neo-Geo), FinalBurn Neo (CPS-1 / CPS-2) | FinalBurn Neo 1.0.0.2 |
| MAME, MAME/Arcade, MAME/MESS | MAME 0.289 |
| FB Alpha 2012 CPS-1, FB Alpha 2012 CPS-2 | FB Alpha v0.2.97.28 |
| FB Alpha 2012 Neo Geo | FB Alpha v0.2.97.29 |
| FB Alpha 2012, FB Alpha 2012 CPS-3 | FB Alpha v0.2.97.30 |
| FB Alpha 2019 | FB Alpha v0.2.97.44 |
| FinalBurn Neo, FinalBurn Neo (CPS-1 / CPS-2), FinalBurn Neo (Neo-Geo) | FinalBurn Neo v1.0.0.03 |
<!-- /generated: romsets -->
Each emulator's page names its version too.
### How this is known
Arcade BIOS sets are coupled to the romset version, so there is one
profile per MAME core generation: MAME 2000 (0.37b5), MAME 2003 (0.78),
MAME 2003-Plus, MAME 2009 (0.135u4), MAME 2010 (0.139), MAME 2015
(0.160), MAME 2016 (0.174), and current MAME (0.289), each read from that
version's own source tree, because the BIOS root sets differ between
versions. Derivatives and ports carry their own profiles on top of those
generations: `mamearcade`, `mamemess`, `mame2003_midway`, the three
`mame4droid` drops, `advancemame`, `groovymame` and `hbmame`. Recalbox
compiles two MAME versions of its own, 0.258 and 0.278, profiled as
`mame0258` and `mame0278`. The pack
ships the sets matching the core you run, and a generic unversioned arcade
pack cannot do that.
profile per MAME core generation (MAME 2000, 2003, 2003-Plus, 2009, 2010,
2015, 2016 and current MAME), each read from that version's own source
tree, because the BIOS root sets differ between versions. The table is
written from the profiles, and each version is the one the core's source
states at the revision its profile was read at. Derivatives and ports
carry their own profiles on top of those generations: `mamearcade`,
`mamemess`, `mame2003_midway`, the three `mame4droid` drops,
`advancemame`, `groovymame` and `hbmame`. Recalbox compiles two MAME
versions of its own, 0.258 and 0.278, profiled as `mame0258` and
`mame0278`. The pack ships the sets matching the core you run, and a
generic unversioned arcade pack cannot do that.
## Why does my verification report say UNTESTED?
wiki/testing-guide.md
+4 -1
View File
@@ -63,7 +63,10 @@ Every module in `tests/`, by the area it guards.
| Standalone emulators | the release asset EmuDeck's rule picks, the AppImage offset, the Xvfb framebuffer reader, the settings written and the oracle the verdicts use, with no emulator run | `test_standalone_probe` |
| Automation runner, disk cleanup, asset sync and bit-flip repair | fake jobs, git repositories with a bare origin and session worktrees, a committed file with one bit flipped, canned CI runs in place of `gh` | `test_autorun` |
| Truth and native export | synthetic + cached originals | `test_export_counts`, `test_export_native_layer`, `test_export_report`, `test_exporters`, `test_truth_data_dir_readers`, `test_truth_diff`, `test_truth_layout` |
| Scrapers, upstream and provenance | inline sources, synthetic | `test_batocera_md5_list`, `test_check_freshness`, `test_contributing_text`, `test_coverage_cache`, `test_data_dir_refs`, `test_dataclass_defaults`, `test_dedup`, `test_doc_pages`, `test_doc_surfaces`, `test_elec_scrapers`, `test_fbneo_parser`, `test_find_pinned_revision`, `test_hash_merge`, `test_launchers`, `test_launchers_emudeck`, `test_launchers_recalbox`, `test_launchers_retrobat`, `test_launchers_retrodeck`, `test_launchers_retropie`, `test_launchers_rocknix`, `test_mame_devices`, `test_mame_parser`, `test_mame_ref_audit`, `test_optional_dependencies`, `test_profile_sync`, `test_prose_style`, `test_provenance`, `test_refresh_data_dirs`, `test_refresh_failures`, `test_refresh_stale`, `test_retrodeck_scraper_errors`, `test_romset_recipes`, `test_schema_semantic_gate`, `test_scraper_contract`, `test_site_availability`, `test_site_content_data`, `test_site_copy`, `test_site_cores`, `test_site_emulator_page`, `test_site_exports`, `test_site_funnel`, `test_site_images`, `test_site_picker`, `test_site_platform_hashes`, `test_site_r2_components`, `test_site_r2_css`, `test_site_r2_emulators`, `test_site_r2_entry`, `test_site_r2_gate`, `test_site_r2_nav`, `test_site_r2_p0`, `test_site_r2_reference`, `test_site_r2_systems`, `test_site_r2_wiki`, `test_site_r3_collection`, `test_site_r3_components`, `test_site_r3_css`, `test_site_r3_emulators`, `test_site_r3_entry`, `test_site_r3_nav`, `test_site_r3_p0`, `test_site_r3_reference`, `test_site_r3_systems`, `test_site_r3_wiki`, `test_site_r4_components`, `test_site_r4_css`, `test_site_r4_emulators`, `test_site_r4_entry`, `test_site_r4_merge`, `test_site_r4_p0`, `test_site_r4_reference`, `test_site_r4_search`, `test_site_r4_systems`, `test_site_r4_wiki`, `test_site_r5_components`, `test_site_r5_css`, `test_site_r5_emulators`, `test_site_r5_entry`, `test_site_r5_reference`, `test_site_r5_search`, `test_site_r5_systems`, `test_site_r5_wiki`, `test_site_render`, `test_site_system_links`, `test_site_validation`, `test_site_weight`, `test_site_write`, `test_source_ref_targets`, `test_upstream`, `test_upstream_index`, `test_validate_pr`, `test_validate_pr_flow`, `test_validate_pr_hashes`, `test_workflow_paths` |
| Scrapers, upstream and provenance | inline sources, synthetic | `test_batocera_md5_list`, `test_check_freshness`, `test_contributing_text`, `test_coverage_cache`, `test_data_dir_refs`, `test_dataclass_defaults`, `test_dedup`, `test_doc_pages`, `test_doc_surfaces`, `test_elec_scrapers`, `test_fbneo_parser`, `test_find_pinned_revision`, `test_hash_merge`, `test_launchers`, `test_launchers_emudeck`, `test_launchers_recalbox`, `test_launchers_retrobat`, `test_launchers_retrodeck`, `test_launchers_retropie`, `test_launchers_rocknix`, `test_mame_devices`, `test_mame_parser`, `test_mame_ref_audit`, `test_optional_dependencies`, `test_profile_sync`, `test_prose_style`, `test_provenance`, `test_refresh_data_dirs`, `test_refresh_failures`, `test_refresh_stale`, `test_retrodeck_scraper_errors`, `test_romset_recipes`, `test_schema_semantic_gate`, `test_scraper_contract`, `test_site_availability`, `test_site_content_data`, `test_site_copy`, `test_site_cores`, `test_site_emulator_page`, `test_site_exports`, `test_site_funnel`, `test_site_images`, `test_site_picker`, `test_site_platform_hashes`, `test_site_r2_components`, `test_site_r2_css`, `test_site_r2_emulators`, `test_site_r2_entry`, `test_site_r2_gate`, `test_site_r2_nav`, `test_site_r2_p0`, `test_site_r2_reference`, `test_site_r2_systems`, `test_site_r2_wiki`, `test_site_r3_collection`, `test_site_r3_components`, `test_site_r3_css`, `test_site_r3_emulators`, `test_site_r3_entry`, `test_site_r3_nav`, `test_site_r3_p0`, `test_site_r3_reference`, `test_site_r3_systems`, `test_site_r3_wiki`, `test_site_r4_components`, `test_site_r4_css`, `test_site_r4_emulators`, `test_site_r4_entry`, `test_site_r4_merge`, `test_site_r4_p0`, `test_site_r4_reference`, `test_site_r4_search`, `test_site_r4_systems`, `test_site_r4_wiki`, `test_site_r5_components`, `test_site_r5_css`, `test_site_r5_emulators`, `test_site_r5_entry`, `test_site_r5_reference`, `test_site_r5_search`, `test_site_r5_systems`, `test_site_r5_wiki`, `test_site_render`, `test_site_system_links`, `test_site_validation`, `test_site_weight`, `test_site_write`, `test_source_ref_targets`, `test_upstream`, `test_upstream_index`, `test_validate_pr`, `test_version_basis`, `test_validate_pr_flow`, `test_validate_pr_hashes`, `test_workflow_paths` |
| Scrapers, upstream and provenance | inline sources, synthetic | `test_batocera_md5_list`, `test_check_freshness`, `test_contributing_text`, `test_coverage_cache`, `test_data_dir_refs`, `test_dataclass_defaults`, `test_dedup`, `test_doc_pages`, `test_doc_surfaces`, `test_elec_scrapers`, `test_fbneo_parser`, `test_find_pinned_revision`, `test_hash_merge`, `test_launchers`, `test_launchers_emudeck`, `test_launchers_recalbox`, `test_launchers_retrobat`, `test_launchers_retrodeck`, `test_launchers_retropie`, `test_launchers_rocknix`, `test_mame_devices`, `test_mame_parser`, `test_mame_ref_audit`, `test_optional_dependencies`, `test_profile_sync`, `test_prose_style`, `test_provenance`, `test_refresh_data_dirs`, `test_refresh_failures`, `test_refresh_stale`, `test_retrodeck_scraper_errors`, `test_romset_recipes`, `test_schema_semantic_gate`, `test_scraper_contract`, `test_site_availability`, `test_site_content_data`, `test_site_copy`, `test_site_cores`, `test_site_emulator_page`, `test_site_entry_tables`, `test_site_exports`, `test_site_funnel`, `test_site_images`, `test_site_picker`, `test_site_platform_hashes`, `test_site_r2_components`, `test_site_r2_css`, `test_site_r2_emulators`, `test_site_r2_entry`, `test_site_r2_gate`, `test_site_r2_nav`, `test_site_r2_p0`, `test_site_r2_reference`, `test_site_r2_systems`, `test_site_r2_wiki`, `test_site_r3_collection`, `test_site_r3_components`, `test_site_r3_css`, `test_site_r3_emulators`, `test_site_r3_entry`, `test_site_r3_nav`, `test_site_r3_p0`, `test_site_r3_reference`, `test_site_r3_systems`, `test_site_r3_wiki`, `test_site_r4_components`, `test_site_r4_css`, `test_site_r4_emulators`, `test_site_r4_entry`, `test_site_r4_merge`, `test_site_r4_p0`, `test_site_r4_reference`, `test_site_r4_search`, `test_site_r4_systems`, `test_site_r4_wiki`, `test_site_r5_components`, `test_site_r5_css`, `test_site_r5_emulators`, `test_site_r5_entry`, `test_site_r5_reference`, `test_site_r5_search`, `test_site_r5_systems`, `test_site_r5_wiki`, `test_site_render`, `test_site_system_links`, `test_site_validation`, `test_site_weight`, `test_site_write`, `test_source_ref_targets`, `test_upstream`, `test_upstream_index`, `test_validate_pr`, `test_validate_pr_flow`, `test_validate_pr_hashes`, `test_workflow_paths` |
| Scrapers, upstream and provenance | inline sources, synthetic | `test_batocera_md5_list`, `test_check_freshness`, `test_contributing_text`, `test_coverage_cache`, `test_data_dir_refs`, `test_dataclass_defaults`, `test_dedup`, `test_doc_pages`, `test_doc_surfaces`, `test_elec_scrapers`, `test_fbneo_parser`, `test_find_pinned_revision`, `test_hash_merge`, `test_launchers`, `test_launchers_emudeck`, `test_launchers_recalbox`, `test_launchers_retrobat`, `test_launchers_retrodeck`, `test_launchers_retropie`, `test_launchers_rocknix`, `test_mame_devices`, `test_mame_parser`, `test_mame_ref_audit`, `test_optional_dependencies`, `test_profile_sync`, `test_prose_style`, `test_provenance`, `test_refresh_data_dirs`, `test_refresh_failures`, `test_refresh_stale`, `test_retrodeck_scraper_errors`, `test_romset_recipes`, `test_schema_semantic_gate`, `test_scraper_contract`, `test_site_availability`, `test_site_content_data`, `test_site_copy`, `test_site_cores`, `test_site_density_cards`, `test_site_emulator_page`, `test_site_exports`, `test_site_funnel`, `test_site_images`, `test_site_picker`, `test_site_platform_hashes`, `test_site_r2_components`, `test_site_r2_css`, `test_site_r2_emulators`, `test_site_r2_entry`, `test_site_r2_gate`, `test_site_r2_nav`, `test_site_r2_p0`, `test_site_r2_reference`, `test_site_r2_systems`, `test_site_r2_wiki`, `test_site_r3_collection`, `test_site_r3_components`, `test_site_r3_css`, `test_site_r3_emulators`, `test_site_r3_entry`, `test_site_r3_nav`, `test_site_r3_p0`, `test_site_r3_reference`, `test_site_r3_systems`, `test_site_r3_wiki`, `test_site_r4_components`, `test_site_r4_css`, `test_site_r4_emulators`, `test_site_r4_entry`, `test_site_r4_merge`, `test_site_r4_p0`, `test_site_r4_reference`, `test_site_r4_search`, `test_site_r4_systems`, `test_site_r4_wiki`, `test_site_r5_components`, `test_site_r5_css`, `test_site_r5_emulators`, `test_site_r5_entry`, `test_site_r5_reference`, `test_site_r5_search`, `test_site_r5_systems`, `test_site_r5_wiki`, `test_site_render`, `test_site_system_links`, `test_site_validation`, `test_site_weight`, `test_site_write`, `test_source_ref_targets`, `test_upstream`, `test_upstream_index`, `test_validate_pr`, `test_version_basis`, `test_validate_pr_flow`, `test_validate_pr_hashes`, `test_workflow_paths` |
| Scrapers, upstream and provenance | inline sources, synthetic | `test_batocera_md5_list`, `test_check_freshness`, `test_contributing_text`, `test_coverage_cache`, `test_data_dir_refs`, `test_dataclass_defaults`, `test_dedup`, `test_doc_pages`, `test_doc_surfaces`, `test_elec_scrapers`, `test_fbneo_parser`, `test_find_pinned_revision`, `test_hash_merge`, `test_launchers`, `test_launchers_emudeck`, `test_launchers_recalbox`, `test_launchers_retrobat`, `test_launchers_retrodeck`, `test_launchers_retropie`, `test_launchers_rocknix`, `test_mame_devices`, `test_mame_parser`, `test_mame_ref_audit`, `test_optional_dependencies`, `test_profile_sync`, `test_prose_style`, `test_provenance`, `test_refresh_data_dirs`, `test_refresh_failures`, `test_refresh_stale`, `test_retrodeck_scraper_errors`, `test_romset_recipes`, `test_schema_semantic_gate`, `test_scraper_contract`, `test_site_availability`, `test_site_content_data`, `test_site_copy`, `test_site_cores`, `test_site_emulator_page`, `test_site_exports`, `test_site_funnel`, `test_site_images`, `test_site_picker`, `test_site_platform_density`, `test_site_platform_hashes`, `test_site_r2_components`, `test_site_r2_css`, `test_site_r2_emulators`, `test_site_r2_entry`, `test_site_r2_gate`, `test_site_r2_nav`, `test_site_r2_p0`, `test_site_r2_reference`, `test_site_r2_systems`, `test_site_r2_wiki`, `test_site_r3_collection`, `test_site_r3_components`, `test_site_r3_css`, `test_site_r3_emulators`, `test_site_r3_entry`, `test_site_r3_nav`, `test_site_r3_p0`, `test_site_r3_reference`, `test_site_r3_systems`, `test_site_r3_wiki`, `test_site_r4_components`, `test_site_r4_css`, `test_site_r4_emulators`, `test_site_r4_entry`, `test_site_r4_merge`, `test_site_r4_p0`, `test_site_r4_reference`, `test_site_r4_search`, `test_site_r4_systems`, `test_site_r4_wiki`, `test_site_r5_components`, `test_site_r5_css`, `test_site_r5_emulators`, `test_site_r5_entry`, `test_site_r5_reference`, `test_site_r5_search`, `test_site_r5_systems`, `test_site_r5_wiki`, `test_site_render`, `test_site_system_links`, `test_site_validation`, `test_site_weight`, `test_site_write`, `test_source_ref_targets`, `test_upstream`, `test_upstream_index`, `test_validate_pr`, `test_validate_pr_flow`, `test_validate_pr_hashes`, `test_workflow_paths` |
## Test architecture
wiki/tools.md
+15
View File
@@ -585,6 +585,21 @@ match no entry. Both land in the `--json` report (`new_files`, with
since the pin or an undeclared hash makes the profile stale. `--tree-diff`
shows added, removed and renamed files in the directories the refs point at.
`core_version` is the version of the code at the pin, and `version_basis`
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.
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.
```bash
python scripts/profile_sync.py --all --verify-version --changed-only
python scripts/profile_sync.py --emulator snes9x --set-version
```
Branch tips, tags and releases are cached for six hours. `--fresh` asks the
forges again for them, which matters right after an upstream commit or a
hand-set pin: a tip cached before the pin reads as behind it. It is refused