Overlays (modify the live system)

Batocera is like a firmware. It's a huge virtual filesystem image at /boot/boot/batocera (it has no extension in its filename) which expands into RAM at boot. You cannot modify it directly, and for most use cases, you shouldn't need to modify it. Most files in the / directory stem from this image.

The boot partition is mounted with read-only permissions at /boot/, but can be remounted with write permissions post-boot. All the user data is stored in a separate userdata partition, which is mounted with write permissions at the path /userdata/.

An illustration showing how the batocera system is laid out on a USB stick: the BATOCERA partition first, containing all the programs, and then the SHARE, containing all the userdata

That said, you can utilize overlays to “patch” certain files over the batocera virtual filesystem image at boot.

If you need to edit files to assist in making Batocera boot or to set up external storage, refer to editing the boot partition.

For modifications to the regular Batocera virtual file system, you can directly edit the files in their directory while booted (for example if you want to play with the configgen scripts in /usr/lib/python3.9/site-packages/configgen/generators/ or change the default platform parameters in /usr/share/batocera/configgen/configgen-defaults-arch.yml). Once the modifications are done, you can save them with the command batocera-save-overlay. This command script creates a patch file at /boot/boot/overlay which stores the differences between the current virtual file system and the one stored in /boot/batocera.

Refer to the notable files/folders page for some more interesting files!

This overlay file is automatically removed at the next upgrade.

Even if you don't use the batocera-save-overlay script you can still edit the files in /usr/, but any modification made will be lost on reboot. If you want to remove all your customizations after running batocera-save-overlay, just remove the /boot/boot/overlay file.

By default, Batocera overlay files are limited to 50 MB. If your modifications are over 50 MB, you can specify the size of the overlay with the command. Keep always a bit of margin, the overlay will embed a few more files than those you were expecting (some system files created on-the-fly at boot time). For example, if you need to save 120 MB of data on the system, you can type batocera-save-overlay 120.

This cannot be done for the Batocera v31 on the Odroid XU4 platform.

Some best practices here:

  • modify_the_system_while_it_s_running.txt
  • Last modified: 2 weeks ago
  • by atari