To work on Batocera, the first step is to get sources and compile it on your computer using this procedure.

Basically, Batocera.linux is based on buildroot. The buildroot documentation for extra information can be found here : https://buildroot.org/downloads/manual/manual.html.

The buildroot steps to compile batocera are described in this page.

Let's assume you want to compile for Raspberry Pi3 (other architecture options and the steps to get there are described on this page).

make batocera-rpi3_defconfig

This steps mainly creates the file .config from the file configs/batocera-rpi3_defconfig.

If you modified manually the .config file for testing/dev purposes, you can reset it by running the previous command again.

batocera-rpi3_defconfig is a quite small file defining what is wanted to be built in the target. For example, kodi and emulationstation (and… well, a bit more ;) …).

.config is a file listing all the packages available, and for each of them, if it's going to be built or not.

In other words, batocera-rpi3_defconfig is a smaller version of the .config file without explicit dependencies. For example, if you build emulationstation which requires sdl2, in the .config, both are listed to yes (like BR2_PACKAGE_BATOCERA_EMULATIONSTATION=y) in the .config while only emulationstation is listed in the batocera-rpi3_defconfig file.

For each package (ie kodi, emulationstation), buildroot does the following :

1. do prerequisites
2. download
3. extract
4. patch
5. configure
6. build
7. install staging
8. install target

More exactly:

1. do the prerequisite packages recursively if not yet done (ie sdl2 if you want to build emulationstation)
2. download the package in the dl directory according to information from package/package-name/package-name.mk or package/batocera/package-name/package-name.mk
3. extract the package in output/build/package-name-version
4. patch the package from *.patch files (files next to the .mk file or board/batocera/patches/ or board/batocera/rpi/patches/)
5. configure the package according to the .mk file
6. build the package according to the .mk file
7. install in the output/rpi3/host/ staging directory, in case of libraries
8. install in the output/rpi3/target/ directory

For each step, buildroot create a flag file, i.e. .stamp_downloaded in output/rpi3/build/package-name-version.

In case a step failed, just run make or make package-name again to restart/continue the build where you left.

In case you want to rebuild completely a package, just do:

rm -rf output/rpi3/build/package-name-version
make package-name

For example, to build EmulationStation again from the latest master git version:

rm -rf output/rpi3/build/batocera-emulationstation-master
make batocera-emulationstation

When you clone the batocera.linux git repository, you mainly get the following directories:

• .config : the list of all packages, stating if you are going to build it or not.
• dl : the directory where all files are downloaded, for example, batocera-emulationstation-master.tar.gz
• output : the directory where everything is built.

In other words, in order to reinitialize your build, you can type:

rm -rf .config dl output

I personally use the following command to confirm I have no other remaining files:

git status --ignored

My dl directory is a link on ../DL in order to use the same download directory for all my builds, to avoid to download the source archives each time again and again. Note that you may have to remove some packages like batocera-emulationstation-master.tar.gz or batocera-configgen-master.tar.gz while the contains is the master branch of their respective git repositories. In other words, whenever the content is dynamic (master) and not a precise GitHub version. If you commit something on configgen, while the file is in the dl directory, buildroot will not download it again as it is seen as the same filename.

Let's say you want to work on the package “retroarch” to make it evolve via a patch.

First, compile a version of Batocera for the architecture you will test.

Once this is done, you don't need to build it for your tests again. Just run the following commands:

mv output/rpi3/target output/rpi3/target_
cd output/rpi3/build/retroarch-version
git init
git add <the file(s) you want to modify>
# edit the file(s)
git diff > ../../package/batocera/retroarch/001-mymodification.patch
cd ../../..
rm -rf ouput/rpi3/build/batocera/retroarch-version
make retroarch-patch # to confirm the patch is applied
make retroarch # to finish other steps

At this step, output/target contains only the retroarch package. You can install it on your target machine via the command:

rsync -av output/target/ root@batocera.local:/

Remember, Batocera system modification are done on the Linux overlay, i.e. in RAM. Rebooting batocera without saving your overlay acts as if you hadn't changed it – in other words, it's a nice way to make tests while your system is not modified, but those changes are not persistent. If you want to permanently save the modification and keep them upon reboot, you need to use batocera-save-overlay.

EmulationStation is a separate git repository from Batocera system. To work on EmulationStation, the simplest way is to directly get it on your computer and compile it without buildroot.