mirror of
https://github.com/Abdess/retroarch_system.git
synced 2026-10-24 04:39:06 -05:00
Abdessamad Derraz
6409757c39
# Conflicts: # CONTRIBUTING.md # scripts/check_release_assets.py # scripts/generate_readme.py
233 lines
8.7 KiB
Markdown
233 lines
8.7 KiB
Markdown
# 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.
|
|
|
|
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. The size depends on the platform and changes with each
|
|
release: the run prints it before downloading (Step 3), and asks first when it
|
|
reaches 1 GB. The installer also 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 8c0e9c762d2f
|
|
|
|
Detecting platform...
|
|
Found Batocera at /userdata/bios
|
|
```
|
|
|
|
The code after RetroBIOS identifies the installer: it is the start of the
|
|
SHA-256 the command checked before running it.
|
|
|
|
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
|
|
|
|
The examples on this page follow the Batocera list as published on 2026-10-21.
|
|
The figures change with each release.
|
|
|
|
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 batocera...
|
|
14481 files (9.1 GB)
|
|
Not installable: 399 files (79 required, not found: 399).
|
|
|
|
Checking existing files...
|
|
0/14481 present (0 verified, 0 wrong hash)
|
|
```
|
|
|
|
`Not installable` counts the files of the list that the collection does not
|
|
hold. They are named at the end of the run (Step 4).
|
|
|
|
On a first install the present count is zero, which is expected, not a fault.
|
|
On a later run it counts what is already there, and only the rest is
|
|
downloaded. A download of 1 GB or more is confirmed first
|
|
(`Download 9.1 GB to /userdata/bios? [Y/n]`).
|
|
|
|
The second phase downloads what is missing, one line per file:
|
|
|
|
```
|
|
Downloading 14481 files (9.1 GB)...
|
|
Press Ctrl+C to stop. Running the same command again carries on from here.
|
|
[1/14481] 3do_arcade_saot.bin ok
|
|
[2/14481] 3dobios.zip 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 end of the run
|
|
|
|
This is what a finished run looks like:
|
|
|
|
```
|
|
Done. 14481 files installed, 0 files already up to date.
|
|
Location: /userdata/bios
|
|
399 files were not installed: the collection does not hold them, or its copy fails their check.
|
|
Needed to start an emulator (79 files):
|
|
dark-forces (theforceengine): DARK.GOB, SOUNDS.GOB, SPRITES.GOB, TEXTURES.GOB
|
|
dark-forces-ii (openjkdf2): openjkdf2/episode/JK1.gob, openjkdf2/episode/JK1CTF.gob, openjkdf2/episode/JK1MP.gob, openjkdf2/resource/Res1hi.gob, openjkdf2/resource/Res2.gob
|
|
diablo (devilutionx): devilutionx/diabdat.mpq
|
|
doom3 (dhewm3): base/pak000.pk4, base/pak002.pk4, base/pak003.pk4, base/pak004.pk4
|
|
droidworks (openjkdf2): dwCD.GOB, dwHD.GOB, dwMin.GOB, dwStream.GOB
|
|
fallout (fallout1-ce): fallout1-ce/critter.dat, fallout1-ce/master.dat
|
|
fallout2 (fallout2-ce): fallout2-ce/critter.dat, fallout2-ce/master.dat
|
|
fury (fury): fury.grp
|
|
... and 9 more systems (--check --verbose lists them all)
|
|
Each emulator's page says what these files are: https://abdess.github.io/retrobios/emulators/
|
|
To check this later, run the same command with --check.
|
|
```
|
|
|
|
The word `Done` and a location are the confirmation. Any other ending (`Stopped`,
|
|
`Finished with errors`, `Nothing was installed`) means something was left undone,
|
|
and the run says which case it was.
|
|
|
|
The lines between `Location:` and the `--check` hint name the files of the list
|
|
that the collection does not hold. `Needed to start an emulator` gives, for each
|
|
system, the emulators that read it and the files they cannot start without. On
|
|
the run above, all 79 belong to games (Dark Forces, Diablo, Doom 3, Tomb Raider
|
|
and the others): the engine reads them from a copy of the game itself. The
|
|
other 320 are optional, and the emulators reading them start without them.
|
|
|
|
## 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...
|
|
14481/14481 present (14481 verified, 0 wrong hash)
|
|
|
|
All files up to date.
|
|
```
|
|
|
|
The files the collection does not hold are listed after it again, as long as
|
|
they are absent from the folder. `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.
|
|
|
|
At a terminal, a menu follows that line. The platform is picked by its number,
|
|
then the run asks for the BIOS folder, offering the platform's usual folder on
|
|
this system as the default when it has one.
|
|
|
|
Without a terminal, or with `--no-input`, the run stops there and prints the
|
|
command to use instead, with the platform and the folder named:
|
|
|
|
```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.
|
|
|
|
No Python 3.8 or newer was found: Python is missing, or older. The message
|
|
names the command that installs it on the system it runs on: `sudo apt install
|
|
python3` on Debian and Ubuntu, `sudo dnf install python3` on Fedora, `sudo
|
|
pacman -S python` on Arch, `xcode-select --install` on macOS and `pkg install
|
|
python` in Termux, where it offers to run that command itself (Termux installs
|
|
without root). On Windows, `install.ps1` offers to run `winget install
|
|
Python.Python.3.12`. 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.
|
|
|
|
A stock RetroPie 4.8 image is Debian Buster, where `python3` is 3.7.3 and apt
|
|
has nothing newer, so the same command changes nothing. The RetroPie pack from
|
|
the [releases page](https://github.com/Abdess/retrobios/releases/latest),
|
|
extracted into `~/RetroPie/BIOS/`, installs the same files.
|
|
|
|
### Error: the downloaded installer does not match its expected fingerprint.
|
|
|
|
Nothing was run and nothing was written. The download did not match the
|
|
fingerprint the script carries, which is almost always a transfer cut short.
|
|
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
|