kmoody/libretro
1
0 Fork 0
mirror of https://github.com/Abdess/retroarch_system.git synced 2026-10-10 13:33:24 -05:00
Code Issues Packages Projects Releases Wiki Activity

docs: add a first install walkthrough

Browse Source
This commit is contained in:
Abdessamad Derraz committed 2026-09-05 07:46:06 +02:00
1 parent 22d7e4aa9f
commit ab170f990d
7 files changed
+231 -19
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

mkdocs.yml
+1
View File
@@ -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
scripts/generate_site.py
+1
View File
@@ -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"},
wiki/faq.md
+6 -3
View File
@@ -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.
wiki/first-install.md
+184
View File
@@ -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
wiki/getting-started.md
+23 -10
View File
@@ -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,
wiki/index.md
+3 -2
View File
@@ -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.
wiki/troubleshooting.md
+13 -4
View File
@@ -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