mirror of
https://github.com/Abdess/retroarch_system.git
synced 2026-11-16 06:44:43 -06:00
chore: merge origin/main
This commit is contained in:
commit
cfc950b834
45 files changed
+1427
-83
No files matched your search
@@ -518,7 +518,8 @@ def _data_directory_members(
|
||||
gets it from the tree's archive.
|
||||
|
||||
``refs_out``, when given, maps each yielded destination to
|
||||
(registry key, system ids, directory destination), for the manifest.
|
||||
(registry key, system ids, directory destination, whether the core
|
||||
needs the tree), for the manifest.
|
||||
|
||||
These are not BIOS and carry no hash of their own: they are whole
|
||||
trees an emulator reads, refreshed from upstream, so what ships is
|
||||
@@ -532,7 +533,8 @@ def _data_directory_members(
|
||||
ref_key = dd.get("ref", "")
|
||||
if not ref_key or not data_registry or ref_key not in data_registry:
|
||||
continue
|
||||
if required_only and dd.get("required") is False:
|
||||
needed = dd.get("required") is not False
|
||||
if required_only and not needed:
|
||||
continue
|
||||
if ref_key in installed_data_refs(platform_name):
|
||||
continue
|
||||
@@ -567,7 +569,7 @@ def _data_directory_members(
|
||||
):
|
||||
del reclaim[full]
|
||||
if refs_out is not None:
|
||||
refs_out[full] = (ref_key, systems, dd_prefix)
|
||||
refs_out[full] = (ref_key, systems, dd_prefix, needed)
|
||||
yield src, full
|
||||
continue
|
||||
if full in seen_destinations or (
|
||||
@@ -581,7 +583,7 @@ def _data_directory_members(
|
||||
if case_insensitive:
|
||||
seen_lower.add(full.lower())
|
||||
if refs_out is not None:
|
||||
refs_out[full] = (ref_key, systems, dd_prefix)
|
||||
refs_out[full] = (ref_key, systems, dd_prefix, needed)
|
||||
yield src, full
|
||||
|
||||
|
||||
@@ -4910,7 +4912,7 @@ def generate_manifest(
|
||||
# Phase 3: data directories. They are not files of the collection: the
|
||||
# installer fetches each from its source archive and keeps the members
|
||||
# whose hash the list below records, the same tree the pack carries.
|
||||
data_refs: dict[str, tuple[str, tuple[str, ...], str]] = {}
|
||||
data_refs: dict[str, tuple[str, tuple[str, ...], str, bool]] = {}
|
||||
reclaim = {full: path for full, (path, _size) in cache_held.items()}
|
||||
data_members = list(_data_directory_members(
|
||||
pack_systems, data_registry, platform_name, base_dest,
|
||||
@@ -5021,7 +5023,7 @@ def generate_manifest(
|
||||
|
||||
def _manifest_data_directories(
|
||||
members: list[tuple[str, str]],
|
||||
refs: dict[str, tuple[str, tuple[str, ...], str]],
|
||||
refs: dict[str, tuple[str, tuple[str, ...], str, bool]],
|
||||
registry: dict,
|
||||
base_dest: str,
|
||||
) -> list[dict]:
|
||||
@@ -5034,11 +5036,14 @@ def _manifest_data_directories(
|
||||
changed since is refused rather than installed. archive_size is the
|
||||
size of the archive refresh_data_dirs last downloaded, what fetching
|
||||
the tree costs: a tarball whose tree is 10 KB is a download of 21 MB.
|
||||
``optional`` marks a tree every core reading it runs without
|
||||
(``required: false``): install.py --required-only leaves it out, as the
|
||||
pack built with --required-only does.
|
||||
"""
|
||||
grouped: dict[tuple[str, str], dict] = {}
|
||||
versions: dict[str, dict[str, dict]] = {}
|
||||
for src, full in members:
|
||||
ref, systems, prefix = refs[full]
|
||||
ref, systems, prefix, needed = refs[full]
|
||||
entry = registry.get(ref, {})
|
||||
key = (ref, prefix)
|
||||
group = grouped.get(key)
|
||||
@@ -5072,11 +5077,19 @@ def _manifest_data_directories(
|
||||
size = versions[str(recorded)].get(ref, {}).get("archive_size")
|
||||
if isinstance(size, int) and size > 0:
|
||||
group["archive_size"] = size
|
||||
if needed:
|
||||
group["needed"] = True
|
||||
group["systems"].extend(s for s in systems if s not in group["systems"])
|
||||
rel = full[len(prefix):].lstrip("/") if prefix else full
|
||||
hashes = compute_hashes(src, frozenset({"sha1"}))
|
||||
group["files"][rel] = {"sha1": hashes["sha1"], "size": os.path.getsize(src)}
|
||||
return [grouped[key] for key in sorted(grouped)]
|
||||
trees = []
|
||||
for key in sorted(grouped):
|
||||
group = grouped[key]
|
||||
if not group.pop("needed", False):
|
||||
group["optional"] = True
|
||||
trees.append(group)
|
||||
return trees
|
||||
|
||||
|
||||
def _manifest_core_index(
|
||||
|
||||
@@ -443,6 +443,9 @@ def format_size(size: int) -> str:
|
||||
|
||||
|
||||
SITE_URL = "https://abdess.github.io/retrobios/"
|
||||
# The installer demo (scripts/make_demo.py): the recording and what it shows.
|
||||
DEMO_DIR = Path(__file__).resolve().parent.parent / "docs_assets" / "demo"
|
||||
DEMO_GIF = "docs_assets/demo/install.gif"
|
||||
REPO_PATH = "../.."
|
||||
REPO = "Abdess/retrobios"
|
||||
# GitHub's "Add file > Upload files" page for bios/: a browser upload by
|
||||
@@ -473,6 +476,19 @@ def clone_line(db: dict) -> str:
|
||||
)
|
||||
|
||||
|
||||
def demo_facts() -> dict:
|
||||
"""What the installer demo shows, as make_demo.py measured it."""
|
||||
return json.loads((DEMO_DIR / "demo.json").read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
def demo_description(facts: dict | None = None) -> str:
|
||||
"""The demo in words, for a reader who cannot see it."""
|
||||
facts = facts or demo_facts()
|
||||
return (f"Recording of the one-line command in a terminal. The installer finds an "
|
||||
f"{facts['setup']} SD card with {facts['games']} games, plans {facts['files']} "
|
||||
f"BIOS files ({facts['size']}) for them, installs them and shows the summary.")
|
||||
|
||||
|
||||
def _existing_contributor_block(readme_path: str = "README.md") -> list[str]:
|
||||
"""The contributors already published, read back from the file.
|
||||
|
||||
@@ -619,6 +635,8 @@ def generate_readme(db: dict, platforms_dir: str, db_path: str = "database.json"
|
||||
install_command("powershell", "--check"),
|
||||
"```",
|
||||
"",
|
||||
f"",
|
||||
"",
|
||||
"The script opens a full-screen installer, driven with the arrow keys and Enter, or with a"
|
||||
" controller on a handheld. It finds your setup and its BIOS folder, downloads only the missing"
|
||||
" files and checks each one. It can also copy the BIOS files from your old SD card.",
|
||||
|
||||
@@ -82,6 +82,8 @@ from generate_readme import (
|
||||
NO_PACK,
|
||||
asset_links,
|
||||
contributing_text,
|
||||
demo_description,
|
||||
demo_facts,
|
||||
download_links,
|
||||
extract_notes,
|
||||
extract_targets,
|
||||
@@ -92,6 +94,7 @@ import sitemarkup as markup
|
||||
import siteentries
|
||||
import siteinputs
|
||||
import retired_files
|
||||
import siteagents
|
||||
import sitestarlight
|
||||
from siteexports import generate_exports_page, load_export_reports
|
||||
from siteguides import (
|
||||
@@ -515,6 +518,7 @@ def generate_home(
|
||||
"**Run one command.** Some setups have a ZIP.",
|
||||
"**Start a game.**",
|
||||
]),
|
||||
*install_demo(),
|
||||
"## Pick your device",
|
||||
"",
|
||||
*setup_picker(registry, display),
|
||||
@@ -4154,6 +4158,20 @@ def first_screen_words() -> list[str]:
|
||||
f"and **{installer.TUI_FOLDER_TITLE}**), then offers **{installer.TUI_INSTALL_ROW}**."]
|
||||
|
||||
|
||||
# The demo files the site serves (docs_assets/demo/, scripts/make_demo.py):
|
||||
# the GIF is the README's, the tape and demo.json are inputs.
|
||||
DEMO_ASSETS = ("install.webm", "install.mp4", "install.png")
|
||||
|
||||
|
||||
def install_demo() -> list[str]:
|
||||
"""The installer demo: a video that loads once it is on screen, its
|
||||
description for screen readers."""
|
||||
facts = demo_facts()
|
||||
text = html.escape(demo_description(facts), quote=True)
|
||||
return [f'<InstallDemo description="{text}" width="{facts["width"]}" '
|
||||
f'height="{facts["height"]}" />', ""]
|
||||
|
||||
|
||||
def check_pass_line() -> str:
|
||||
"""The pass line of "How to check": the words `--check` prints only when
|
||||
no file is missing or wrong (install.py EVERYTHING_IN_PLACE), read from
|
||||
@@ -11956,6 +11974,7 @@ def generate_which_pack() -> str:
|
||||
"",
|
||||
*first_screen_words(),
|
||||
"",
|
||||
*install_demo(),
|
||||
*trust_box(""),
|
||||
"**Check your folder later.** Add `--check`. It changes nothing.",
|
||||
"",
|
||||
@@ -12315,6 +12334,10 @@ def _generate(args: argparse.Namespace) -> None:
|
||||
source = Path("docs_assets") / folder
|
||||
if source.is_dir():
|
||||
shutil.copytree(source, public / "assets" / dest, dirs_exist_ok=True)
|
||||
demo_dest = public / "assets" / "demo"
|
||||
demo_dest.mkdir(parents=True, exist_ok=True)
|
||||
for name in DEMO_ASSETS:
|
||||
shutil.copy2(Path("docs_assets") / "demo" / name, demo_dest / name)
|
||||
assets_src = Path(".github") / "assets"
|
||||
for name, dest_name in [("logo.png", "logo.png"), ("favicon.png", "favicon.png")]:
|
||||
src = assets_src / name
|
||||
@@ -12368,6 +12391,9 @@ def _generate(args: argparse.Namespace) -> None:
|
||||
stats = compute_stats(db, coverages, profiles)
|
||||
stats["composition"] = compute_composition(db)
|
||||
write_if_changed(str(public / "stats.json"), generate_stats(stats))
|
||||
# llms.txt and the ARD manifest an agent reads first, from the registry.
|
||||
siteagents.write(public, sorted(((name, cov["platform"]) for name, cov in coverages.items()),
|
||||
key=lambda row: row[1].casefold()), write_if_changed)
|
||||
|
||||
# Computed once: the gap analysis page and the published gaps export must
|
||||
# report the same files.
|
||||
|
||||
@@ -0,0 +1,295 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Record the installer demo shown in the README and on the site, once.
|
||||
|
||||
The recording is the full-screen installer run from the one-line command on
|
||||
an ArkOS SD card that holds six games: it finds the card, plans only the BIOS
|
||||
files those games need, installs them and shows the summary. Everything it
|
||||
reads is local and the same on every machine:
|
||||
|
||||
- The card is built under tmp/demo/ (bios/, the folders ArkOS writes on its
|
||||
games partition, one game per console) and mounted at /media/EASYROMS in a
|
||||
mount namespace of this user (unshare), on a tmpfs of a card's size. /media
|
||||
and /mnt are emptied there, so no drive of this machine is shown.
|
||||
- The repository is served on 127.0.0.1 and named with RETROBIOS_BASE_URL:
|
||||
the file lists, install/games/ and the BIOS files are this checkout's.
|
||||
- The one-line command runs this checkout's install.sh and install.py. The
|
||||
shell of the recording answers `curl -fsSL <site>/i` with a line that
|
||||
starts the local install.sh, which skips the download of the installer and
|
||||
its SHA-256 check and runs the rest of the bootstrap as the site's copy does.
|
||||
- HOME is an empty folder and the prompt is "$ ".
|
||||
|
||||
docs_assets/demo/install.tape drives VHS (github.com/charmbracelet/vhs, with
|
||||
ttyd, ffmpeg and a Chromium on PATH). This script encodes what it records:
|
||||
|
||||
docs_assets/demo/install.gif the README
|
||||
docs_assets/demo/install.webm the site, with install.mp4 as fallback
|
||||
docs_assets/demo/install.png the first frame shown, the video's poster
|
||||
docs_assets/demo/demo.json what the recording shows, for the alt text
|
||||
|
||||
The site build copies the video files and never runs this script. Run it
|
||||
again when a screen of the installer or the file list of its games changes:
|
||||
|
||||
python scripts/make_demo.py
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import functools
|
||||
import hashlib
|
||||
import http.server
|
||||
import importlib.util
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import threading
|
||||
from collections.abc import Iterator
|
||||
from contextlib import contextmanager
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
OUT = ROOT / "docs_assets" / "demo"
|
||||
TAPE = OUT / "install.tape"
|
||||
WORK = ROOT / "tmp" / "demo"
|
||||
# What the tape writes, read back here (paths relative to ROOT, the tape's
|
||||
# working directory).
|
||||
RECORDED = WORK / "recorded.mp4"
|
||||
POSTER_SHOT = WORK / "poster.png"
|
||||
MOUNT = "/media/EASYROMS"
|
||||
CARD_SIZE = "29g"
|
||||
SETUP = "ArkOS"
|
||||
|
||||
# The card: the folders ArkOS's default tree writes on EASYROMS (install.py
|
||||
# _GAMES_PART_RULES reads launchimages/), and one game per console folder,
|
||||
# named as the folder's extensions in install/games/setups/arkos.json allow.
|
||||
CARD_FOLDERS = ("bios", "bgmusic", "launchimages", "themes/es-theme-nes-box")
|
||||
GAMES = {
|
||||
"psx": "Sky Courier (USA).iso",
|
||||
"segacd": "Night Shift (USA).iso",
|
||||
"megadrive": "Old Harbour (World).md",
|
||||
"mastersystem": "Tide Runner (Europe).sms",
|
||||
"gamegear": "Pocket Quest (World).gg",
|
||||
"pcengine": "Star Lancer (Japan).pce",
|
||||
}
|
||||
GAME_BYTES = 256 * 1024
|
||||
# A PlayStation disc carries Sony's licence text in sector 4, the text the
|
||||
# cores read the region from (install/games/systems/sony-playstation.json).
|
||||
PSX_LICENCE = b" Licensed by Sony Computer Entertainment Amer ica "
|
||||
|
||||
# Size targets of the outputs, in bytes: the README and two site pages.
|
||||
LIMITS = {"install.gif": 1_500_000, "install.webm": 1_000_000,
|
||||
"install.mp4": 1_000_000, "install.png": 150_000}
|
||||
GIF_FPS = 10
|
||||
VIDEO_FPS = 25
|
||||
|
||||
|
||||
def game_bytes(name: str) -> bytes:
|
||||
"""Bytes of a game no catalog names, the same on every run."""
|
||||
seed = hashlib.sha256(name.encode("utf-8")).digest()
|
||||
blocks, counter = [], 0
|
||||
while len(blocks) * 32 < GAME_BYTES:
|
||||
blocks.append(hashlib.sha256(seed + counter.to_bytes(4, "big")).digest())
|
||||
counter += 1
|
||||
return b"".join(blocks)[:GAME_BYTES]
|
||||
|
||||
|
||||
def build_card(card: Path) -> None:
|
||||
if card.exists():
|
||||
shutil.rmtree(card)
|
||||
for folder in CARD_FOLDERS:
|
||||
(card / folder).mkdir(parents=True)
|
||||
(card / "launchimages" / "loading.jpg").write_bytes(b"\xff\xd8\xff\xe0" + bytes(60) + b"\xff\xd9")
|
||||
(card / "themes" / "es-theme-nes-box" / "theme.xml").write_text(
|
||||
"<theme>\n</theme>\n", encoding="utf-8")
|
||||
for folder, name in GAMES.items():
|
||||
data = bytearray(game_bytes(name))
|
||||
if folder == "psx":
|
||||
data[4 * 2048:4 * 2048 + len(PSX_LICENCE)] = PSX_LICENCE
|
||||
(card / folder).mkdir()
|
||||
(card / folder / name).write_bytes(bytes(data))
|
||||
|
||||
|
||||
class QuietHandler(http.server.SimpleHTTPRequestHandler):
|
||||
def log_message(self, format: str, *args: object) -> None: # noqa: A002
|
||||
pass
|
||||
|
||||
|
||||
@contextmanager
|
||||
def served_repository() -> Iterator[str]:
|
||||
"""The repository on a loopback port, the base URL install.py accepts
|
||||
without HTTPS."""
|
||||
handler = functools.partial(QuietHandler, directory=str(ROOT))
|
||||
server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), handler)
|
||||
thread = threading.Thread(target=server.serve_forever, daemon=True)
|
||||
thread.start()
|
||||
try:
|
||||
yield f"http://127.0.0.1:{server.server_address[1]}"
|
||||
finally:
|
||||
server.shutdown()
|
||||
server.server_close()
|
||||
|
||||
|
||||
def write_session(work: Path, names: list[str]) -> Path:
|
||||
"""The program the recording's shell becomes: the card mounted in a
|
||||
namespace of its own, then a clean interactive bash, or the command
|
||||
given as arguments, with only the variables names lists."""
|
||||
rc = work / "bashrc"
|
||||
rc.write_text(
|
||||
"PS1='$ '\n"
|
||||
"unset HISTFILE PROMPT_COMMAND\n"
|
||||
"curl() {\n"
|
||||
' if [ "$*" = "-fsSL https://abdess.github.io/retrobios/i" ]; then\n'
|
||||
' printf \'exec %s "$@"\\n\' "$RETROBIOS_DEMO_BOOTSTRAP"\n'
|
||||
" else\n"
|
||||
' command curl "$@"\n'
|
||||
" fi\n"
|
||||
"}\n"
|
||||
"clear\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
session = work / "session.sh"
|
||||
session.write_text(
|
||||
"#!/bin/sh\n"
|
||||
"# Written by scripts/make_demo.py.\n"
|
||||
"set -eu\n"
|
||||
"inner='set -eu\n"
|
||||
"mount -t tmpfs -o mode=0755 demo /media\n"
|
||||
"mount -t tmpfs -o mode=0755 demo /mnt\n"
|
||||
f"mkdir {MOUNT}\n"
|
||||
f"mount -t tmpfs -o size={CARD_SIZE},mode=0755 EASYROMS {MOUNT}\n"
|
||||
f'cp -a "$RETROBIOS_DEMO_CARD/." {MOUNT}/\n'
|
||||
'cd "$HOME"\n'
|
||||
'exec unshare --user --map-user="$RETROBIOS_DEMO_UID" '
|
||||
'--map-group="$RETROBIOS_DEMO_GID" env -i '
|
||||
+ " ".join(f'{name}="${name}"' for name in names) + ' "$@"\'\n'
|
||||
'if [ "$#" -eq 0 ]; then\n'
|
||||
f' set -- bash --noprofile --rcfile "{rc}" -i\n'
|
||||
"fi\n"
|
||||
'exec unshare --user --mount --map-root-user /bin/sh -c "$inner" sh "$@"\n',
|
||||
encoding="utf-8",
|
||||
)
|
||||
session.chmod(0o755)
|
||||
return session
|
||||
|
||||
|
||||
def session_env(base_url: str, work: Path, card: Path) -> dict[str, str]:
|
||||
home = work / "home"
|
||||
home.mkdir(parents=True, exist_ok=True)
|
||||
return {
|
||||
"HOME": str(home),
|
||||
"PATH": "/usr/local/bin:/usr/bin:/bin",
|
||||
"LANG": "C.UTF-8",
|
||||
"TERM": "xterm-256color",
|
||||
"TMPDIR": str(work / "scratch"),
|
||||
"RETROBIOS_OS": "linux",
|
||||
"RETROBIOS_BASE_URL": base_url,
|
||||
# What the downloaded bootstrap sets: commands given back are the
|
||||
# one-line command, not a path to a temporary copy.
|
||||
"RETROBIOS_BOOTSTRAP": "sh",
|
||||
"RETROBIOS_DEMO_BOOTSTRAP": str(ROOT / "install.sh"),
|
||||
"RETROBIOS_DEMO_CARD": str(card),
|
||||
"RETROBIOS_DEMO_UID": str(os.getuid()),
|
||||
"RETROBIOS_DEMO_GID": str(os.getgid()),
|
||||
}
|
||||
|
||||
|
||||
def format_size(size: int) -> str:
|
||||
"""The size as the installer writes it."""
|
||||
spec = importlib.util.spec_from_file_location("retrobios_install", ROOT / "install.py")
|
||||
if spec is None or spec.loader is None:
|
||||
raise RuntimeError("install.py cannot be loaded")
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
return str(module.format_size(size))
|
||||
|
||||
|
||||
def measure(session: Path, env: dict[str, str]) -> dict:
|
||||
"""What the recording shows, read from the same run without the screen:
|
||||
the games read on the card and the files planned for them."""
|
||||
command = [str(session), sys.executable, str(ROOT / "install.py"), "--platform", "retroarch",
|
||||
"--dest", f"{MOUNT}/bios", "--for-games", "--dry-run", "--events"]
|
||||
result = subprocess.run(command, env=env, capture_output=True, text=True, check=False)
|
||||
if result.returncode != 0:
|
||||
raise RuntimeError(f"the dry run failed ({result.returncode}):\n{result.stderr}")
|
||||
events = [json.loads(line) for line in result.stdout.splitlines() if line.startswith("{")]
|
||||
games = next(e for e in events if e["event"] == "games")
|
||||
check = next(e for e in events if e["event"] == "check")
|
||||
size = {key.lower(): int(value) for key, value in
|
||||
re.findall(r"^Set (Width|Height) (\d+)$", TAPE.read_text(encoding="utf-8"), re.M)}
|
||||
return {
|
||||
"width": size["width"],
|
||||
"height": size["height"],
|
||||
"setup": SETUP,
|
||||
"games": games["games"],
|
||||
"systems": len(games["found"]),
|
||||
"files": check["missing"],
|
||||
"size": format_size(check["bytes_needed"]),
|
||||
}
|
||||
|
||||
|
||||
def ffmpeg(*args: str) -> None:
|
||||
subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-y", *args], check=True)
|
||||
|
||||
|
||||
def encode(recorded: Path, poster: Path, out: Path, scratch: Path) -> None:
|
||||
palette = scratch / "palette.png"
|
||||
ffmpeg("-i", str(recorded), "-vf", f"fps={GIF_FPS},palettegen=max_colors=48:stats_mode=full",
|
||||
str(palette))
|
||||
ffmpeg("-i", str(recorded), "-i", str(palette), "-lavfi",
|
||||
f"fps={GIF_FPS}[v];[v][1:v]paletteuse=dither=none:diff_mode=rectangle",
|
||||
"-loop", "0", str(out / "install.gif"))
|
||||
ffmpeg("-i", str(recorded), "-an", "-r", str(VIDEO_FPS), "-c:v", "libvpx-vp9",
|
||||
"-b:v", "0", "-crf", "42", "-row-mt", "1", "-deadline", "good",
|
||||
"-pix_fmt", "yuv420p", str(out / "install.webm"))
|
||||
ffmpeg("-i", str(recorded), "-an", "-r", str(VIDEO_FPS), "-c:v", "libx264",
|
||||
"-preset", "veryslow", "-crf", "30", "-tune", "animation", "-pix_fmt", "yuv420p",
|
||||
"-movflags", "+faststart", str(out / "install.mp4"))
|
||||
ffmpeg("-i", str(poster), "-pred", "mixed", "-compression_level", "100",
|
||||
str(out / "install.png"))
|
||||
|
||||
|
||||
def check_sizes(out: Path) -> list[str]:
|
||||
return [f"{name}: {(out / name).stat().st_size:,} bytes, over {limit:,}"
|
||||
for name, limit in LIMITS.items() if (out / name).stat().st_size > limit]
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(allow_abbrev=False,
|
||||
description="Record the installer demo (VHS).")
|
||||
parser.parse_args()
|
||||
missing = [tool for tool in ("vhs", "ttyd", "ffmpeg", "unshare") if shutil.which(tool) is None]
|
||||
if missing:
|
||||
sys.exit(f"Missing on PATH: {', '.join(missing)} (VHS: github.com/charmbracelet/vhs)")
|
||||
if WORK.exists():
|
||||
shutil.rmtree(WORK)
|
||||
(WORK / "scratch").mkdir(parents=True)
|
||||
try:
|
||||
card = WORK / "card"
|
||||
build_card(card)
|
||||
with served_repository() as base_url:
|
||||
env = session_env(base_url, WORK, card)
|
||||
session = write_session(WORK, sorted(env))
|
||||
facts = measure(session, env)
|
||||
vhs_env = {**os.environ, **env, "PATH": os.environ.get("PATH", ""),
|
||||
"HOME": os.environ.get("HOME", ""),
|
||||
"RETROBIOS_DEMO_SESSION": str(session)}
|
||||
subprocess.run(["vhs", str(TAPE.relative_to(ROOT))], cwd=ROOT, env=vhs_env,
|
||||
check=True)
|
||||
encode(RECORDED, POSTER_SHOT, OUT, WORK / "scratch")
|
||||
(OUT / "demo.json").write_text(json.dumps(facts, indent=2) + "\n", encoding="utf-8")
|
||||
for name in (*LIMITS, "demo.json"):
|
||||
print(f"{(OUT / name).relative_to(ROOT)} {(OUT / name).stat().st_size:,} bytes")
|
||||
over = check_sizes(OUT)
|
||||
if over:
|
||||
sys.exit("Over the size targets:\n " + "\n ".join(over))
|
||||
finally:
|
||||
shutil.rmtree(WORK, ignore_errors=True)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
from common import run_cli
|
||||
|
||||
run_cli(main)
|
||||
@@ -0,0 +1,225 @@
|
||||
"""What the site tells an AI agent about itself.
|
||||
|
||||
- ``llms.txt`` (https://llmstxt.org): the pages and data an agent should
|
||||
read first, in Markdown, at the site's root.
|
||||
- ``skills/setup-bios/SKILL.md``: an Agent Skill that sets up a device's
|
||||
BIOS files with the fewest downloads.
|
||||
- ``ard.json``: an Agentic Resource Discovery manifest
|
||||
(https://github.com/ards-project/ard-spec) listing that skill and the
|
||||
JSON API, linked from every page's head with ``rel="ard"``.
|
||||
|
||||
Both are written from the registry at each build, so a new platform or a
|
||||
moved page cannot leave them stale. The WebMCP tools a page registers live
|
||||
in website/src/scripts/agent-tools.ts.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Callable
|
||||
from pathlib import Path
|
||||
|
||||
SITE = "https://abdess.github.io/retrobios/"
|
||||
PUBLISHER = "abdess.github.io"
|
||||
SH = "curl -fsSL https://abdess.github.io/retrobios/i | sh -s --"
|
||||
PS = "& ([scriptblock]::Create((irm https://abdess.github.io/retrobios/i.ps1)))"
|
||||
# What a folder put into a command may not hold, as agent-tools.ts refuses
|
||||
# it: PowerShell also ends a single-quoted string on the typographic quotes.
|
||||
REFUSED = "any quote, straight or typographic (' \" ‘ ’ ‚ ‛ “ ” „), a backtick or a control character"
|
||||
QUOTING = (f"A folder goes in single quotes, attached to its option. One that holds {REFUSED}, "
|
||||
"or starts with `-`, is a question for the user, never a value to escape into the "
|
||||
"command. On a page of the site, the `device_setup_command` WebMCP tool writes the "
|
||||
"command and refuses such a folder.")
|
||||
|
||||
START_PAGES = (
|
||||
("Which pack do I need", "which-pack/", "pick a device or setup, get the folder its BIOS files go in, "
|
||||
"one command that installs and checks them, or a ZIP pack"),
|
||||
("First install", "wiki/first-install/", "the steps from nothing to a working BIOS folder"),
|
||||
("What are BIOS files", "wiki/what-are-bios-files/", "why emulators need them and where they come from"),
|
||||
("Troubleshooting", "wiki/troubleshooting/", "a file the emulator does not find or refuses"),
|
||||
("Common questions", "wiki/faq/", "short answers"),
|
||||
)
|
||||
|
||||
DATA = (
|
||||
("API index", "api/v1/index.json", "every dataset of the JSON API, versioned"),
|
||||
("Catalog", "api/v1/catalog.json", "each dataset, manifest, export and download with its size, SHA-256 and schema"),
|
||||
("Emulators", "api/v1/emulators.json", "every emulator profile: the files it reads, required or not, "
|
||||
"their hashes and the source line that reads each. One document "
|
||||
"per emulator at api/v1/emulators/<id>.json"),
|
||||
("Core names", "api/v1/cores.json", "each core name and alias, with the profile it designates"),
|
||||
("Systems", "api/v1/systems.json", "each system id, its name and the section holding its files"),
|
||||
("Platforms", "api/v1/platforms.json", "each setup (RetroArch, Batocera...), its BIOS folder and files"),
|
||||
("Hash lookup", "api/v1/lookup/00.json", "what a hash (MD5, SHA-1, SHA-256, CRC32) designates, sharded "
|
||||
"by its first two hex characters: api/v1/lookup/<xx>.json"),
|
||||
)
|
||||
|
||||
MORE = (
|
||||
("Emulators", "emulators/", "one page per emulator"),
|
||||
("Systems", "systems/", "one page per console maker, every file with its hashes"),
|
||||
("Installer", "wiki/installer/", "every option of install.py"),
|
||||
("What we count", "wiki/privacy/", "the site's cookie-free counting"),
|
||||
("Is it legal?", "wiki/legal/", "the project's position"),
|
||||
("Contributing", "contributing/", "add a missing file or an emulator profile"),
|
||||
)
|
||||
|
||||
|
||||
def llms_txt(platforms: list[tuple[str, str]]) -> str:
|
||||
"""The site's llms.txt. ``platforms`` lists (id, display name) of every
|
||||
registered setup, each with its page."""
|
||||
lines = [
|
||||
"# RetroBIOS",
|
||||
"",
|
||||
"> BIOS and firmware files for emulators, each checked against the emulator's source "
|
||||
"code: which files an emulator reads, whether it starts without them, where each one "
|
||||
"goes on every setup, their hashes, and an installer that puts them in place.",
|
||||
"",
|
||||
"Every claim about a file cites the line of emulator source code that reads it. The "
|
||||
"files themselves are served by the GitHub repository "
|
||||
"(https://github.com/Abdess/retrobios) and its releases.",
|
||||
"",
|
||||
"## Setting up a device for its user",
|
||||
"",
|
||||
"Most people want to play now, with the fewest files. The installer does that in one "
|
||||
"command: it finds the setup and its BIOS folder, reads the games on the card, and with "
|
||||
"`--for-games --required-only` installs only the files those games cannot start "
|
||||
"without. Without these two options it installs every file of the setup's list "
|
||||
"(gigabytes), even with `--yes`.",
|
||||
"",
|
||||
f"1. Preview, nothing written: `{SH} --for-games --required-only --dry-run`",
|
||||
f"2. Install, no questions: `{SH} --for-games --required-only --yes`",
|
||||
f"3. On Windows (PowerShell): `{PS} --for-games --required-only --yes`",
|
||||
"",
|
||||
"- Run it on the device itself (its terminal or SSH), or on a computer with the device's "
|
||||
"card plugged in. The installer recognises the handheld systems on the card, among them "
|
||||
"ArkOS, dArkOS, ArchR and UnofficialOS (R36S and its clones), muOS, KNULLI, ROCKNIX, "
|
||||
"AmberELEC, EmuELEC, Onion, spruceOS and MinUI. "
|
||||
"The [Linux handhelds page](" + SITE + "platforms/linux-handhelds/) maps each device "
|
||||
"to its system and folder.",
|
||||
"- From a computer, if the card is not found, name its BIOS folder: `--dest='<card>/bios'` "
|
||||
"(ArkOS and dArkOS: the `bios` folder of the EASYROMS part).",
|
||||
"- A games folder somewhere else: `--for-games='<folder>'`, one subfolder per system.",
|
||||
f"- {QUOTING}",
|
||||
"- Later, to see what is missing or wrong: `--check`. Machine-readable progress: "
|
||||
"`--events` (JSON lines, one per event, documented on the installer page).",
|
||||
"- A game the installer cannot identify gets every BIOS of its system, and the run names it.",
|
||||
f"- The same steps as an Agent Skill: [SKILL.md]({SITE}{SKILL_PATH}).",
|
||||
"",
|
||||
"## Start",
|
||||
"",
|
||||
*(f"- [{title}]({SITE}{path}): {what}" for title, path, what in START_PAGES),
|
||||
"",
|
||||
"## Setups",
|
||||
"",
|
||||
*(f"- [{name}]({SITE}platforms/{pid}/): its BIOS folder and files" for pid, name in platforms),
|
||||
"",
|
||||
"## Data",
|
||||
"",
|
||||
*(f"- [{title}]({SITE}{path}): {what}" for title, path, what in DATA),
|
||||
"",
|
||||
"## Optional",
|
||||
"",
|
||||
*(f"- [{title}]({SITE}{path}): {what}" for title, path, what in MORE),
|
||||
]
|
||||
return "\n".join(lines) + "\n"
|
||||
|
||||
|
||||
SKILL_PATH = "skills/setup-bios/SKILL.md"
|
||||
# The Agent Skills media type ARD names: Markdown with this profile.
|
||||
SKILL_TYPE = 'text/markdown; profile="urn:air:agent-skills"'
|
||||
|
||||
|
||||
def skill_md() -> str:
|
||||
"""An Agent Skill (SKILL.md: YAML front matter, then instructions) that
|
||||
sets up a device's BIOS files with the fewest downloads."""
|
||||
return "\n".join([
|
||||
"---",
|
||||
"name: setup-bios",
|
||||
"description: Install the BIOS and firmware files a retrogaming device or computer needs "
|
||||
"(RetroArch, Batocera, EmuDeck, ArkOS, dArkOS, muOS, KNULLI, ROCKNIX and others), only "
|
||||
"what the games on its card need to start. Use when a user asks to set up emulators, "
|
||||
"a handheld (R36S, Miyoo, Anbernic), BIOS files or firmware.",
|
||||
"---",
|
||||
"",
|
||||
"# Set up BIOS files with RetroBIOS",
|
||||
"",
|
||||
"Most users want to play now, with the fewest files. Install only what the games on the "
|
||||
"card need, unless the user asks for everything.",
|
||||
"",
|
||||
"## Steps",
|
||||
"",
|
||||
"1. Ask where the games are: on the device itself (you have its terminal or SSH), or on "
|
||||
"its card plugged into this computer.",
|
||||
f"2. Preview, nothing is written: `{SH} --for-games --required-only --dry-run` "
|
||||
f"(Windows PowerShell: `{PS} --for-games --required-only --dry-run`).",
|
||||
"3. Show the user the plan it prints: the setup found, the BIOS folder, the files and "
|
||||
"their size. Ask before going on if the setup or the folder is not the one expected.",
|
||||
"4. Install with the same command, `--yes` in place of `--dry-run`.",
|
||||
"5. Report the summary line. A game the installer could not identify got every BIOS of "
|
||||
"its system: say which.",
|
||||
"",
|
||||
"## When the setup or the card is not found",
|
||||
"",
|
||||
"- From a computer, name the card's BIOS folder: `--dest='<card>/bios'`. ArkOS and dArkOS "
|
||||
"keep it on the EASYROMS part.",
|
||||
"- Games outside the card: `--for-games='<folder>'`, one subfolder per system.",
|
||||
"- A setup not detected: `--platform=<name>`, a name exactly as `--list-platforms` prints "
|
||||
"it (letters, digits, `-` and `_`).",
|
||||
f"- {QUOTING}",
|
||||
"",
|
||||
"## Later",
|
||||
"",
|
||||
"- `--check` says what is missing or wrong, without downloading.",
|
||||
"- `--events` writes the run as JSON lines, for reading by a program.",
|
||||
"",
|
||||
f"Every option: {SITE}wiki/installer/. Devices and their folders: "
|
||||
f"{SITE}platforms/linux-handhelds/. The site's guide for agents: {SITE}llms.txt.",
|
||||
"",
|
||||
])
|
||||
|
||||
|
||||
def ard_manifest() -> dict:
|
||||
"""The ARD manifest: the setup skill and the JSON API, each with the
|
||||
questions it answers. llms.txt is found at the site root, as its
|
||||
convention says."""
|
||||
return {
|
||||
"entries": [
|
||||
{
|
||||
"identifier": f"urn:air:{PUBLISHER}:retrobios:setup-bios",
|
||||
"displayName": "Set up BIOS files with RetroBIOS",
|
||||
"type": SKILL_TYPE,
|
||||
"url": f"{SITE}{SKILL_PATH}",
|
||||
"description": "An agent skill that installs the BIOS files a device needs, only "
|
||||
"what the games on its card need to start.",
|
||||
"representativeQueries": [
|
||||
"install the minimum BIOS files for the games on my R36S running dArkOS",
|
||||
"set up BIOS files for RetroArch on my Steam Deck",
|
||||
"my emulator says BIOS missing, fix it",
|
||||
],
|
||||
"capabilities": ["SetupBios"],
|
||||
"tags": ["bios", "firmware", "emulation", "retrogaming"],
|
||||
},
|
||||
{
|
||||
"identifier": f"urn:air:{PUBLISHER}:retrobios:api",
|
||||
"displayName": "RetroBIOS JSON API",
|
||||
"type": "application/json",
|
||||
"url": f"{SITE}api/v1/index.json",
|
||||
"description": "Versioned JSON datasets: emulator profiles, platforms, systems, core "
|
||||
"names and a hash lookup.",
|
||||
"representativeQueries": [
|
||||
"what file has the MD5 490f666e1afb15b7362b406ed1cea246",
|
||||
"which files does the beetle_psx core read",
|
||||
"where do PlayStation BIOS files go on Batocera",
|
||||
],
|
||||
"capabilities": ["HashLookup", "EmulatorFiles", "PlatformFiles"],
|
||||
"tags": ["api", "json", "bios"],
|
||||
},
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
def write(public: Path, platforms: list[tuple[str, str]],
|
||||
write_if_changed: Callable[[str, str], object]) -> None:
|
||||
write_if_changed(str(public / "llms.txt"), llms_txt(platforms))
|
||||
(public / SKILL_PATH).parent.mkdir(parents=True, exist_ok=True)
|
||||
write_if_changed(str(public / SKILL_PATH), skill_md())
|
||||
write_if_changed(str(public / "ard.json"), json.dumps(ard_manifest(), indent=1) + "\n")
|
||||
@@ -29,6 +29,7 @@ COMPONENTS = {
|
||||
"TabItem": "@astrojs/starlight/components",
|
||||
"FilePicker": "components/FilePicker.astro",
|
||||
"MeasurementsExplorer": "components/MeasurementsExplorer.astro",
|
||||
"InstallDemo": "components/InstallDemo.astro",
|
||||
}
|
||||
|
||||
# Pages of file cards: level 3 headings by the hundred, so the table of
|
||||
@@ -330,7 +331,7 @@ OG_DIR = Path(__file__).resolve().parent.parent / "docs_assets" / "og"
|
||||
|
||||
# An emulator page's card is that of the maker of the first system it runs,
|
||||
# by page path: "emulators/mgba.mdx" -> "nintendo". One card per emulator
|
||||
# would be some 900 images in the repository. The maker's names the
|
||||
# would be some 900 images in the repository, and the maker's names the
|
||||
# consoles. Filled by generate_site.record_emulator_page.
|
||||
EMULATOR_CARDS: dict[str, str] = {}
|
||||
|
||||
|
||||
Reference in new issue
Block a user