docs: describe config_reads and libretro_pools

Both profile fields reached the schema without a row in the profile
field table. pin_frozen is no longer required by pin_build, which now
stands beside pin_frozen or config_reads: its row says so.
This commit is contained in:
Abdessamad Derraz committed 2026-11-11 14:31:08 +01:00
1 parent 02a400aead
commit 484a711053
1 file changed
+4 -2
+4 -2
View File
@@ -526,8 +526,8 @@ reports the profile as uncheckable, and the CI job that runs
| `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` | with `pin_build` | 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 |
| `pin_build` | no | the build file each platform shipping a `pin_frozen` build reads its revision from: a list of `platform` (registry slug), `repo` (the platform's own repository), `revision` (the tag or commit the file was read at), `path`, `variable` (`PKG_VERSION`, `<PKG>_VERSION`, `rp_module_repo`) and `value` (what it held there). `check_freshness.py` reads the file again where the platform's YAML now stands and reports the profile `STALE` when the platform builds another revision. A hold that no build file names (a release binary, an abandoned repository) carries `pin_frozen` alone |
| `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 |
| `pin_build` | no | the build file each platform shipping a `pin_frozen` build reads its revision from: a list of `platform` (registry slug), `repo` (the platform's own repository), `revision` (the tag or commit the file was read at), `path`, `variable` (`PKG_VERSION`, `<PKG>_VERSION`, `rp_module_repo`) and `value` (what it held there). `check_freshness.py` reads the file again where the platform's YAML now stands and reports the profile `STALE` when the platform builds another revision. A hold that no build file names (a release binary, an abandoned repository) carries `pin_frozen` alone. A `pin_build` list stands only beside the `pin_frozen` or the `config_reads` that it serves |
| `pin_follows` | no | why `source_commit` follows the branch tip when a single platform ships the profile: that platform builds the tip, cited by its build file. A bump refuses a profile one platform ships until it carries `pin_frozen` or `pin_follows` |
| `groups` | no | the sets of entries the code takes one of, by name, each with its `required`. A member names its sets with `group` and writes no `required` of its own: it is required when one of its sets is |
| `data_root` | no | per operating system (`android`, `ios`, `windows`, `macos`, `linux`), the folder the app reads its user data from, under which `standalone_path` destinations sit: `path` as the user finds it (`Android/data/<package>/files`, `%APPDATA%/...`), with the `source_ref` that builds it. Only the systems the app runs on are keyed |
@@ -544,6 +544,8 @@ reports the profile as uncheckable, and the CI job that runs
| `bios_directory` | no | the folder an agnostic core scans, relative to the system directory (`pcsx2/bios/`). A scan never seeds from files outside it |
| `standalone_directories` | no | what the standalone build resolves `standalone_path` against, as its code names it: a directory (`$XDG_DATA_HOME/flycast`), a setting (`Dreamcast.BiosPath`), an environment variable (`FLYCAST_BIOS_PATH`) or the function returning the directory (`find_user_data_dir`). A platform whose launcher links or passes a folder of its BIOS tree under one of them gets the standalone files in that folder |
| `standalone_pools` | no | settings the standalone build reads as a list of directories it searches one after the other, each mapped to the subfolder of the layout (relative to `standalone_directories`, empty for the whole of it) its directories stand for: openMSX's filepool entries are searched like `share/systemroms`, XRoar's rompath entries hold the ROMs themselves. A file in any entry is read, so several platform records naming entries give the first one a pack can fill |
| `libretro_pools` | no | options of the command line a libretro build is handed as its content that set a list of directories it searches, each mapped to the folder below the system directory its directories stand for: a `folder` with the `source_ref` where the build reads the option. libretro MAME hands MAME `<system>/mame/bios` unless the content's own `-rompath` replaces it |
| `config_reads` | no | the configs the build loads and the keys it opens a file from, so a platform launcher record citing a config is proven: each entry names the `file` (a name, a glob, a path, a flag, `command line` or `core options`), the `source_ref` where it is found and loaded, and `keys`, each `key` with the `source_ref` where it is read and its value opened. An entry naming `platforms` is read at their `pin_build` revision, or at `revision` or in `binary_sha256` with `revision_from` saying where that was read. One naming none is read at `source_commit` |
| `display_name` | no | full display name (e.g. "Sega - Mega Drive (BlastEm)") |
| `logo` | no | image URL used on the emulator page |
| `systems` | no | list of system IDs this core handles |