From d5a25190a3df21de7e6d87f8de3ee478372edfb0 Mon Sep 17 00:00:00 2001 From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com> Date: Wed, 21 Oct 2026 12:39:03 +0200 Subject: [PATCH] fix: place standalone files in the linked folder standalone_path is relative to the directories a standalone build resolves it against, now declared per profile (standalone_directories). A launcher record that links or passes a whole folder of the BIOS tree under one of them gives that folder, and platform_layouts rebases the standalone view once for the builder, the manifest, verify and slots (launchers.standalone_root, common.standalone_destination). Flycast on RetroPie and ROCKNIX reads bios/dc, on EmuDeck bios/flycast/bios, on Batocera (FLYCAST_BIOS_PATH) and RetroBat (Dreamcast.BiosPath) bios/dc. The ROCKNIX, Batocera and RetroBat scrapers now record the patched data directory, the environment variable and the setting that say so. --- emulators/flycast.yml | 12 +- platforms/batocera.yml | 8 + platforms/retrobat.yml | 8 + platforms/rocknix.yml | 9 + schemas/emulator.schema.json | 7 + scripts/common.py | 74 ++++++- scripts/launchers.py | 128 +++++++++++ scripts/scraper/batocera_launchers.py | 42 +++- scripts/scraper/retrobat_launchers.py | 31 +++ scripts/scraper/rocknix_launchers.py | 47 ++++ tests/test_standalone_links.py | 303 ++++++++++++++++++++++++++ wiki/adding-a-platform.md | 9 +- wiki/profiling.md | 1 + wiki/testing-guide.md | 2 +- 14 files changed, 674 insertions(+), 7 deletions(-) create mode 100644 tests/test_standalone_links.py diff --git a/emulators/flycast.yml b/emulators/flycast.yml index fc46cf8e..f1d50a18 100644 --- a/emulators/flycast.yml +++ b/emulators/flycast.yml @@ -18,6 +18,12 @@ systems: - sega-naomi2 - sega-atomiswave - sega-systemsp +standalone_directories: + - "Dreamcast.BiosPath" + - "find_user_data_dir" + - "$XDG_DATA_HOME/flycast" + - "$HOME/.local/share/flycast" + - "FLYCAST_BIOS_PATH" notes: | The libretro core is built from flyinghead/flycast, the same tree as the @@ -46,7 +52,11 @@ notes: | macOS (core/windows/winmain.cpp:73-78, core/windows/winmain.cpp:86-89, shell/android-studio/flycast/src/main/jni/src/Android.cpp:149-159, shell/apple/emulator-osx/emulator-osx/osx-main.mm:97-101). - standalone_path is relative to the data directory. + standalone_path is relative to the data directory. The BIOS paths are the + Dreamcast.BiosPath setting (core/cfg/option.cpp:144), the system data + directories take $FLYCAST_BIOS_PATH (core/linux-dist/main.cpp:198-202), and + find_user_data_dir() returns the data directory + (core/linux-dist/main.cpp:74, core/linux-dist/main.cpp:247). Only the Dreamcast reads flat files. The prefix is dc_ for Dreamcast (core/hw/flashrom/nvmem.cpp:35-50), and the boot ROM is searched as diff --git a/platforms/batocera.yml b/platforms/batocera.yml index ea5f5912..3cab2c10 100644 --- a/platforms/batocera.yml +++ b/platforms/batocera.yml @@ -6111,6 +6111,14 @@ launchers: fails_when_missing: false depends_on_option: gsplus_bios_filename source_ref: "package/batocera/core/batocera-configgen/configgen/configgen/generators/gsplus/gsplusGenerator.py:105" +- emulator: flycast + build: standalone + kind: passes_path + names: [] + search_dir: /userdata/bios/dc + passes_to: environment FLYCAST_BIOS_PATH + fails_when_missing: false + source_ref: "package/batocera/core/batocera-configgen/configgen/configgen/generators/flycast/flycastGenerator.py:199" - emulator: o2em build: libretro kind: core_option diff --git a/platforms/retrobat.yml b/platforms/retrobat.yml index 122618d9..8a48b383 100644 --- a/platforms/retrobat.yml +++ b/platforms/retrobat.yml @@ -3238,6 +3238,14 @@ launchers: fails_when_missing: not checked by the launcher depends_on_option: duck_bios source_ref: "emulatorLauncher/Generators/Duckstation.Generator.cs:204-209, .emulationstation/es_features.cfg:11638-11646" +- emulator: flycast + build: standalone + kind: passes_path + names: [] + search_dir: bios/dc + passes_to: "emu.cfg [config] Dreamcast.BiosPath = bios/dc" + fails_when_missing: false + source_ref: "emulatorLauncher/Generators/Flycast.Generator.cs:149, 167" - emulator: jgenesis build: standalone kind: fixed_name diff --git a/platforms/rocknix.yml b/platforms/rocknix.yml index 28da7df6..7156ead1 100644 --- a/platforms/rocknix.yml +++ b/platforms/rocknix.yml @@ -757,6 +757,15 @@ launchers: source_ref: "projects/ROCKNIX/packages/emulators/standalone/armsx2-sa/config/S922X/ARMSX2/inis/PCSX2.ini:21,\ \ 475, projects/ROCKNIX/packages/emulators/standalone/armsx2-sa/config/inputplumber/ARMSX2/inis/PCSX2.ini:21,\ \ 473, projects/ROCKNIX/packages/emulators/standalone/armsx2-sa/package.mk:117-118" +- emulator: flycast + build: standalone + kind: passes_path + names: [] + search_dir: /storage/roms/dreamcast/data + passes_to: "find_user_data_dir() in core/linux-dist/main.cpp returns it" + fails_when_missing: false + source_ref: "projects/ROCKNIX/packages/emulators/standalone/flycast-sa/patches/000-conf-dir.patch:25,\ + \ 29" - emulator: drastic build: standalone kind: links diff --git a/schemas/emulator.schema.json b/schemas/emulator.schema.json index 2bd48c88..dd54993d 100644 --- a/schemas/emulator.schema.json +++ b/schemas/emulator.schema.json @@ -886,6 +886,13 @@ "type": "string", "description": "Branch the port was read from, when it is not the default one." }, + "standalone_directories": { + "type": "array", + "items": { + "type": "string" + }, + "description": "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 or the function returning the directory. A platform launcher record that links or passes a folder of its BIOS tree under one of these puts the standalone files in that folder." + }, "prose_written_at": { "type": "string", "pattern": "^[0-9a-f]{40}$", diff --git a/scripts/common.py b/scripts/common.py index daf45018..e67f3fb0 100644 --- a/scripts/common.py +++ b/scripts/common.py @@ -6,7 +6,7 @@ and file resolution - eliminates DRY violations across scripts. from __future__ import annotations -from collections.abc import Callable +from collections.abc import Callable, Iterable from collections import Counter import hashlib @@ -2249,6 +2249,9 @@ def runs_standalone( # Marks, in a platform's standalone set, an emulator it also launches as a # libretro core. No core name starts with it. DUAL_MODE_PREFIX = "dual:" +# Marks, in the same set, a whole directory the platform's launcher hands a +# standalone emulator (launchers.handed_directories), as JSON. +HANDED_PREFIX = "handed:" def standalone_set(config: dict) -> set[str]: @@ -2260,9 +2263,60 @@ def standalone_set(config: dict) -> set[str]: """ names = {str(c) for c in config.get("standalone_cores") or []} names |= {DUAL_MODE_PREFIX + str(c) for c in config.get("dual_mode_cores") or []} + if names: + from launchers import handed_directories # noqa: PLC0415 + + names |= { + HANDED_PREFIX + json.dumps( + [h.emulator, h.folder, h.directory, sorted(h.handles), h.source_ref] + ) + for h in handed_directories(config) + } return names +def _handed(standalone_cores: Iterable[str]) -> list: + """The directories a standalone set carries, as launchers built them.""" + from launchers import HandedDirectory # noqa: PLC0415 + + found = [] + for tag in standalone_cores: + if not tag.startswith(HANDED_PREFIX): + continue + emulator, folder, directory, handles, ref = json.loads(tag[len(HANDED_PREFIX):]) + found.append(HandedDirectory(emulator, folder, directory, frozenset(handles), ref)) + return found + + +def standalone_destination(entry: dict, root: str | None) -> str: + """Where a standalone build reads an entry, relative to the BIOS root. + + ``standalone_path`` is relative to the directories the build resolves + it against (``standalone_directories``). A platform that hands one of + them a folder of its BIOS tree puts the file under that folder: + RetroPie and ROCKNIX give Flycast bios/dc, EmuDeck bios/flycast/bios. + An entry with no ``standalone_path`` keeps ``path``, the layout both + builds share. + """ + own = entry.get("standalone_path") + if own and root: + return f"{root}/{own}" + return own or entry.get("path") or entry.get("name", "") + + +def standalone_root_for( + emu_name: str, profile: dict, standalone_cores: Iterable[str] +) -> str | None: + """The folder a platform gives this emulator's standalone layout, or None.""" + declared = profile.get("standalone_directories") or [] + if not declared: + return None + from launchers import standalone_root # noqa: PLC0415 + + names = {emu_name, *(str(c) for c in profile.get("cores") or [])} + return standalone_root(names, declared, _handed(standalone_cores)) + + def platform_layouts( emu_name: str, profile: dict, standalone_cores: set[str] ) -> list[tuple[dict, bool]]: @@ -2275,13 +2329,27 @@ def platform_layouts( """ if not runs_standalone(emu_name, profile, standalone_cores): return [(profile, False)] + standalone = profile + root = standalone_root_for(emu_name, profile, standalone_cores) + if root: + # The standalone view carries the platform's destination, so every + # reader of standalone_path (builder, manifest, verify, slots) places + # the file in the folder the platform hands the emulator. + standalone = { + **profile, + "files": [ + {**f, "standalone_path": standalone_destination(f, root)} + if isinstance(f, dict) and f.get("standalone_path") else f + for f in profile.get("files") or [] + ], + } dual = {c.removeprefix(DUAL_MODE_PREFIX) for c in standalone_cores if c.startswith(DUAL_MODE_PREFIX)} if "libretro" in str(profile.get("type", "")) and dual & { emu_name, *(str(c) for c in profile.get("cores", [])) }: - return [(profile, False), (profile, True)] - return [(profile, True)] + return [(profile, False), (standalone, True)] + return [(standalone, True)] # What identifies a profile entry's content, carried unchanged wherever the diff --git a/scripts/launchers.py b/scripts/launchers.py index e12b21f5..19d1f378 100644 --- a/scripts/launchers.py +++ b/scripts/launchers.py @@ -186,6 +186,134 @@ def launcher_places(config: dict) -> list[LauncherPlace]: return places +# The names a platform's launch code gives its BIOS root, besides the +# base_destination _bios_relative reads: RetroPie's scriptmodules set +# biosdir="$home/RetroPie/BIOS", EmuDeck's scripts ${biosPath}, RetroDECK's +# component scripts $bios_path. +BIOS_ROOT_VARIABLES = ("$biosdir", "$home/RetroPie/BIOS", "${biosPath}", "$bios_path") + +# The kinds that hand an emulator a whole directory. +HANDED_KINDS = ("links", "passes_path") + +_HOME = re.compile(r"^(?:\$\{HOME\}|\$HOME|\$home|~)(?=/|$)") +# Flatpak sets XDG_DATA_HOME to ~/.var/app//data inside the sandbox. +_FLATPAK_DATA = re.compile(r"^~/\.var/app/[^/]+/data(?=/|$)") + + +def normalize_handle(token: str) -> str: + """One spelling for a path, setting or function a launcher record names. + + ``$home``, ``$HOME``, ``${HOME}`` and ``~`` are one directory, and a + Flatpak's data directory is its ``$XDG_DATA_HOME``. + """ + token = token.strip().strip("\"'").rstrip(",;").rstrip("/") + token = token.removesuffix("()") + token = _HOME.sub("~", token) + return _FLATPAK_DATA.sub("$XDG_DATA_HOME", token) + + +def _folder_in_bios(directory: str, base: str) -> str | None: + """A directory relative to the BIOS root, None when it lies outside.""" + relative = _bios_relative(directory, base) + if relative is not None: + return relative + directory = directory.strip().rstrip("/") + for variable in BIOS_ROOT_VARIABLES: + if directory == variable: + return "" + if directory.startswith(variable + "/"): + rest = directory[len(variable) + 1:] + return None if re.search(r"[\s<>$:;]", rest) else rest + return None + + +@dataclass(frozen=True) +class HandedDirectory: + """A whole directory a platform hands a standalone emulator. + + ``folder`` is the directory relative to the BIOS root, None when it lies + outside it. ``handles`` are the paths, settings and functions the record + names on the emulator's side: the link's other end, the config key, the + function a patch rewrites. + """ + + emulator: str + folder: str | None + directory: str + handles: frozenset[str] + source_ref: str + + +def handed_directories(config: dict) -> list[HandedDirectory]: + """Every whole directory a platform links or passes to a standalone build. + + A record naming files (gpsp's gba_bios.bin) or one slot of a directory + (RetroDECK's GC/EUR) hands over no whole directory, and a search_dir + holding several directories names no single one. + """ + base = str(config.get("base_destination") or "bios") + found: list[HandedDirectory] = [] + for record in config.get("launchers") or []: + if record.get("build") != "standalone" or record.get("kind") not in HANDED_KINDS: + continue + if record.get("names") or record.get("slot"): + continue + raw = str(record.get("search_dir") or "").strip() + if not raw or re.search(r"[\s,:;]", raw): + continue + directory = normalize_handle(raw) + handles = frozenset( + handle + for token in str(record.get("passes_to") or "").split() + if (handle := normalize_handle(token)) and handle != directory + ) + for emulator in (e.strip() for e in str(record.get("emulator", "")).split(",")): + found.append(HandedDirectory( + emulator=emulator, + folder=_folder_in_bios(raw, base), + directory=directory, + handles=handles, + source_ref=str(record.get("source_ref", "")), + )) + return found + + +def standalone_root( + names: Iterable[str], declared: Iterable[str], handed: Iterable[HandedDirectory] +) -> str | None: + """The folder of the BIOS tree a platform gives a standalone build's layout. + + ``declared`` are the directories the build resolves ``standalone_path`` + against, as its profile names them (``standalone_directories``). A + record handing a folder of the BIOS tree under one of them gives it + directly: RetroPie points Flycast's ~/.local/share/flycast at bios/dc. A + record handing a directory outside the tree under one of them is + followed through a link to the tree: ROCKNIX's patched Flycast uses + /storage/roms/dreamcast/data, which its start script links to bios/dc. + + None when nothing gives a folder, or when two records give two: the + layout is then the profile's, relative to the BIOS root. + """ + names = set(names) + wanted = {normalize_handle(d) for d in declared} + if not wanted: + return None + records = [h for h in handed if h.emulator in names] + folders: set[str] = set() + for record in records: + if not record.handles & wanted: + continue + if record.folder is not None: + folders.add(record.folder) + continue + folders.update( + link.folder + for link in records + if link.folder is not None and record.directory in link.handles + ) + return next(iter(folders)) if len(folders) == 1 else None + + def declared_destinations(config: dict) -> set[str]: """Each destination the platform declares, relative to the core file directory. diff --git a/scripts/scraper/batocera_launchers.py b/scripts/scraper/batocera_launchers.py index c53edc6a..eb11b148 100644 --- a/scripts/scraper/batocera_launchers.py +++ b/scripts/scraper/batocera_launchers.py @@ -647,6 +647,46 @@ def gsplus(cg: Configgen) -> list[Launcher]: )] +# Generators that hand a directory of /userdata/bios to the emulator through +# its environment, with the module holding their path constants. +ENVIRONMENT_GENERATORS = (("flycast.flycastGenerator", "flycast/flycastPaths.py"),) + + +def environment_directories(cg: Configgen) -> list[Launcher]: + """Command(..., env={KEY: }) in the generator.""" + launchers = [] + for module, paths_module in ENVIRONMENT_GENERATORS: + src = cg.generator(module) + constants = dict(cg.paths) + for node in cg.source(f"{GENERATORS}/{paths_module}").tree.body: + name = _assigned_name(node) + value = _path_value(getattr(node, "value", None), constants) + if name is not None and value is not None: + constants[name] = value + prefix = cg.bios.rstrip("/") + found = [ + (key.value, value, key) + for call in _calls(src.tree, attr="Command") + for keyword in call.keywords + if keyword.arg == "env" and isinstance(keyword.value, ast.Dict) + for key, item in zip(keyword.value.keys, keyword.value.values) + if isinstance(key, ast.Constant) + and (value := _path_value(item, constants)) is not None + and (value == prefix or value.startswith(prefix + "/")) + ] + if not found: + src.fail("the command environment names no /userdata/bios directory") + launchers.extend( + Launcher( + emulator=cg.emulator(module), build="standalone", kind="passes_path", + names=[], search_dir=value, passes_to=f"environment {key}", + source_ref=src.ref([(node.lineno, node.end_lineno)]), + ) + for key, value, node in found + ) + return launchers + + # libretro core options whose value names the BIOS file the core opens. FILE_OPTIONS = (("_o2em_options", "o2em_bios"), ("_neocd_options", "neocd_bios")) @@ -701,7 +741,7 @@ def core_file_options(cg: Configgen) -> list[Launcher]: EXTRACTORS: tuple[Callable[[Configgen], list[Launcher]], ...] = ( duckstation, duckstation_legacy, hatari, xemu, melonds, mupen64plus, - x16emu, gsplus, core_file_options, + x16emu, gsplus, environment_directories, core_file_options, ) diff --git a/scripts/scraper/retrobat_launchers.py b/scripts/scraper/retrobat_launchers.py index eeb68a5d..2e79e225 100644 --- a/scripts/scraper/retrobat_launchers.py +++ b/scripts/scraper/retrobat_launchers.py @@ -22,6 +22,7 @@ SOURCE_FILES = ( f"{GENERATORS}/Ares.Generator.cs", f"{GENERATORS}/Bizhawk.Generator.cs", f"{GENERATORS}/Duckstation.Generator.cs", + f"{GENERATORS}/Flycast.Generator.cs", f"{GENERATORS}/Hatari.Generator.cs", f"{GENERATORS}/Jgenesis.Generator.cs", f"{GENERATORS}/KegaFusion.Generator.cs", @@ -1185,6 +1186,35 @@ def duckstation(sources: dict[str, Source]) -> list[Record]: ] +def flycast(sources: dict[str, Source]) -> list[Record]: + src = sources[f"{GENERATORS}/Flycast.Generator.cs"] + folder = src.find( + r'string biosPath = Path\.Combine\(' + BIOS + r', "(\w+)"\);', "biosPath under bios" + ) + write = src.find( + r'ini\.WriteValue\("(\w+)", "(Dreamcast\.BiosPath)", biosPath\);', + "Dreamcast.BiosPath write", + folder.end(), + ) + return [ + _record( + "flycast", + "standalone", + "passes_path", + [], + source_ref( + ( + src.path, + [src.lines(folder.start(), folder.end()), src.lines(write.start(), write.end())], + ) + ), + search_dir=f"bios/{folder.group(1)}", + passes_to=f"emu.cfg [{write.group(1)}] {write.group(2)} = bios/{folder.group(1)}", + fails_when_missing=False, + ) + ] + + # Generators that write each BIOS path into the emulator's configuration # only when the file exists: string x = Path.Combine(bios, ..., "name"); # if (File.Exists(x)) ini.WriteValue("section", "key", x). @@ -1401,6 +1431,7 @@ EXTRACTORS: tuple[Callable[[dict[str, Source]], list[Record]], ...] = ( amiberry, ares, duckstation, + flycast, guarded_writes, hatari, hatari_libretro, diff --git a/scripts/scraper/rocknix_launchers.py b/scripts/scraper/rocknix_launchers.py index 55a8a5de..8aed2554 100644 --- a/scripts/scraper/rocknix_launchers.py +++ b/scripts/scraper/rocknix_launchers.py @@ -612,6 +612,52 @@ def links(tree: RepoTree) -> list[Launcher]: return records +# Packages whose build patch replaces the function an emulator resolves a +# directory with by a fixed path: ROCKNIX's Flycast returns +# /storage/roms/dreamcast/data as its data directory, which start_flycast.sh +# then links to the BIOS tree. +DIRECTORY_PATCHES = ( + ("flycast", f"{STANDALONE}/flycast-sa/patches/000-conf-dir.patch", "find_user_data_dir"), +) + + +def patched_directories(tree: RepoTree) -> list[Launcher]: + records = [] + for emulator, path, function in DIRECTORY_PATCHES: + lines = tree.read(path).splitlines() + target = next( + (line[len("+++ b/"):] for line in lines if line.startswith("+++ b/")), None + ) + start = next( + (n for n, line in enumerate(lines, 1) if re.search(rf"\b{function}\(\)", line)), + None, + ) + returned = None + if target is not None and start is not None: + returned = next( + ( + (n, match.group(1)) + for n, line in enumerate(lines[start:], start + 1) + if (match := re.match(r'^\+\s*return "(/[^"]+)";', line)) + ), + None, + ) + if returned is None: + raise LauncherPatternMissing(path, f"{function}() patched to return a fixed path") + number, directory = returned + records.append(Launcher( + emulator=emulator, + build="standalone", + kind="passes_path", + names=[], + source_ref=source_ref([(path, {start, number})]), + search_dir=directory.rstrip("/"), + passes_to=f"{function}() in {target} returns it", + fails_when_missing=False, + )) + return records + + def _existence_guard(script: Script, link: Link) -> int | None: """The line of a -e test of the BIOS-side path the link waits for, if any.""" last = max(link.lines) @@ -639,6 +685,7 @@ EXTRACTORS: tuple[Callable[[RepoTree], list[Launcher]], ...] = ( duckstation, aethersx2, armsx2, + patched_directories, links, ) diff --git a/tests/test_standalone_links.py b/tests/test_standalone_links.py new file mode 100644 index 00000000..6062eb2d --- /dev/null +++ b/tests/test_standalone_links.py @@ -0,0 +1,303 @@ +"""A standalone build's files land in the folder its platform hands it. + +``standalone_path`` is relative to the directories the standalone build +resolves it against (``standalone_directories``). RetroPie links Flycast's +~/.local/share/flycast to bios/dc and writes Dreamcast.BiosPath, ROCKNIX +patches Flycast's data directory to /storage/roms/dreamcast/data and links +that to bios/dc, EmuDeck links the Flatpak's data directory to +bios/flycast/bios, Batocera sets FLYCAST_BIOS_PATH and RetroBat +Dreamcast.BiosPath to bios/dc. Laid out at the BIOS root instead, Flycast's +naomi.zip took the place of MAME's. +""" + +from __future__ import annotations + +import sys +import textwrap +import unittest +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent +sys.path.insert(0, str(REPO_ROOT / "scripts")) + +from common import ( # noqa: E402 + load_emulator_profiles, + load_platform_config, + platform_layouts, + standalone_destination, + standalone_root_for, + standalone_set, +) +from launchers import handed_directories, normalize_handle, standalone_root # noqa: E402 + + +def link(emulator: str, search_dir: str, passes_to: str, **fields: object) -> dict: + return { + "emulator": emulator, "build": "standalone", "kind": "links", "names": [], + "search_dir": search_dir, "passes_to": passes_to, "source_ref": "x.sh:1", + **fields, + } + + +def passes(emulator: str, search_dir: str, passes_to: str) -> dict: + return {**link(emulator, search_dir, passes_to), "kind": "passes_path"} + + +PROFILE = { + "emulator": "Emu", + "type": "standalone + libretro", + "cores": ["emu_core"], + "standalone_directories": ["$XDG_DATA_HOME/emu", "$HOME/.local/share/emu", "find_user_data_dir"], + "files": [ + {"name": "boot.bin", "path": "dc/boot.bin", "standalone_path": "boot.bin"}, + {"name": "set.zip", "path": "dc/set.zip", "standalone_path": "set.zip"}, + {"name": "shared.bin", "path": "dc/shared.bin"}, + ], +} + + +def config(*launchers: dict, base: str = "bios") -> dict: + return {"base_destination": base, "standalone_cores": ["emu"], "launchers": list(launchers)} + + +def standalone_view(cfg: dict) -> dict: + views = platform_layouts("emu", PROFILE, standalone_set(cfg)) + return next(view for view, standalone in views if standalone) + + +class HandleSpelling(unittest.TestCase): + def test_home_and_flatpak_spellings_are_one_directory(self) -> None: + self.assertEqual(normalize_handle("$home/.local/share/emu"), "~/.local/share/emu") + self.assertEqual(normalize_handle("${HOME}/.local/share/emu/"), "~/.local/share/emu") + self.assertEqual( + normalize_handle("${HOME}/.var/app/org.emu.Emu/data/emu/"), "$XDG_DATA_HOME/emu" + ) + self.assertEqual(normalize_handle("find_user_data_dir()"), "find_user_data_dir") + + +class HandedDirectories(unittest.TestCase): + def test_retropie_variable_resolves_to_a_bios_folder(self) -> None: + found = handed_directories(config( + link("emu", "$biosdir/dc", "$home/.local/share/emu is a symlink to it"), base="BIOS", + )) + self.assertEqual([h.folder for h in found], ["dc"]) + self.assertIn("~/.local/share/emu", found[0].handles) + + def test_named_and_slotted_links_hand_no_directory(self) -> None: + found = handed_directories(config( + {**link("emu", "$biosdir", "$md_inst/"), "names": ["boot.bin"]}, + {**link("emu", "$bios_path/gc/EU", "$XDG_DATA_HOME/emu/GC/EUR"), "slot": "EUR"}, + )) + self.assertEqual(found, []) + + def test_directory_outside_the_tree_has_no_folder(self) -> None: + found = handed_directories(config( + passes("emu", "/storage/roms/dreamcast/data", "find_user_data_dir() returns it"), + )) + self.assertIsNone(found[0].folder) + + +class Root(unittest.TestCase): + def root(self, *launchers: dict, base: str = "bios") -> str | None: + return standalone_root( + {"emu"}, PROFILE["standalone_directories"], handed_directories(config(*launchers, base=base)) + ) + + def test_link_of_the_data_directory_gives_its_folder(self) -> None: + self.assertEqual( + self.root(link("emu", "$biosdir/dc", "$home/.local/share/emu is a symlink to it")), + "dc", + ) + + def test_flatpak_data_directory(self) -> None: + self.assertEqual( + self.root(link( + "emu", "${biosPath}/emu/bios", + "symlink ${biosPath}/emu/bios -> ${HOME}/.var/app/org.emu.Emu/data/emu/", + )), + "emu/bios", + ) + + def test_patched_data_directory_followed_through_its_link(self) -> None: + self.assertEqual( + self.root( + passes("emu", "/storage/roms/dreamcast/data", "find_user_data_dir() returns it"), + link("emu", "/storage/roms/bios/dc", + "symlink /storage/roms/dreamcast/data -> /storage/roms/bios/dc"), + ), + "dc", + ) + + def test_link_of_another_directory_gives_nothing(self) -> None: + # A subfolder of the emulator's tree (Dolphin's Triforce) is not the + # directory standalone_path is relative to. + self.assertIsNone(self.root( + link("emu", "$bios_path/Triforce", "$XDG_DATA_HOME/emu/Triforce is a symlink to it"), + )) + + def test_two_folders_give_nothing(self) -> None: + self.assertIsNone(self.root( + link("emu", "$biosdir/dc", "$home/.local/share/emu is a symlink to it"), + link("emu", "$biosdir/other", "$XDG_DATA_HOME/emu is a symlink to it"), + )) + + +class Layout(unittest.TestCase): + LINKED = link("emu", "$biosdir/dc", "$home/.local/share/emu is a symlink to it") + + def test_standalone_view_takes_the_linked_folder(self) -> None: + view = standalone_view(config(self.LINKED, base="BIOS")) + self.assertEqual( + [f.get("standalone_path") for f in view["files"]], ["dc/boot.bin", "dc/set.zip", None] + ) + self.assertEqual(view["files"][2]["path"], "dc/shared.bin") + + def test_without_a_link_the_profile_layout_stands(self) -> None: + view = standalone_view(config()) + self.assertEqual([f.get("standalone_path") for f in view["files"]][:2], ["boot.bin", "set.zip"]) + + def test_profile_is_not_changed(self) -> None: + standalone_view(config(self.LINKED, base="BIOS")) + self.assertEqual(PROFILE["files"][0]["standalone_path"], "boot.bin") + + def test_libretro_view_keeps_path(self) -> None: + cfg = {**config(self.LINKED, base="BIOS"), "dual_mode_cores": ["emu"]} + views = platform_layouts("emu", PROFILE, standalone_set(cfg)) + libretro = next(view for view, standalone in views if not standalone) + self.assertIs(libretro, PROFILE) + + def test_union_of_platforms_with_two_folders_keeps_the_profile_layout(self) -> None: + union = standalone_set(config(self.LINKED, base="BIOS")) | standalone_set(config( + link("emu", "${biosPath}/emu/bios", "symlink ${biosPath}/emu/bios -> ${HOME}/.local/share/emu"), + )) + self.assertIsNone(standalone_root_for("emu", PROFILE, union)) + + def test_destination_function(self) -> None: + entry = PROFILE["files"][0] + self.assertEqual(standalone_destination(entry, "dc"), "dc/boot.bin") + self.assertEqual(standalone_destination(entry, None), "boot.bin") + self.assertEqual(standalone_destination(PROFILE["files"][2], "dc"), "dc/shared.bin") + + +class FlycastOnEachPlatform(unittest.TestCase): + """The real profile against the real launcher records.""" + + EXPECTED = { + "batocera": "dc", + "emudeck": "flycast/bios", + "retrobat": "dc", + "retropie": "dc", + "rocknix": "dc", + } + + @classmethod + def setUpClass(cls) -> None: + cls.profile = load_emulator_profiles(str(REPO_ROOT / "emulators"))["flycast"] + + def test_each_platform_hands_flycast_its_folder(self) -> None: + for platform, folder in self.EXPECTED.items(): + with self.subTest(platform=platform): + cfg = load_platform_config(platform, str(REPO_ROOT / "platforms")) + self.assertEqual( + standalone_root_for("flycast", self.profile, standalone_set(cfg)), folder + ) + + def test_no_standalone_file_lands_at_the_bios_root(self) -> None: + # Flycast's naomi.zip and awbios.zip share their names with MAME's + # root archives: at the root they replace them. + for platform, folder in self.EXPECTED.items(): + with self.subTest(platform=platform): + cfg = load_platform_config(platform, str(REPO_ROOT / "platforms")) + for view, standalone in platform_layouts( + "flycast", self.profile, standalone_set(cfg) + ): + if not standalone: + continue + for entry in view["files"]: + self.assertTrue( + entry["standalone_path"].startswith(folder + "/"), + entry["standalone_path"], + ) + + +class Scrapers(unittest.TestCase): + """The records each platform's scraper writes for these directories.""" + + def test_rocknix_patched_data_directory(self) -> None: + from scraper import rocknix_launchers as rl + from scraper.shell_launchers import LauncherPatternMissing, RepoTree + + path = f"{rl.STANDALONE}/flycast-sa/patches/000-conf-dir.patch" + patch = textwrap.dedent("""\ + --- a/core/linux-dist/main.cpp + +++ b/core/linux-dist/main.cpp + @@ -69,12 +69,17 @@ + static std::string find_user_data_dir() + { + +#ifdef __unix__ + +\tflycast::mkdir("/storage/roms/dreamcast/data", 0755); + +\treturn "/storage/roms/dreamcast/data/"; + +#else + """) + records = rl.patched_directories(RepoTree.from_files({path: patch})) + self.assertEqual(len(records), 1) + entry = records[0].entry() + self.assertEqual(entry["search_dir"], "/storage/roms/dreamcast/data") + self.assertEqual(entry["passes_to"], "find_user_data_dir() in core/linux-dist/main.cpp returns it") + self.assertEqual(entry["source_ref"], f"{path}:4, 8") + with self.assertRaises(LauncherPatternMissing): + rl.patched_directories(RepoTree.from_files({path: patch.replace("return", "x =")})) + + def test_batocera_environment_directory(self) -> None: + from scraper.batocera_launchers import ( + GENERATORS, IMPORTER, PATHS_MODULE, Configgen, environment_directories, + ) + from scraper.configgen_launchers import LauncherShapeError + + paths = "from pathlib import Path\nBIOS = Path('/userdata/bios')\nCONFIGS = Path('/userdata/system/configs')\n" + importer = "_GENERATOR_MAP = {}\n_LEGACY_GENERATOR_MAP = {}\n" + flycast_paths = "from ...batoceraPaths import BIOS\nFLYCAST_BIOS = BIOS / 'dc'\n" + generator = textwrap.dedent("""\ + def generate(self): + return Command.Command( + array=[], + env={ + "XDG_CONFIG_HOME": CONFIGS, + "FLYCAST_BIOS_PATH": FLYCAST_BIOS, + } + ) + """) + tree = { + PATHS_MODULE: paths, + IMPORTER: importer, + f"{GENERATORS}/flycast/flycastPaths.py": flycast_paths, + f"{GENERATORS}/flycast/flycastGenerator.py": generator, + } + records = [r.entry() for r in environment_directories(Configgen(tree.__getitem__))] + self.assertEqual(len(records), 1) + self.assertEqual(records[0]["search_dir"], "/userdata/bios/dc") + self.assertEqual(records[0]["passes_to"], "environment FLYCAST_BIOS_PATH") + self.assertTrue(records[0]["source_ref"].endswith("flycastGenerator.py:6")) + tree[f"{GENERATORS}/flycast/flycastGenerator.py"] = generator.replace("FLYCAST_BIOS,", "CONFIGS,") + with self.assertRaises(LauncherShapeError): + environment_directories(Configgen(tree.__getitem__)) + + def test_retrobat_bios_path_setting(self) -> None: + from scraper import retrobat_launchers as rl + + path = f"{rl.GENERATORS}/Flycast.Generator.cs" + text = textwrap.dedent("""\ + string biosPath = Path.Combine(AppConfig.GetFullPath("bios"), "dc"); + ini.Remove("config", "Dreamcast.BiosPath"); + ini.WriteValue("config", "Dreamcast.BiosPath", biosPath); + """) + records = rl.flycast({path: rl.Source(path, text)}) + self.assertEqual(records[0]["search_dir"], "bios/dc") + self.assertEqual(records[0]["passes_to"], "emu.cfg [config] Dreamcast.BiosPath = bios/dc") + self.assertEqual(records[0]["source_ref"], f"{path}:1-3") + with self.assertRaises(rl.LauncherPatternMissing): + rl.flycast({path: rl.Source(path, text.replace("Dreamcast.BiosPath", "X"))}) + + +if __name__ == "__main__": + unittest.main() diff --git a/wiki/adding-a-platform.md b/wiki/adding-a-platform.md index 166bac8f..81f017c3 100644 --- a/wiki/adding-a-platform.md +++ b/wiki/adding-a-platform.md @@ -182,7 +182,14 @@ resolved. Three strategies exist: - **Omitted**: fallback to system ID intersection, `built_by` profiles excluded. Two lists say how each resolved emulator is laid out. `standalone_cores` names the -ones the platform launches as standalone apps: their files go to `standalone_path`. +ones the platform launches as standalone apps: their files go to `standalone_path`, +under the folder the platform hands the emulator when its `launchers:` say so. A +`links` or `passes_path` record of a whole directory that names one of the profile's +`standalone_directories` gives that folder (`launchers.standalone_root`): RetroPie +links Flycast's `~/.local/share/flycast` to `BIOS/dc`, EmuDeck the Flatpak's data +directory to `bios/flycast/bios`, and ROCKNIX's patched data directory is followed +through the link its start script makes. Two records giving two folders leave the +profile's layout. `dual_mode_cores` names those it launches both ways (RetroPie packages `lr-hatari` and `hatari`): both layouts are packed. A profile without a standalone build keeps its libretro layout whatever the platform calls it. diff --git a/wiki/profiling.md b/wiki/profiling.md index ebf96a27..726e8620 100644 --- a/wiki/profiling.md +++ b/wiki/profiling.md @@ -493,6 +493,7 @@ reports the profile as uncheckable, and the CI job that runs | `built_by` | no | platforms that ship this build under its core name, compiled by them or installed from the project's own release (Recalbox's `mame0278`, the GSplus legacy build). On those platforms the name resolves to this profile, never through `all_libretro`: the buildbot does not publish it | | `bios_mode` | no | `agnostic` when the core takes any file of the right shape in its BIOS folder instead of a fixed name (PCSX2). Packs then carry every matching dump, and a `.bin` placeholder stands for them | | `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 | | `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 | diff --git a/wiki/testing-guide.md b/wiki/testing-guide.md index 83621b18..0d4ad355 100644 --- a/wiki/testing-guide.md +++ b/wiki/testing-guide.md @@ -39,7 +39,7 @@ Every module in `tests/`, by the area it guards. |------|----------|---------| | Core regression suites | synthetic | `test_e2e`, `test_audit_regressions`, `test_tool_messages` | | File resolution and identity | synthetic + collection | `test_adler32_resolution`, `test_agnostic_scan`, `test_agnostic_scan_mode`, `test_agnostic_scope`, `test_agnostic_substitute`, `test_archive_choice`, `test_bios_companions`, `test_bundled_identity`, `test_casefold_cache`, `test_db_aliases`, `test_declared_names`, `test_derivations`, `test_directory_entries`, `test_extra_identity`, `test_foreign_tree`, `test_foreign_tree_names`, `test_frontend_digest`, `test_game_data_homonyms`, `test_hashing`, `test_identity`, `test_md5_pack_context`, `test_name_tiebreak`, `test_nec_filing`, `test_owner_resolution`, `test_path_suffix`, `test_resolution_evidence`, `test_shipped_content`, `test_twin_declarations`, `test_validated_choice`, `test_variant_choice`, `test_variant_identity`, `test_zipped_member` | -| Verification, cross-reference and profile checks | synthetic + profiles | `test_crypto_aes`, `test_crypto_unique_data`, `test_crypto_verify`, `test_case_insensitive_platforms`, `test_checks_have_values`, `test_core_file_fills_declaration`, `test_core_size_refusal`, `test_cross_reference_sources`, `test_file_consumers`, `test_fileless_audit`, `test_gap_settlement`, `test_hidden_extras`, `test_flycast_layout`, `test_launcher_aliases`, `test_launcher_layer`, `test_native_mode`, `test_no_case_collisions`, `test_path_conflict_status`, `test_path_null_copies`, `test_profile_checks`, `test_profile_repositories`, `test_romm_hash_rule`, `test_shared_groups`, `test_standalone_mode`, `test_undeclared_dedup`, `test_unplaced_extras`, `test_validation_scope`, `test_verify_all_dir`, `test_verify_emulator_evidence`, `test_verify_listing`, `test_verify_pack_choice`, `test_verify_release_asset` | +| Verification, cross-reference and profile checks | synthetic + profiles | `test_crypto_aes`, `test_crypto_unique_data`, `test_crypto_verify`, `test_case_insensitive_platforms`, `test_checks_have_values`, `test_core_file_fills_declaration`, `test_core_size_refusal`, `test_cross_reference_sources`, `test_file_consumers`, `test_fileless_audit`, `test_gap_settlement`, `test_hidden_extras`, `test_flycast_layout`, `test_launcher_aliases`, `test_launcher_layer`, `test_native_mode`, `test_no_case_collisions`, `test_path_conflict_status`, `test_path_null_copies`, `test_profile_checks`, `test_profile_repositories`, `test_romm_hash_rule`, `test_shared_groups`, `test_standalone_links`, `test_standalone_mode`, `test_undeclared_dedup`, `test_unplaced_extras`, `test_validation_scope`, `test_verify_all_dir`, `test_verify_emulator_evidence`, `test_verify_listing`, `test_verify_pack_choice`, `test_verify_release_asset` | | Packs and manifests | synthetic + real packs | `test_artifact_lock`, `test_atomic_artifacts`, `test_batocera_cores`, `test_deterministic_zip`, `test_emulator_pack_counts`, `test_finalize_pack_names`, `test_large_file_cache`, `test_libretro_layout`, `test_manifest_entry`, `test_pack_conformance_dirs`, `test_pack_core_extras`, `test_pack_counts`, `test_pack_destinations`, `test_pack_failures`, `test_pack_file_names`, `test_pack_grouping`, `test_pack_integrity`, `test_pack_member_identity`, `test_pack_readme`, `test_platform_inheritance`, `test_platform_keys`, `test_required_only_archives`, `test_required_only_twins`, `test_split_extras`, `test_split_names`, `test_split_pack`, `test_system_pack_extras`, `test_system_pack_parity`, `test_torrentzip`, `test_which_pack` | | Slots and regions | synthetic + profiles | `test_region`, `test_region_agnostic_scan`, `test_region_groups`, `test_region_held`, `test_region_platform_index`, `test_region_required_only`, `test_slot`, `test_slots`, `test_slots_shipped_file` | | Hardware targets and systems | synthetic + target files | `test_extract_targets`, `test_lakka_targets`, `test_libretro_slugs`, `test_system_ids`, `test_system_selection`, `test_target_names`, `test_target_scrapers`, `test_target_systems`, `test_target_verify` |