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 [2022/02/01 02:14] – [How to add an emulator] changed step 1 into a list for easier comprehension, added step for include package in update checker 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 ===== 
- 
-  - Add the initial scripts for successful compilation. Ensure that there are no valid build errors with it. 
-    - Create its initial configuration script: https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/emulators/<new emulator>/Config.in 
-    - Call it from https://github.com/batocera-linux/batocera.linux/blob/master/Config.in 
-    - Create its makefile for package compilation: https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/emulators/<new emulator>/<new emulator>.mk 
-    - If building from source, add the git repository check to the update script: https://github.com/batocera-linux/batocera.linux/blob/master/scripts/linux/checkPackagesUpdates.sh 
-  - 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 (typically, 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 73: Line 63:
 <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 109: 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 118: 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 126: Line 119:
  
 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.
 +
 +<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: 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:
Line 157: 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 166: 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
  • coding_rules.1643681694.txt.gz
  • Last modified: 4 years ago
  • by atari