From ab170f990df5695bdc7046c06d2d1692a2f196b3 Mon Sep 17 00:00:00 2001 From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com> Date: Sat, 5 Sep 2026 07:39:50 +0200 Subject: [PATCH] docs: add a first install walkthrough --- mkdocs.yml | 1 + scripts/generate_site.py | 1 + wiki/faq.md | 9 +- wiki/first-install.md | 184 +++++++++++++++++++++++++++++++++++++++ wiki/getting-started.md | 33 ++++--- wiki/index.md | 5 +- wiki/troubleshooting.md | 17 +++- 7 files changed, 231 insertions(+), 19 deletions(-) create mode 100644 wiki/first-install.md diff --git a/mkdocs.yml b/mkdocs.yml index 01dbcfca..56edc09b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -664,6 +664,7 @@ nav: - Data & API: data.md - Wiki: - Overview: wiki/index.md + - First install: wiki/first-install.md - Getting started: wiki/getting-started.md - Installer: wiki/installer.md - FAQ: wiki/faq.md diff --git a/scripts/generate_site.py b/scripts/generate_site.py index b606c72c..130f67a4 100644 --- a/scripts/generate_site.py +++ b/scripts/generate_site.py @@ -3560,6 +3560,7 @@ def generate_mkdocs_nav( wiki_nav = [ {"Overview": "wiki/index.md"}, + {"First install": "wiki/first-install.md"}, {"Getting started": "wiki/getting-started.md"}, {"Installer": "wiki/installer.md"}, {"FAQ": "wiki/faq.md"}, diff --git a/wiki/faq.md b/wiki/faq.md index 04a91363..028edaa4 100644 --- a/wiki/faq.md +++ b/wiki/faq.md @@ -2,13 +2,16 @@ ## My game shows a black screen -Most likely a missing or incorrect BIOS file. Run verification for your platform: +Most likely a missing or incorrect BIOS file. Check what is in the BIOS folder: ```bash -python scripts/verify.py --platform retroarch +curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --check ``` -Look for `missing` or `untested` entries. `missing` means the file is not there at all. `untested` means the file is there but its hash is not the expected one, so it is the wrong version or a bad dump: replace it with one matching the hash listed on the system page. +The count it ends on says what is wrong. A number after `wrong hash` means a +file is there whose contents the platform will reject, so it is the wrong +version or a bad dump, and running the install again replaces it. Files that +are absent are counted as needing downloading. Some cores also support HLE (see below), so a missing BIOS may not always be the cause. Check the emulator's logs for error messages. diff --git a/wiki/first-install.md b/wiki/first-install.md new file mode 100644 index 00000000..b278ac9a --- /dev/null +++ b/wiki/first-install.md @@ -0,0 +1,184 @@ +# First install + +One path, from an empty BIOS folder to files the emulator can read. Every step +shows what the screen looks like when it worked, so there is never a moment of +wondering. + +If something on this page does not match what happens, the last section covers +the cases that come up. + +## Before starting + +Three things, and a few minutes: + +- The BIOS folder the emulator reads. The installer finds it by itself on most + systems; on a handheld, that usually means plugging the SD card into a + computer. +- `curl` or `wget`, and Python 3.8 or newer. The command below checks for both + and stops with a message if either is absent. +- Room on the drive. A full RetroArch set is 5.5 GB, Batocera 4.0 GB, MiSTer + FPGA 24 MB. The installer measures the free space and refuses before writing + anything if there is not enough. + +Nothing is written outside the BIOS folder, and games and saves are never +touched. + +## Step 1. Run the command + +On Linux, macOS, a Steam Deck, or a handheld running Batocera, Recalbox, +KNULLI, ROCKNIX or Lakka: + +```bash +curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh +``` + +On Windows, in PowerShell: + +```powershell +irm https://raw.githubusercontent.com/Abdess/retrobios/main/install.ps1 | iex +``` + +PowerShell's execution policy does not block that line. The policy governs +script files, and this command never writes one. Changing the policy is not +part of installing anything here. + +On Android, from Termux, three commands instead of one: + +```bash +pkg install python +termux-setup-storage +curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh +``` + +Before running anything, that first line downloads the installer, compares it +against the SHA-256 written inside the command's own script, and refuses to +continue if the two differ. To read the script first: + +```bash +curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | less +``` + +## Step 2. Watch it find the platform + +The first lines name what it found and where it will write: + +``` +RetroBIOS + +Detecting platform... + Found Batocera at /userdata/bios +``` + +That path is the one thing worth reading twice. If it is not where the emulator +keeps its BIOS files, stop with Ctrl+C and see the last section. + +## Step 3. Let it work + +Two phases follow. The first reads what is already in the folder, which takes a +few minutes on a memory card because every file is hashed: + +``` +Fetching file index for misterfpga... + 72 files (24.0 MB) + +Checking existing files... + 72/72 present (72 verified, 0 wrong hash) +``` + +On a first install those numbers are zeros, which is expected, not a fault. + +The second phase downloads what is missing, one line per file: + +``` +Downloading 72 files (24.0 MB)... + Press Ctrl+C to stop. Running the same command again carries on from here. + [1/72] AtariLynx/boot.rom ok + [2/72] Astrocade/boot.rom ok +``` + +Ctrl+C is safe at any point. Files already installed stay, and running the +command again picks up where it stopped. + +## Step 4. Read the last three lines + +This is what a finished run looks like: + +``` +Done. 72 files installed, 0 files already up to date. +Location: /userdata/bios +To check this later, run the same command with --check. +``` + +The word `Done` and a location are the confirmation. Any other ending means +something was left undone, and the run says which case it was. + +## Step 5. Confirm it later + +The same command with `--check` reads the folder and writes nothing: + +```bash +curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --check +``` + +``` +Checking existing files... + 72/72 present (72 verified, 0 wrong hash) + + All files up to date. +``` + +`0 wrong hash` is the line that matters. A number there means a file is present +whose contents the platform will reject, and running the install again replaces +it. + +## When the screen says something else + +### No supported platform detected. + +The command was piped from the internet, so it cannot stop and ask a question. +Name the platform and the folder instead: + +```bash +curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh \ + | sh -s -- --platform retroarch --dest /path/to/system +``` + +The accepted names come from `--list-platforms`. For where each platform keeps +its BIOS folder, see [Getting started](getting-started.md). + +### Error: Python 3.8 or newer is required. + +Python is missing from the machine. On Debian and Ubuntu, `sudo apt install +python3`; on a handheld running Batocera or Recalbox it is already there, so +this message usually means the command ran on the computer rather than on the +console. + +### Error: install.py SHA-256 mismatch. + +Nothing was run. The download did not match the fingerprint the script expects, +which is almost always a truncated or intercepted transfer. Running the command +again, on another network if possible, is the answer. + +### Cannot create ... + +The user running the command cannot write there. On Batocera, Recalbox and +ROCKNIX the BIOS folder belongs to root, so the same command with `sudo` in +front of it succeeds. + +### Not enough space on the drive holding ... + +The run stopped before writing. The message names how much is needed and how +much is free. `--dest` installs to another drive. + +### The game still shows a black screen + +A file can be in place and still be the wrong one for that game, or the console +may need a file that nobody has dumped yet. +[Troubleshooting](troubleshooting.md) goes through that case. + +## What comes next + +- [Troubleshooting](troubleshooting.md), when a game does not start +- [FAQ](faq.md), for what the words mean and why a pack is this large +- [Installer](installer.md), for every option, what it detects and what it is + allowed to write diff --git a/wiki/getting-started.md b/wiki/getting-started.md index 6cb0086f..362dc068 100644 --- a/wiki/getting-started.md +++ b/wiki/getting-started.md @@ -6,7 +6,10 @@ BIOS files are firmware dumps from original console hardware. Emulators need the ## Installation -Three ways to get BIOS files in place, from easiest to most manual. +Three ways to get BIOS files in place. The installer is the one to use; +the two sections after it are for when it cannot run. For a walkthrough of a +first install with what each step prints, see +[First install](first-install.md). ### Option 1: the installer (recommended) @@ -214,20 +217,30 @@ BIOS files live in the RomM library under `bios/{platform_slug}/`, one subfolder per system, and are managed through the web interface. Check the [RomM documentation](https://github.com/rommapp/romm) for setup details. -## Verifying your setup +## Checking what you installed -`install.py --check` verifies an existing install without downloading anything. -For the full report, run `verify.py` from a clone of the repository: +`--check` reads the BIOS folder, hashes what is there and writes nothing: ```bash -python scripts/verify.py --platform retroarch -python scripts/verify.py --platform batocera -python scripts/verify.py --platform recalbox +curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --check ``` -The output shows each expected file with its status: `ok`, `missing`, or -`untested`. `untested` means the file is there but its hash is not the expected -one, which is how a wrong revision or a bad dump shows up. +It ends on a count: + +``` +Checking existing files... + 1872/1872 present (1872 verified, 0 wrong hash) + + All files up to date. +``` + +`0 wrong hash` is the line that matters. A number there means a file is present +whose contents the platform will reject, which is how a wrong revision or a bad +dump shows up. + +`scripts/verify.py` answers a different question, how complete this +repository's collection is. It reads `database.json`, never your BIOS folder, +and needs a clone. Only hash-checking platforms can catch a wrong version: Batocera, RetroBat, Recalbox, EmuDeck, RetroDECK, RomM, ROCKNIX and MiSTer FPGA compare MD5, diff --git a/wiki/index.md b/wiki/index.md index 309208a8..fe239ad1 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -9,9 +9,11 @@ each page takes one job from start to finish. ## For users +- **[First install](first-install.md)** - one path from an empty folder to working files, with what each step prints - **[Getting started](getting-started.md)** - installation, BIOS directory paths per platform, verification - **[Installer](installer.md)** - the one-liner in full: bootstrap, options, environment overrides, platform detection, trust boundary -- **[FAQ](faq.md)** - common questions, troubleshooting, hash explanations +- **[Troubleshooting](troubleshooting.md)** - diagnosis by symptom: missing BIOS, hash mismatch, pack issues +- **[FAQ](faq.md)** - common questions, hash explanations If you just want to download BIOS packs, see the [home page](../index.md). @@ -22,7 +24,6 @@ If you just want to download BIOS packs, see the [home page](../index.md). - **[Advanced usage](advanced-usage.md)** - custom packs, region filtering, one file per slot, target filtering, truth generation, emulator verification, offline workflow - **[Verification modes](verification-modes.md)** - how each platform verifies BIOS files, severity matrix, resolution chain - **[Data model](data-model.md)** - database.json structure, indexes, file resolution order, YAML formats -- **[Troubleshooting](troubleshooting.md)** - diagnosis by symptom: missing BIOS, hash mismatch, pack issues, verify errors See also [dump provenance](../provenance.md) for how the collection lines up against the No-Intro, Redump and TOSEC catalogs. diff --git a/wiki/troubleshooting.md b/wiki/troubleshooting.md index 25c06166..f2b1f350 100644 --- a/wiki/troubleshooting.md +++ b/wiki/troubleshooting.md @@ -6,16 +6,25 @@ Diagnosis guide organized by symptom. Each section describes what to check and h Most launch failures are caused by a missing or incorrect BIOS file. -**Check if the BIOS exists:** +**Check what is in your BIOS folder:** + +```bash +curl -fsSL https://raw.githubusercontent.com/Abdess/retrobios/main/install.sh | sh -s -- --check +``` + +It hashes what is there and writes nothing. Anything counted as needing +downloading is absent, and a required file that is absent means the core cannot +start games for that system at all. + +`scripts/verify.py` answers a different question, how complete this +repository's collection is. It reads `database.json`, never your BIOS folder, +and needs a clone: ```bash python scripts/verify.py --platform retroarch --verbose python scripts/verify.py --system sony-playstation ``` -Look for `MISSING` entries in the output. A missing required BIOS means the core -cannot start games for that system at all. - **Check if the hash matches:** Look for `untested` entries in the verify output. This means the file exists but