Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
coding_rules [2021/11/03 05:32] – [How to add an emulator] amended ataricoding_rules [2022/07/21 02:43] (current) – add some bullet point coding rules atari
Line 7: Line 7:
  
 In other words, don't try to handle all cases if it makes the software complicated and unmaintainable. In other words, don't try to handle all cases if it makes the software complicated and unmaintainable.
 +
 +  * Don't add new systems that are simply variations of other systems, aim to have one folder per system. An exception to this rule would be if a system required different configuration to launch, as asking the user to create two sets of custom emulator settings should be avoided.
 +  * Don't put in [[:devices|device]]-specific ''if'' conditions into Batocera's ''/etc/init.d'' scripts. These should be applied via [[:udev_rules|udev rules]] for proper identification. Ultimately, it would be preferable to fix the global script in the first place to be suitable for all situations.
 +  * Build emulators from their source where possible.
 +  * Don't add emulators that duplicate the function of other emulators. We must avoid redundancy as there is an upper limit as to how much data can be packed into the ''batocera'' update file.
 +  * Avoid making patches if possible, encourage the source developer of the software to fix issues upstream.
 +  * Avoid adding files to the ''fsoverlay''. Fix the core root of the issue instead.
 +
 +<WRAP center round info>
 +A timeline of when certain changes are allowed to be merged upstream can be found here: https://batocera.org/timeline
 +</WRAP>
  
 ===== Project files ===== ===== Project files =====
  
-The [[https://github.com/batocera-linux/batocera.linux|batocera.linux]] git is based on a Buildroot tree. Ideally, a file is either owned by Batocera or by Buildroot. [[#on_buildroot|Buildroot files must not be modified]]. The following directories are owned by Batocera:+The [[https://github.com/batocera-linux/batocera.linux|batocera.linux]] git is based on a Buildroot tree. Ideally, a file is either owned by Batocera or by Buildroot. [[#on_buildroot|Buildroot files must not be modified]]. 
 + 
 +The following directories are owned by Batocera:
  
 ==== defconfig build files ==== ==== defconfig build files ====
Line 41: Line 54:
 Windows Vista and above support symlinks, but this is not built-in by default. Here's an unofficial extension to explorer.exe that adds such functionality: https://schinagl.priv.at/nt/hardlinkshellext/linkshellextension.html Windows Vista and above support symlinks, but this is not built-in by default. Here's an unofficial extension to explorer.exe that adds such functionality: https://schinagl.priv.at/nt/hardlinkshellext/linkshellextension.html
 </WRAP> </WRAP>
- 
-===== How to add an emulator ===== 
- 
-  - Install (its initial configuration script in its package at https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/emulators/<new emulator>/Config.in is called by https://github.com/batocera-linux/batocera.linux/blob/master/Config.in) and compile (make file for the new emulator at https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/emulators/<new emulator>/<new emulator>.mk and its build configuration at https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/emulators/<new emulator>/Config.in) your emulator with Batocera. Ensure that there are no valid build errors with it. 
-  - Add your system/emulator to the EmulationStation system configuration at https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/emulationstation/batocera-es-system/es_systems.yml (if you're adding an emulator to an already existing system and don't need it to be the default, you can leave this alone). 
-    * You can check a list of system shortnames that can be automatically scraped for here: https://github.com/batocera-linux/batocera-emulationstation/blob/master/es-app/src/PlatformId.cpp 
-  - Add your system/emulator to the features list (https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/emulationstation/batocera-es-system/es_features.yml) and any advanced system settings if necessary. 
-  - Create and test its config generator at https://github.com/batocera-linux/batocera.linux/tree/master/package/batocera/core/batocera-configgen/configgen/configgen/generators. 
-    - Define the generator (syntax: ''from generators.<shortname>.<shortname>Generator import <CamelCased shortname>Generator'', shortname is the [[:systems|system name]]) with its system shortname here: https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-configgen/configgen/configgen/emulatorlauncher.py (you can test this locally with ''/usr/lib/python3.9/site-packages/configgen/emulatorlauncher.py''). The ''commandArray'' is ultimately the line that is used to run the emulator from bash. 
-    - Include it in the packages list (syntax: ''configgen.generators.<shortname>'') here: https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-configgen/configgen/setup.py. 
-    - Create the "main" configuration generator Python script here: https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-configgen/configgen/configgen/generators/ followed by <shortname>/<shortname>Generator.py. 
-    - If appropriate, split the file into multiple Python scripts called by <shortname>Generator.py in the ''generators/<shortname>/'' folder. 
-    - Call the files if required here: https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-configgen/configgen/configgen/batoceraFiles.py. 
-  - Configure the default emulator (if you've added a whole new system) with https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-configgen/configs/configgen-defaults.yml. 
-  - Configure the default settings for particular architectures (such as if your emulator requires certain settings to function on a particular architecture) at https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-configgen/configs/. 
-  - Limit your emulator to particular platforms (most typically, most complex standalone emulators are x86/x86_64 only) with https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-system/Config.in. 
-  - If BIOS files are required, set them in https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-scripts/scripts/batocera-systems 
- 
-If you'd like an example of a recent pull request that adds a whole new emulator: https://github.com/batocera-linux/batocera.linux/pull/4742/files 
  
 ===== Global features/advanced system settings ===== ===== Global features/advanced system settings =====
Line 68: Line 62:
  
 <code yaml> <code yaml>
-<emulator 1 shortname>: # We refer to the internal name of the emulator, not the system name.+<emulator_1_shortname>: # We refer to the internal name of the emulator, not the system name. 
 +  group: <group name> # An optional group to sort this feature under. This is mostly used to categorize "advanced options" together, not much else.
   features: [<common feature 1>, <common feature 2>, <...>] # All the global options applicable to this emulator.   features: [<common feature 1>, <common feature 2>, <...>] # All the global options applicable to this emulator.
   cfeatures: # Custom features, found in the advanced settings.   cfeatures: # Custom features, found in the advanced settings.
Line 105: Line 100:
                 "Vulkan": Vulkan                 "Vulkan": Vulkan
         perf_hacks:         perf_hacks:
 +            group: ADVANCED OPTIONS
             prompt:      PERFORMANCE HACKS             prompt:      PERFORMANCE HACKS
             description: Increase emulator performance, at the cost of accuracy/stability             description: Increase emulator performance, at the cost of accuracy/stability
Line 114: Line 110:
         cfeatures:         cfeatures:
             emulatedwiimotes:             emulatedwiimotes:
 +                group: ADVANCED OPTIONS
                 prompt:      EMULATE WIIMOTE                 prompt:      EMULATE WIIMOTE
                 description: Use your gamepad like a vertical Wiimote in game                 description: Use your gamepad like a vertical Wiimote in game
Line 123: Line 120:
 Spacing is everything here. Triple-check that you have used the correct amount of indentation. If your build fails to compile because of errors related to ''es_features.yml'' after you have made modifications to it then this is likely the culprit. Spacing is everything here. Triple-check that you have used the correct amount of indentation. If your build fails to compile because of errors related to ''es_features.yml'' after you have made modifications to it then this is likely the culprit.
  
-General practice isn't to be a one-for-one representation of the settings available to the emulator, that would defy the point of Batocera. Important settings that may need to be changed frequently/per game should be represented as is, but generally the more advanced settings should be simplified (with the help of the config generator setting all the correct values) and clearly explained in the advanced system settings. For example, the above ''PERFORMANCE HACKS'' setting actually changes a bunch of settings within Dolphin all at once:+<WRAP center round tip> 
 +A new way to use options is available as presets, read more about it on [[https://github.com/batocera-linux/batocera-emulationstation/pull/1089|its pull request]]. This also introduced the ability to have global options in the per-system option. Don't do that in Batocera. 
 + 
 +(FIXME how is this done in Batocera, though?) 
 +</WRAP> 
 + 
 +General practice isn't to be a one-for-one representation of the settings available to the emulator, that would defy the point of Batocera. Important settings that may need to be changed frequently/per game should be represented as is, but generally the more advanced settings should be simplified (with the help of the config generator setting all the correct values for that emulator's configuration files as necessary) and clearly explained in the advanced system settings. For example, the above ''PERFORMANCE HACKS'' setting actually changes a bunch of settings within Dolphin all at once. Here's a snippet of its config generator:
  
 <code python> <code python>
Line 153: Line 156:
                 dolphinGFXSettings.remove_option("Enhancements", "DisableCopyFilter")                 dolphinGFXSettings.remove_option("Enhancements", "DisableCopyFilter")
                 dolphinGFXSettings.remove_option("Enhancements", "ForceTrueColor")                   dolphinGFXSettings.remove_option("Enhancements", "ForceTrueColor")  
 +</code>
 +
 +==== Multi-line descriptions ====
 +
 +Use of multi-line descriptions is discouraged, but for excessively complicated options requiring more detailed descriptions exceptions can be made.
 +
 +A multi-line description can be enabled by prepending ''|-'' into the description field for the option and using ordinary YAML multi-line strings.
 +
 +<code yaml>
 +[...]
 +prompt:      HEADS UP DISPLAY
 +    description: |-
 +                 Show context-sensitive info
 +                 over the game
 +                 and a 3rd line
 +                 and a 4th line.
 +    submenu: DECORATIONS
 +[...]
 </code> </code>
  
Line 162: Line 183:
   * Only update values controlled by Batocera   * Only update values controlled by Batocera
  
-Configuration handled by Batocera comes from three places:+Configuration handled by Batocera comes from:
   * the configgen plugin. hardcoded or dependant on non user values (the number of plugged pads for example)   * the configgen plugin. hardcoded or dependant on non user values (the number of plugged pads for example)
   * **configgen-defaults.yml** the default configuration   * **configgen-defaults.yml** the default configuration
Line 168: Line 189:
   * **batocera.conf** The settings file saved to by EmulationStation or manually edited by the user. Contains keys such as ''global.<setting>=<value>'' or ''<system>.<emulator>.<setting>=<value>''   * **batocera.conf** The settings file saved to by EmulationStation or manually edited by the user. Contains keys such as ''global.<setting>=<value>'' or ''<system>.<emulator>.<setting>=<value>''
  
-Note: ideally, ''batocera.conf'' must be installed empty and keep only user-changed settings. Default system configurations must be only in YML files. EmulationStation is capable of editing the ''batocera.conf'' file.+<WRAP center round info> 
 +Ideally, ''batocera.conf'' must be installed empty and keep only user-changed settings. Default system configurations must be only in YML files. EmulationStation is capable of editing the ''batocera.conf'' file. 
 +</WRAP>
  
 ===== Patches ===== ===== Patches =====
Line 187: Line 210:
  
 In case a modification to a Buildroot file is absolutely necessary, prefix each paragraph by '# batocera' to help during the merges. In case a modification to a Buildroot file is absolutely necessary, prefix each paragraph by '# batocera' to help during the merges.
 +
 +=== When to merge buildroot ===
 +The good way to update buildroot packages is to merge the last official buildroot tree (stable if possible).
 +During last month before a release, we avoid buildroot merges to avoid adding unpredictable bugs.
 +There are some cases we can merge buildroot packages directly, because it worth to have up to date packages. It includes :
 +  * mesa packages (gpu drivers)
 +  * pipewire packages (because it is in a very active phase and solving regularly issues)
 +  * linux-firmwares (because it is incrementing files, not real risk)
 +  * rpi kernels (to be up to date)
 +  * rust (because ruffle uses the last versions)
 +  * linux LTS kernels
  
  • coding_rules.1635917536.txt.gz
  • Last modified: 5 years ago
  • by atari