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 04:40] – added advanced system settings section (WIP) 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 +
-  - 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''). +
-    - 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 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. +
-  - 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 +
- +
-===== Advanced system settings ===== +
- +
-<WRAP center round todo> +
-WIP +
-</WRAP> +
- +
-Define advanced system options (outside of the usual video mode, aspect ratio, etc. available to all systems) 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.+
  
 Syntax (replace everything including less-than and greater-than symbols (<>)): Syntax (replace everything including less-than and greater-than symbols (<>)):
  
-<code> +<code yaml> 
-<emulator shortname>: +<emulator_1_shortname>: # We refer to the internal name of the emulator, not the system name. 
-  features: [<common feature 1>, <common feature 2>, <...>] +  group: <group name> # An optional group to sort this feature under. This is mostly used to categorize "advanced options" together, not much else. 
-      cfeatures: +  features: [<common feature 1>, <common feature 2>, <...>] # All the global options applicable to this emulator. 
-          <batocera.conf key name 1>: +  cfeatures: # Custom features, found in the advanced settings. 
-            archs_include: [<archs to limit this option to, if applicable>] +          <batocera.conf key name 1>: # This is what is written as the key name to batocera.conf 
-            prompt:      <ALL CAPS OPTION NAME>+            archs_include: [<arch>] # Platforms to limit this option to, if applicable. 
 +            prompt:      <ALL CAPS OPTION NAME> # All caps because consistency with other labels in ES.
             description: <Explanation of the sentence that doesn't exceed 1000px across.>             description: <Explanation of the sentence that doesn't exceed 1000px across.>
             choices:             choices:
-                "<Option 1 name>":    <batocera.conf value 1>+                "<Option 1 name>":    <batocera.conf value 1> # This is the value written after the "=" in batocera.conf.
                 "<Option 2 name>":    <batocera.conf value 2>                 "<Option 2 name>":    <batocera.conf value 2>
-                "<...>":              <...> +                "<...>":              <...> # etc. for additional values. 
-           <batocera.conf key name 2>:+           <batocera.conf key name 2>: # Add as many unique keys as needed.
              <...>              <...>
-         <options that only apply to a specific system>: +# This section is optional. If there are settings in your emulator that only apply to a specific 
-           <...> +# system, you can add them in here. 
-<emulator 2 shortname>:+  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> </code>
  
-Here's an example system:+Here's an example:
  
-<code>+<code yaml>
 dolphin: dolphin:
   features: [ratio]   features: [ratio]
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:
  
---> Click to reveal the related option in Dolphin's config generator# +<code python>
-<code>+
         # Various performance hacks - Default Off         # Various performance hacks - Default Off
         if system.isOptSet('perf_hacks') and system.getOptBoolean('perf_hacks'):         if system.isOptSet('perf_hacks') and system.getOptBoolean('perf_hacks'):
Line 156: Line 158:
 </code> </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>
  
 ===== How emulator configuration applies ===== ===== How emulator configuration applies =====
Line 165: 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 171: 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 190: 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.1634618414.txt.gz
  • Last modified: 5 years ago
  • by atari