The idea behind the coding rules of batocera.linux is to tell how to make things to keep the project maintainable, upgradable and simple to understand.
Keep It Simple
Worst is better
In other words, don't try to handle all cases if it must make the software complicated an unmaintainable.
batocera.linux git is a buildroot tree. Ideally, a file is owned by batocera.linux or by buildroot. buildroot files must not be modified. The following directory list is the place of files owned by batocera.linux
this is the defconfig files of batocera.linux. One (or several) file by board. These files must be kept are small as possible, while board package selection is done in https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-system/Config.in. The only information that you should find in this file is : the physical architecture, and the packages which are choices while it is technically not possible to put them in the Config.in with KConfig.
this is the place where you can find files specific to batocera and to each board. This directory must be kept as small as possible while ideally, all files are handled by packages.
this place is splitted in several places.
this is the place where you can find all packages specific to batocera.linux. There are organized. Each packages must be self independant (outside of Config.in dependancies).
Package selection by board
ES emulator configuration :
Default emulator configuration (in the same folder, you can find one file by architecture to override by architecture)
For each emulator, a configgen plugin must be done to update emulators config files before the emulator starts. There are 2 kinds of configuration. The one handled by batocera.linux and others. To let the user modify configuration files on configuration not handled by batocera.linux, please keep it true :
Configuration handled by batocera.linux comes from 3 places :
Note: ideally, recalbox.conf must be installed empty and keep only user choices. Default system configurations must be only in yml files. ES is the gui to modify recalbox.conf values.
buildroot uses a great feature : patching program.
Patches are separate files that will modify a program at compilation time. The nice point about these patch is that there are visible and in a single file : it is not sparsed around code at different places. There are 3 places where you can put patches :
this is the prefered place for batocera packages when the hack affects all architectures. It is very visible for the package maintainer.
this is the prefered place when patching a buildroot package that affects all architectures.
this is the prefered place when patch a package having an issue with a specific board. If the patch is not related to the board or has no impact for other boards (like adding a choice entry in a Makefile for a board), the prefered place is not that one. It is prefered to reduce the number of entries in this place to reduce the differences between boards.
You must avoid to modify buildroot files. This makes buildroot upgrade harder. This is buildroot files, not the one of batocera.linux. The script https://github.com/batocera-linux/batocera.linux/blob/master/scripts/linux/buildrootdiff.sh may help you to find altered buildroot files. This number of files must be reduced at maximum.
In case you modify a buildroot file, please prefix each paragraph by '# batocera' to help during the merges.