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/10/19 00:25] – [How to add an emulator] es_features is just as important as es_systems 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 42: Line 55:
 </WRAP> </WRAP>
  
-===== How to add an emulator =====+===== Global features/advanced system settings =====
  
-  - 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. +Define global features and advanced system options in the ''es_features.yml'' file ([[https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/emulationstation/batocera-es-system/es_features.yml|available on the Github here]]). This is a human-readable file containing all the advanced settings available in ES. 
-  - 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 +Syntax (replace everything including less-than and greater-than symbols (<>)): 
-  - 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. +<code yaml> 
-    - 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''). +<emulator_1_shortname>: # We refer to the internal name of the emulator, not the system name. 
-    - 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. +  group: <group name> # An optional group to sort this feature under. This is mostly used to categorize "advanced options" together, not much else. 
-    - 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. +  features: [<common feature 1>, <common feature 2>, <...>] # All the global options applicable to this emulator. 
-    - If appropriate, split the file into multiple Python scripts called by <shortname>Generator.py in the ''generators/<shortname>/'' folder. +  cfeatures: # Custom features, found in the advanced settings. 
-    - Call the files as appropriate and construct the command line here: https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-configgen/configgen/configgen/batoceraFiles.py. +          <batocera.conf key name 1>: # This is what is written as the key name to batocera.conf 
-  - 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. +            archs_include: [<arch>] # Platforms to limit this option to, if applicable. 
-  - 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/. +            prompt:      <ALL CAPS OPTION NAME> # All caps because consistency with other labels in ES. 
-  - 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. +            description: <Explanation of the sentence that doesn't exceed 1000px across.> 
-  - 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+            choices: 
 +                "<Option 1 name>":    <batocera.conf value 1> # This is the value written after the "=" in batocera.conf. 
 +                "<Option 2 name>":    <batocera.conf value 2> 
 +                "<...>":              <...> # etc. for additional values. 
 +           <batocera.conf key name 2>: # Add as many unique keys as needed. 
 +             <...> 
 +# This section is optional. If there are settings in your emulator that only apply to a specific 
 +# system, you can add them in here. 
 +  systems: 
 +    <system 1 shortname>: 
 +          <batocera.conf key name 3>: # Options that only apply to system 1 
 +            <...> # As above. 
 +<emulator 2 shortname>: # Another emulator's settings follow this, so on and so forth... 
 +  <...> 
 +</code> 
 + 
 +Here's an example: 
 + 
 +<code yaml> 
 +dolphin: 
 +  features: [ratio] 
 +  cfeatures: 
 +        gfxbackend: 
 +            archs_include: [x86, x86_64, rpi4, odroidgoa, gameforce] 
 +            prompt:      GRAPHICS BACKEND 
 +            description: Choose your graphics rendering 
 +            choices: 
 +                "OpenGL": OGL 
 +                "Vulkan": Vulkan 
 +        perf_hacks: 
 +            group: ADVANCED OPTIONS 
 +            prompt:      PERFORMANCE HACKS 
 +            description: Increase emulator performance, at the cost of accuracy/stability 
 +            choices: 
 +                "Off": 0 
 +                "On":  1 
 +  systems: 
 +    wii: 
 +        cfeatures: 
 +            emulatedwiimotes: 
 +                group: ADVANCED OPTIONS 
 +                prompt:      EMULATE WIIMOTE 
 +                description: Use your gamepad like a vertical Wiimote in game 
 +                choices: 
 +                    "Off":                       0 
 +                    "On":                        1 
 +</code> 
 + 
 +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. 
 + 
 +<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> 
 +        # Various performance hacks - Default Off 
 +        if system.isOptSet('perf_hacks') and system.getOptBoolean('perf_hacks'): 
 +            dolphinGFXSettings.set("Hacks", "BBoxEnable", '"False"') 
 +            dolphinGFXSettings.set("Hacks", "DeferEFBCopies", '"True"') 
 +            dolphinGFXSettings.set("Hacks", "EFBEmulateFormatChanges", '"False"') 
 +            dolphinGFXSettings.set("Hacks", "EFBScaledCopy", '"True"') 
 +            dolphinGFXSettings.set("Hacks", "EFBToTextureEnable", '"True"') 
 +            dolphinGFXSettings.set("Hacks", "SkipDuplicateXFBs", '"True"') 
 +            dolphinGFXSettings.set("Hacks", "XFBToTextureEnable", '"True"') 
 +            dolphinGFXSettings.set("Enhancements", "ForceFiltering", '"True"') 
 +            dolphinGFXSettings.set("Enhancements", "ArbitraryMipmapDetection", '"True"') 
 +            dolphinGFXSettings.set("Enhancements", "DisableCopyFilter", '"True"') 
 +            dolphinGFXSettings.set("Enhancements", "ForceTrueColor", '"True"')             
 +        else: 
 +            if dolphinGFXSettings.has_section("Hacks"): 
 +                dolphinGFXSettings.remove_option("Hacks", "BBoxEnable") 
 +                dolphinGFXSettings.remove_option("Hacks", "DeferEFBCopies") 
 +                dolphinGFXSettings.remove_option("Hacks", "EFBEmulateFormatChanges") 
 +                dolphinGFXSettings.remove_option("Hacks", "EFBScaledCopy") 
 +                dolphinGFXSettings.remove_option("Hacks", "EFBToTextureEnable") 
 +                dolphinGFXSettings.remove_option("Hacks", "SkipDuplicateXFBs") 
 +                dolphinGFXSettings.remove_option("Hacks", "XFBToTextureEnable") 
 +            if dolphinGFXSettings.has_section("Enhancements"): 
 +                dolphinGFXSettings.remove_option("Enhancements", "ForceFiltering") 
 +                dolphinGFXSettings.remove_option("Enhancements", "ArbitraryMipmapDetection") 
 +                dolphinGFXSettings.remove_option("Enhancements", "DisableCopyFilter") 
 +                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>
  
-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 
 ===== How emulator configuration applies ===== ===== How emulator configuration applies =====
  
Line 67: 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 73: 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 92: 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.1634603150.txt.gz
  • Last modified: 5 years ago
  • by atari