From 8361575be86b2239e16c457b34966f49d8d86540 Mon Sep 17 00:00:00 2001 From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com> Date: Fri, 23 Oct 2026 02:42:19 +0200 Subject: [PATCH] docs: start pages say what the installer does The safety list names the save folder, every install command shows its Windows form, first install reads the last line of a run, the FAQ answers zip or unzip and the arcade version rule, and each page keeps one name. --- tests/test_doc_pages.py | 9 +++- tests/test_doc_surfaces.py | 5 +- tests/test_site_copy.py | 1 - tests/test_site_funnel.py | 13 +++-- wiki/faq.md | 96 ++++++++++++++++++------------------- wiki/first-install.md | 73 +++++++++++++++------------- wiki/glossary.md | 16 +++++-- wiki/legal.md | 13 +++-- wiki/technical-faq.md | 10 ++-- wiki/troubleshooting.md | 34 ++++++------- wiki/what-are-bios-files.md | 11 ++--- 11 files changed, 150 insertions(+), 131 deletions(-) diff --git a/tests/test_doc_pages.py b/tests/test_doc_pages.py index cd208c02..bddc28bc 100644 --- a/tests/test_doc_pages.py +++ b/tests/test_doc_pages.py @@ -698,7 +698,14 @@ class FirstInstallWalkthrough(unittest.TestCase): step3 = _section(self.run, "The file index and the download") step4 = _section(self.run, "The end of the run") step5 = _section(self.run, "A later check") - self.assertIn(re.search(r"Done\. \d+ files installed", step4).group(0), self.text) + # First install names the three endings a run prints, and no count: + # a figure from one setup read as the size of every install. + source = (ROOT / "install.py").read_text(encoding="utf-8") + for ending in ("Done.", "Finished with errors.", "Nothing was installed."): + with self.subTest(ending=ending): + self.assertIn(f"`{ending}`", _section(self.text, "5. Read the last line")) + self.assertIn(f'"\\n{ending} ', source) + self.assertNotRegex(self.text, r"Done\. \d+ files") count, size = re.search(r"\n (\d+) files \(([\d.]+ [KMG]B)\)", step3).groups() self.assertIn(f"0/{count} present", step3) self.assertIn(f"Downloading {count} files ({size})", step3) diff --git a/tests/test_doc_surfaces.py b/tests/test_doc_surfaces.py index a565740c..02361b1d 100644 --- a/tests/test_doc_surfaces.py +++ b/tests/test_doc_surfaces.py @@ -186,7 +186,7 @@ class SlicesLeaveWithTheirRelease(unittest.TestCase): """Parts named `.zip.001` were cut by v2026.09.04, deleted since. A page explaining a layout no release serves buries the one the user has.""" - PAGES = ("README.md", "wiki/getting-started.md", "wiki/troubleshooting.md") + PAGES = ("README.md", "wiki/troubleshooting.md") def setUp(self): assets = [a for p in RECORD.get("packs", {}).values() for a in p["assets"]] @@ -236,7 +236,6 @@ class DestIsTheBiosFolder(unittest.TestCase): PAGES = ( "README.md", - "wiki/getting-started.md", "wiki/installer.md", "wiki/faq.md", "wiki/first-install.md", @@ -269,7 +268,7 @@ class ShownOutputIsPrintedOutput(unittest.TestCase): self.assertIn(literal, source) def test_samples_match_a_shape(self): - section = _section(_read("wiki/verification-modes.md"), "### Reading the output") + section = _section(_read("wiki/reading-reports.md"), "### Reading the output") blocks = re.findall(r"```\n(.*?)```", section, re.DOTALL) self.assertTrue(blocks) for block in blocks: diff --git a/tests/test_site_copy.py b/tests/test_site_copy.py index eece3067..de54fd02 100644 --- a/tests/test_site_copy.py +++ b/tests/test_site_copy.py @@ -35,7 +35,6 @@ START_PAGES = { "wiki/troubleshooting.md": 300, "wiki/faq.md": 450, "wiki/glossary.md": 200, - "wiki/getting-started.md": 120, } # Level 1: the guide part of each setup page, above its Reference heading. SETUP_CEILING = 220 diff --git a/tests/test_site_funnel.py b/tests/test_site_funnel.py index bf2234a1..284de356 100644 --- a/tests/test_site_funnel.py +++ b/tests/test_site_funnel.py @@ -96,8 +96,7 @@ class EveryPlatformOnThePicker(unittest.TestCase): def test_every_wiki_page_is_in_the_navigation(self): """A wiki page is published as soon as it exists, but a page left out of the nav is reachable only by a link and MkDocs says so at info - level. getting-started.md is kept out on purpose: it only links the - pages that took its content, for the old links that point to it.""" + level.""" def targets(entries) -> list[str]: found = [] for entry in entries: @@ -109,7 +108,7 @@ class EveryPlatformOnThePicker(unittest.TestCase): return found nav = " ".join(targets(generate_site.generate_nav({}, {}, {}, {}))) - kept_out = {"getting-started.md"} + kept_out: set[str] = set() wiki = Path(__file__).resolve().parents[1] / "wiki" missing = sorted( p.name for p in wiki.glob("*.md") @@ -239,7 +238,13 @@ class GuidePagesEndOnANextStep(unittest.TestCase): path = REPO_ROOT / page with self.subTest(page=page): text = path.read_text(encoding="utf-8") - self.assertTrue(":::tip[Next]" in text or "## What comes next" in text) + if page.startswith("wiki/"): + # A plain list: an aside drew a coloured stripe and an icon. + self.assertIn("\n## Next steps\n", text) + self.assertNotIn(":::tip[Next]", text) + else: + self.assertTrue(":::tip[Next]" in text or "## Next steps" in text + or "## What comes next" in text) def test_the_platform_page_opens_on_its_guide(self): """The folder came after four counters and a metadata table, and was diff --git a/wiki/faq.md b/wiki/faq.md index 092a1cc6..0499bf38 100644 --- a/wiki/faq.md +++ b/wiki/faq.md @@ -1,10 +1,9 @@ --- level: start order: 50 -nav_title: Common questions --- -# FAQ +# Common questions ## Do I need BIOS files? @@ -14,36 +13,55 @@ many home computers. For NES or Super Nintendo cartridges, usually not. ## How do I know which BIOS I need? -Run the installer with `--dry-run`. It lists what it would install and changes +Run the command with `--dry-run`. It lists what it would install and changes nothing. + ```sh curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --dry-run ``` -Your setup's page also lists every file, console by console. +Your setup's page lists every file. + +## Do I need every file of a console? + +No. A console often has one BIOS per region. The ZIP holds them all. To keep +only yours, add your region, like `--region us`. + +## Zip or unzip? { #zip-or-unzip } + +Unzip the ZIP you downloaded once, into the folder your setup's page names. +Leave the ZIP files inside it as they are, like `neogeo.zip`. Arcade emulators +read them zipped. + +## Does a BIOS work on every setup? + +The same file usually works everywhere. Some setups also check the version and +report one they do not expect. Arcade files like `neogeo.zip` change with the +emulator. The command installs the version your setup expects. + +## Can I play without the BIOS? + +Sometimes. Some emulators carry a stand-in for it. Some games then glitch or +do not start. ## Is the command safe? { #is-piping-the-installer-into-a-shell-safe } -- It checks the installer's fingerprint before running it. If the download - does not match its expected fingerprint, it stops. -- It checks every file before saving it. -- It writes only in your BIOS folder. - -To read the script before you run it: - -```sh -curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh -o install.sh -less install.sh && sh install.sh -``` +- It checks the installer's fingerprint first. If it does not match its expected + fingerprint, it stops. +- It checks each file before saving it. +- It writes in your BIOS folder. For some emulators it also adds files to your + save folder. +- It never changes or deletes a game or a save. +- It keeps any file it replaces in a `retrobios-backup` folder, next to your + BIOS folder. `--restore` puts it back + ([details](installer.md#files-you-already-had)). +Read the script first: [install.sh](https://github.com/Abdess/retrobios/blob/main/install.sh), +[install.ps1](https://github.com/Abdess/retrobios/blob/main/install.ps1) and +[install.py](https://github.com/Abdess/retrobios/blob/main/install.py). Details: [How the installer checks itself](installer.md#what-the-bootstrap-does). -## Will it change my other files? - -No. It never touches games or saves, or a file it does not know. It replaces a -BIOS file with the wrong contents, and keeps yours. - ## Windows or my antivirus blocks the command Download the ZIP of your setup instead, from [Get your files](../which-pack.md). @@ -51,35 +69,22 @@ It holds the same files. ## Can I run it again? -Yes. That is how you update. It downloads only what is missing or wrong. - -## Can I undo it? - -Yes. It keeps every file it replaces in a `retrobios-backup` folder, beside -your BIOS folder. The end of the run prints the line that puts them back: the -same command with `--restore` and that folder. - -Details: [Files you already had](installer.md#files-you-already-had). +Yes, to update. It downloads only what is missing or wrong. ## Fill an SD card from a computer? -Yes. Name your setup and the BIOS folder on the card: +Yes. Name your setup and the BIOS folder on the card. On Windows, `E:` stands +for the card. + ```sh curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh \ | sh -s -- --platform retroarch --dest /path/to/sdcard/retroarch/cores/system ``` -On Windows the line is different. Details: [Passing options](installer.md#passing-options). - -## Does a BIOS work on every setup? - -Yes. Only the folder changes, and sometimes the name. - ## Why is a file missing from the ZIP? -Some files come with the emulator when you install it. The ZIP leaves those -out. +Some files come with the emulator. The ZIP leaves those out. ## Required or optional? @@ -93,19 +98,10 @@ Most of the time, a BIOS file is missing or is the wrong version. ## Is this legal? -Laws on copying console firmware differ by country. The question is not -settled, and nothing here is legal advice. Details: [The project's legal position](legal.md). +Laws differ by country, and nothing here is legal advice. Details, and how to +ask for a file to be removed: [Is it legal?](legal.md) -To ask for a file to be removed, [open an issue](https://github.com/Abdess/retrobios/issues) -and name the file. A file is removed when the owner of its rights asks. +## Next steps -## Why keep recent consoles too? - -Files disappear when stores close, like the 3DS and Wii U shops in 2023. We keep -them while they can still be found. - -:::tip[Next] - [Get your files](../which-pack.md) - [Words used on this site](glossary.md) -::: - diff --git a/wiki/first-install.md b/wiki/first-install.md index fb31ea97..a7b0bca7 100644 --- a/wiki/first-install.md +++ b/wiki/first-install.md @@ -1,10 +1,9 @@ --- level: start order: 30 -nav_title: First install, step by step --- -# First install +# First install, step by step From an empty BIOS folder to games that start. @@ -20,34 +19,43 @@ system, then press Enter. Open the Start menu. Type **PowerShell** and open it. -```powershell +```powershell title="PowerShell" irm https://raw.githubusercontent.com/Abdess/retrobios/main/install.ps1 | iex ``` - + Open **Terminal**. It is in Applications, then Utilities. -```sh +```sh title="Terminal" curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh ``` - + -On a Steam Deck, switch to Desktop Mode and open **Konsole**. +Open a terminal. -```sh +```sh title="Terminal" curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh ``` - + + +Switch to Desktop Mode and open **Konsole**. + +```sh title="Terminal" +curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh +``` + + + Install **Termux**, a terminal app. Run these three lines in it. -```sh +```sh title="Terminal" pkg install python termux-setup-storage curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh @@ -56,22 +64,20 @@ curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | - -On Batocera, Recalbox and other game systems, follow +On Batocera, Recalbox and similar setups, follow [your setup's page](../which-pack.md). - - ## 2. Check the folder it found It shows your setup and its BIOS folder: ``` - Found Batocera at /userdata/bios + Found at ``` - **Right folder?** Go on. -- **Wrong folder?** Press Ctrl+C to stop. Then see [If it stops](#if-it-stops). +- **Wrong folder?** Press Ctrl+C. Run the command again with `--dest` and your + folder. ## 3. Choose what to install @@ -86,22 +92,25 @@ It shows your setup and its BIOS folder: ## 4. Wait -It shows one line per file. You can stop with Ctrl+C at any time. Run the -command again to carry on. +You can stop with Ctrl+C at any time. Run the command again to carry on. -## 5. Look for "Done." +## 5. Read the last line -``` -Done. 14481 files installed, 0 files already up to date. -Location: /userdata/bios -``` +- **`Done.`** All files are in place. +- **`Finished with errors.`** Some files failed. Run the same command again. + It retries only those. +- **`Nothing was installed.`** The lines above it say why. See + [If it stops](#if-it-stops). -`Done.` means it worked. It may list files it could not install. +## What the command does + + ## Check it later Add `--check` to the same command. It changes nothing. + ```sh curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --check ``` @@ -110,11 +119,8 @@ All good when you see `0 wrong hash`. ## Undo -It keeps every file it replaces in a `retrobios-backup` folder, beside your -BIOS folder. Nothing is deleted. - -To put your files back, run the command with `--restore` and that folder. The -end of the run prints the exact line. +It keeps every file it replaces in a `retrobios-backup` folder, next to your +BIOS folder. The end of the run prints the line that puts them back. ## If it stops @@ -141,8 +147,8 @@ The download was cut short. Nothing was changed. Run the command again. ### Cannot create ... -You do not have the right to write there. On Batocera, Recalbox and ROCKNIX, -put `sudo` and a space before the command. It then runs as the administrator. +You do not have the right to write there. Do what the message says. It names +what to run. ### Not enough space on the drive holding ... @@ -153,9 +159,8 @@ drive. See [When a game does not start](troubleshooting.md). -:::tip[Next] +## Next steps + - [Your setup's page](../which-pack.md): its folder and how it checks files - [When a game does not start](troubleshooting.md) - Details: [Reading the installer's output, line by line](installer.md#reading-a-run) -::: - diff --git a/wiki/glossary.md b/wiki/glossary.md index e19275e4..75c966e7 100644 --- a/wiki/glossary.md +++ b/wiki/glossary.md @@ -1,7 +1,6 @@ --- level: start order: 60 -nav_title: Glossary --- # Words used on this site @@ -22,6 +21,12 @@ nav_title: Glossary **BIOS folder** : The folder where your setup looks for BIOS files. +**Pack** +: The ZIP file with every BIOS file for one setup. + +**Platform** +: A setup, as the project's data calls it. + **ZIP** : One file that holds many files. You unzip it to get them out. @@ -34,6 +39,9 @@ nav_title: Glossary **Hash** : A fingerprint of a file's contents. A different file gets a different hash. +**MD5** / **SHA-1** +: Two kinds of hash, a file's fingerprint. Setups that check files list one. + **Region** : Where a console was sold: Japan, North America, Europe. @@ -43,9 +51,9 @@ nav_title: Glossary **Game data** : Files from your own copy of a PC game, like Doom. Not a BIOS. -:::tip[Next] +## Next steps + - [What is a BIOS?](what-are-bios-files.md) - [Get your files](../which-pack.md) -- Reference: [Terms of the reference pages](reference-terms.md) -::: +- For contributors: [Terms of the reference pages](reference-terms.md) diff --git a/wiki/legal.md b/wiki/legal.md index f2524f56..638acafc 100644 --- a/wiki/legal.md +++ b/wiki/legal.md @@ -1,10 +1,9 @@ --- -level: explore -order: 40 -nav_title: "Is it legal?" +level: start +order: 55 --- -# The project's legal position +# Is it legal? Redistributing firmware is not settled law. Below is the reasoning the project acts on, with the strength of each argument, so anyone can weigh it. None of it is legal advice, and none of it has been tested in court. @@ -41,8 +40,8 @@ This reflects the project's good-faith understanding, not legal advice. A rights holder, or anyone acting for one, can [open an issue](https://github.com/Abdess/retrobios/issues) identifying the file by path or hash. A file whose removal is requested by its rights holder is removed from the repository and from the next release. No formal notice is required and none will be demanded. State the file and the basis of the claim. The same channel is open to anyone else with a concern about a specific file. -:::tip[Next] -- [FAQ](faq.md) +## Next steps + +- [Common questions](faq.md) - [What is a BIOS?](what-are-bios-files.md) -::: diff --git a/wiki/technical-faq.md b/wiki/technical-faq.md index 9b9adaf6..6a6b7002 100644 --- a/wiki/technical-faq.md +++ b/wiki/technical-faq.md @@ -8,8 +8,8 @@ order: 120 Answers to "how do you know?" questions: how a file is identified, why one BIOS has several fingerprints, why some files are not BIOS, and which MAME version an arcade set belongs to. Each answer gives a real file as its example, so you can -check it on the system pages. Questions asked before installing are in the -[FAQ](faq.md). +check it on the system pages. Questions asked before installing are in +[Common questions](faq.md). ## What's a hash/checksum? @@ -143,8 +143,8 @@ Running `verify.py --emulator --verbose` shows the emulator-level ground It reaches only as far as the profiles do. Files no profile states a value for are platform-only, and nothing can be said about their content. The footer of the platform report gives that ratio as `Ground truth: N/M files have emulator validation`. -:::tip[Next] -- [Reference index](index.md), every reference page in one list +## Next steps + +- [Reference](index.md), every reference page in one list - For contributors: [How to contribute](../contributing.md) -::: diff --git a/wiki/troubleshooting.md b/wiki/troubleshooting.md index 966f2df4..7d14c4e1 100644 --- a/wiki/troubleshooting.md +++ b/wiki/troubleshooting.md @@ -14,6 +14,7 @@ find it. Run the command with `--check`. It changes nothing. + ```sh curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --check ``` @@ -24,16 +25,15 @@ Read the count line: 1/109 present (0 verified, 1 wrong hash) ``` -- **`wrong hash`**: a file is there, but its contents are wrong. It may be for - another region or model, or damaged. +- **`wrong hash`**: a file is there with the wrong contents: another region + or model, or damaged. - **Fewer present than the total**: some files are missing. - **`0 wrong hash` and all present**: your files are fine. Go to step 3. ## 2. Fix the files Run the same command without `--check`. It adds the missing files and replaces -the wrong ones. It keeps the old ones in `retrobios-backup`, beside your BIOS -folder. +the wrong ones, keeping the old ones. ## 3. Check the folder and the names @@ -41,8 +41,10 @@ folder. [Your setup's page](../which-pack.md) names it. - **Is the name exact?** `scph5501.bin` and `SCPH-5501.BIN` are two different names. On Linux, capital letters count too. -- **Unzipped by hand on Linux?** Use the command. Some emulators there need a - lower-case name the ZIP lacks. +- **A `bios` folder inside your BIOS folder?** That ZIP holds its own top + folder. Move its files up one level. +- **Unzipped by hand on Linux?** Run the command once. It adds the names that + differ only by capital letters, which some ZIPs leave out. - **A ZIP in parts will not open?** Download every part, like `Pack.part1of2.zip` and `Pack.part2of2.zip`. Unzip each one into the same folder. @@ -51,6 +53,7 @@ folder. Add `--system` and its name: + ```sh curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --check --system sony-playstation --verbose ``` @@ -60,26 +63,25 @@ console name. ## My setup says UNTESTED -Batocera shows `UNTESTED` for a file whose contents it does not expect. Run -the command without `--check` to replace it. +Batocera shows `UNTESTED` for a file with unexpected contents. Run the command +without `--check` to replace it. ## If the command fails { #installation-script-fails } - **Network error:** check that github.com opens, then try again. -- **Permission denied:** on Batocera, Recalbox and ROCKNIX, put `sudo` and a - space before the command. It then runs as the administrator. -- **No setup found:** name it yourself, with your BIOS folder: +- **Permission denied:** do what the message says. It names what to run. +- **No setup found:** pick it from the list. Or name it and its folder: + ```sh curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --platform retroarch --dest ~/.config/retroarch/system ``` -Other messages: Details: [When something goes wrong](installer.md#when-something-goes-wrong). +Other messages: [When something goes wrong](installer.md#when-something-goes-wrong). -:::tip[Next] -- [Your setup's page](../which-pack.md): its folder and how it checks files -- [FAQ](faq.md) -::: +## Next steps +- [Your setup's page](../which-pack.md): its folder and how it checks files +- [Common questions](faq.md) diff --git a/wiki/what-are-bios-files.md b/wiki/what-are-bios-files.md index 87427f84..c0070d53 100644 --- a/wiki/what-are-bios-files.md +++ b/wiki/what-are-bios-files.md @@ -1,7 +1,6 @@ --- level: start order: 10 -nav_title: What BIOS files are --- # What is a BIOS? @@ -18,8 +17,8 @@ a copy of the BIOS. That copy is a file: a **BIOS file**. ## How it works -1. You pick a game in your game menu. -2. The menu starts the emulator. +1. You pick a game in your setup's menu. +2. The setup starts the emulator. 3. The emulator opens the BIOS file in your **BIOS folder**. 4. The game starts. @@ -57,10 +56,10 @@ then glitch or do not start. The real file works best, so we include it. ## Is it legal? -Laws differ by country. [Read the project's position](faq.md#is-this-legal). +Laws differ by country. [Is it legal?](legal.md) + +## Next steps -:::tip[Next] - [Get your files](../which-pack.md) - [Words used on this site](glossary.md) -:::