This shows you the differences between two versions of the page.

Link to this comparison view

coding_rules [2020/01/28 20:47] (current)
genetik57 created
Line 1: Line 1:
 +===== Basics =====
 +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.
 +===== Project files =====
 +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
 +  * configs/batocera_*_defconfig
 +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.
 +  * board/batocera
 +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.
 +  * fsoverlay : files that will be copied over the batocera image. this directory is ideally empty. Avoid adding files here, instead, add them in a package. The same folder exists for each board : <architecture>/fsoverlay.
 +  * patches : packages patches. The same folder exists for each board : <architecture>/patches : packages patches specific to the board
 +  * <architecture>/boot : files specific to the boot
 +  * <architecture>/linux_patches : linux patches specific to the board
 +  * packages/batocera
 +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).
 +===== How to add an emulator =====
 +Package selection by board
 +  * https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-system/Config.in
 +ES emulator configuration :
 +  * https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/emulationstation/batocera-es-system/es_systems.yml
 +Default emulator configuration (in the same folder, you can find one file by architecture to override by architecture)
 +  * https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-configgen/configs/configgen-defaults.yml
 +===== How emulator configuration applies =====
 +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 :
 +  * don't base the configuration on templates
 +  * only update values controlled by batocera.linux
 +Configuration handled by batocera.linux comes from 3 places :
 +  * the configgen plugin. hardcoded or dependant or non user values (the number of plugged pads for example)
 +  * configgen-defaults.yml : the default configuration
 +  * configgen-defaults-arch.yml : the configuration that overrides configgen-defaults.yml defaults for a given architecture
 +  * recalbox.conf : the user can change the values using global.xxx= or emulator.xxx=
 +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.
 +===== How to add a hack =====
 +==== On a package ====
 +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 :
 +  * in the package/batocera/<package_name> directory.
 +this is the prefered place for batocera packages when the hack affects all architectures. It is very visible for the package maintainer.
 +  * in the board/batocera/patches/<package_name> directory.
 +this is the prefered place when patching a buildroot package that affects all architectures.
 +  * in the board/batocera/<architecture>/patches/<package_name> directory.
 +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.
 +==== On buildroot ====
 +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.
  • coding_rules.txt
  • Last modified: 7 months ago
  • by genetik57