Xargon/ES-DE
1
0
Fork 0
mirror of https://github.com/RetroDECK/ES-DE.git synced 2024-11-22 06:05:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2021-07-04 21:01:14 +02:00
parent 4b9dc1e0c4
commit d49d0e3c86
4 changed files with 62 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
CHANGELOG.md
View file

@ -33,6 +33,7 @@ Apart from this, many small improvements and bug fixes are part of the release,
* Default controller configuration is now automatically applied, input configuration should rarely if ever be required any longer except for deliberate button customization * Default controller configuration is now automatically applied, input configuration should rarely if ever be required any longer except for deliberate button customization
* Added support for selecting the controller type (Xbox, Xbox 360, PS4, PS5 and SNES), which changes the help icons, help text and the input configuration tool icons and text * Added support for selecting the controller type (Xbox, Xbox 360, PS4, PS5 and SNES), which changes the help icons, help text and the input configuration tool icons and text
* Added an option to limit the input in ES-DE to only the first controller (does not affect the emulators) * Added an option to limit the input in ES-DE to only the first controller (does not affect the emulators)
* Switched the order of the "Back" and "Start" buttons (or equivalents) in the input configurator to align with the other button entries which go from left to right
* Added separate controller deadzone values for the triggers and thumbsticks * Added separate controller deadzone values for the triggers and thumbsticks
* Removed the startup notification regarding default keyboard mappings being in use, instead default mappings are now considered the recommended input configuration * Removed the startup notification regarding default keyboard mappings being in use, instead default mappings are now considered the recommended input configuration
* The controller input configuration is not automatically started any longer if there is no es_input.cfg file or if there are no applicable configuration entries in the file * The controller input configuration is not automatically started any longer if there is no es_input.cfg file or if there are no applicable configuration entries in the file
@ -73,6 +74,7 @@ Apart from this, many small improvements and bug fixes are part of the release,
* Added a function to ImageComponent to crop fully transparent areas around an image * Added a function to ImageComponent to crop fully transparent areas around an image
* Added a CMake option to control whether the VLC video player should be built, and set this to off by default * Added a CMake option to control whether the VLC video player should be built, and set this to off by default
* Removed the pointless APPLE_SKIP_INSTALL_LIBS CMake option * Removed the pointless APPLE_SKIP_INSTALL_LIBS CMake option
* Added a clang-format style configuration file to use for automatic code formatting
* Added the NanoSVG library as a proper Git subtree * Added the NanoSVG library as a proper Git subtree
* Changed the language standard from C++11 to C++14 * Changed the language standard from C++11 to C++14

34
CONTRIBUTING.md
View file

@ -87,36 +87,20 @@ To see which features have been implemented in previous versions, please refer t
### Coding style ### Coding style
The coding style for ES-DE is mostly a combination of the Linux kernel style (although that's C it's close enough to C++ as far as I'm concerned) and Google's C++ guidelines. The coding style for ES-DE is mostly a combination of the Webkit and Linux kernel guidelines. The cosmetic aspect of the style is auto-formatted using clang-format, so all code changes must first have been processed using this tool. You can read in [INSTALL-DEV.md](INSTALL-DEV.md#using-clang-format-for-automatic-code-formatting) how clang-format is installed and used.
Please refer to these documents here: But of course clang-format won't change the actual code content or fix all code style choices so here are some additional key points:
https://www.kernel.org/doc/html/v4.10/process/coding-style.html \ * Always write comments in C++ style, i.e. `//` instead of `/* */`
https://google.github.io/styleguide/cppguide.html
**Some key points:**
* Column width (line length) is 100 characters
* Indentation is 4 spaces, don't use tabs as they can be interpreted differently
* Line break is Unix-style (line feed only, no carriage return)
* Do not leave trailing whitespaces at the end of the lines (a good source code editor should have a setting to automatically trim these for you)
* When breaking up long lines into multiple lines, consider what could be useful data to grep for so you don't break in the middle of such a string
* Comments always in C++ style, i.e. `//` instead of `/* */`
* Comments should be proper sentences, starting with a capital letter and ending with a dot * Comments should be proper sentences, starting with a capital letter and ending with a dot
* Use K&R placements of braces, read the Linux kernel coding style document for clarifications * As a general rule, use C++ syntax instead of C syntax, for example `static_cast<int>(someFloatVariable)` instead of `(int)someFloatVariable`
* Always use spaces between keywords and opening brackets, i.e. `if ()`, `for ()`, `while ()` etc.
* Indentation of switch/case statements is optional, but it's usually easier to read the code with indentations in place
* Use `std::string` or `std::vector<char>` instead of `char *` or `char []` unless there is a specific reason requiring the latter
* Actually, try to use C++ syntax in general instead of C syntax, another example would be `static_cast<int>(someFloatVariable)` instead of `(int)someFloatVariable`
* If the arguments (and initializer list) for a function or class exceeds 4 items, arrange them vertically to make the code easier to read
* Always declare one variable per line, never combine multiple declarations of the same type * Always declare one variable per line, never combine multiple declarations of the same type
* Name local variables with the first word in small letters and the proceeding words starting with capital letters, e.g. `myExampleVariable` * Name member variables starting with an `m` such as `mMyMemberVariable` and name static variables starting with an `s` such as `sMyStaticVariable`
* Name member variables starting with an `m` such as `mMyMemberVariable` and name static variables with an `s` such as `sMyStaticVariable` * Single-line function definitions can be placed in either the .h or .cpp files depending on the situation
* Use the same naming convention for functions as for local variables, e.g. `someFunction()`
* Single-line function definitions are fine to put in the header files, but if it's more than one line, place it in the corresponding .cpp file * Inline functions makes perfect sense to use, but don't overdo it by using them for code that won't be called very frequently
* Inline functions makes perfect sense to use, but don't overdo it by using them for functions that won't be called very frequently
* Don't put more than one statement on a single line (there are some exceptions though like lambda expressions and possibly switch statements)
* Avoid overoptimizations, especially if it sacrifices readability, makes the code hard to expand on or is error prone * Avoid overoptimizations, especially if it sacrifices readability, makes the code hard to expand on or is error prone
* Try to be coherent with the existing codebase regarding names, structure etc., it should not be obvious which person wrote what parts
* For the rest, check the code and have fun! :) * For the rest, check the code and have fun! :)
### Building and configuring ### Building and configuring

52
INSTALL-DEV.md
View file

@ -14,6 +14,8 @@ ES-DE is developed and compiled using Clang/LLVM and GCC on Unix, Clang/LLVM on
CMake is the build system for all the supported operating systems, used in conjunction with `make` on Unix and macOS and `nmake` and `make` on Windows. Xcode on macOS or Visual Studio on Windows are not required for building ES-DE and they have not been used during the development. The only exception is notarization of codesigned macOS packages which require the `altool` and `stapler` binaries that come bundled with Xcode. CMake is the build system for all the supported operating systems, used in conjunction with `make` on Unix and macOS and `nmake` and `make` on Windows. Xcode on macOS or Visual Studio on Windows are not required for building ES-DE and they have not been used during the development. The only exception is notarization of codesigned macOS packages which require the `altool` and `stapler` binaries that come bundled with Xcode.
For automatic code formatting clang-format is used.
Any code editor can be used of course, but I recommend [VSCode](https://code.visualstudio.com). Any code editor can be used of course, but I recommend [VSCode](https://code.visualstudio.com).
@ -27,7 +29,7 @@ The code has some dependencies. For building, you'll need CMake and development
All of the required packages can be installed with apt-get: All of the required packages can be installed with apt-get:
``` ```
sudo apt-get install build-essential git cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libfreetype6-dev libcurl4-openssl-dev libpugixml-dev rapidjson-dev libasound2-dev libgl1-mesa-dev sudo apt-get install build-essential clang-format git cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libfreetype6-dev libcurl4-openssl-dev libpugixml-dev rapidjson-dev libasound2-dev libgl1-mesa-dev
``` ```
If building with the optional VLC video player, the following packages are also needed: If building with the optional VLC video player, the following packages are also needed:
@ -39,7 +41,7 @@ sudo apt-get install vlc libvlc-dev
Use dnf to install all the required packages: Use dnf to install all the required packages:
``` ```
sudo dnf install gcc-c++ cmake SDL2-devel ffmpeg-devel freeimage-devel freetype-devel curl-devel pugixml-devel rapidjson-devel alsa-lib-devel mesa-libGL-devel sudo dnf install gcc-c++ clang-tools-extra cmake SDL2-devel ffmpeg-devel freeimage-devel freetype-devel curl-devel pugixml-devel rapidjson-devel alsa-lib-devel mesa-libGL-devel
``` ```
If building with the VLC video player, add the RPM Fusion repository. If building with the VLC video player, add the RPM Fusion repository.
@ -56,7 +58,7 @@ sudo dnf install vlc vlc-devel
Use pacman to install all the required packages: Use pacman to install all the required packages:
``` ```
sudo pacman -S gcc make cmake pkgconf sdl2 ffmpeg freeimage freetype2 pugixml rapidjson sudo pacman -S gcc clang make cmake pkgconf sdl2 ffmpeg freeimage freetype2 pugixml rapidjson
``` ```
If building with the optional VLC video player, the following package is also needed: If building with the optional VLC video player, the following package is also needed:
@ -82,7 +84,7 @@ Clang/LLVM and cURL should already be installed in the base OS image.
Use pkgin to install the dependencies: Use pkgin to install the dependencies:
``` ```
pkgin install git cmake pkgconf SDL2 ffmpeg4 freeimage pugixml rapidjson pkgin install clang git cmake pkgconf SDL2 ffmpeg4 freeimage pugixml rapidjson
``` ```
If building with the optional VLC video player, the following package is also needed: If building with the optional VLC video player, the following package is also needed:
@ -90,13 +92,13 @@ If building with the optional VLC video player, the following package is also ne
pkgin vlc pkgin vlc
``` ```
NetBSD ships with GCC by default, and although you should be able to install and use Clang/LLVM, it's probably easier to just stick to the default compiler environment. NetBSD ships with GCC by default, and although you should be able to use Clang/LLVM, it's probably easier to just stick to the default compiler environment. The reason why the clang package needs to be installed is to get clang-format onto the system.
**On OpenBSD** **On OpenBSD**
Use pkg_add to install the dependencies: Use pkg_add to install the dependencies:
``` ```
pkg_add cmake pkgconf sdl2 ffmpeg freeimage pkg_add clang-tools-extra cmake pkgconf sdl2 ffmpeg freeimage
``` ```
If building with the optional VLC video player, the following package is also needed: If building with the optional VLC video player, the following package is also needed:
@ -416,7 +418,7 @@ Be aware that Homebrew can be really slow, especially when it compiles packages
Install the required tools and dependencies: Install the required tools and dependencies:
``` ```
brew install cmake pkg-config nasm fdk-aac libvpx sdl2 freeimage freetype pugixml rapidjson brew install clang-format cmake pkg-config nasm fdk-aac libvpx sdl2 freeimage freetype pugixml rapidjson
``` ```
If building with the optional VLC video player, then run this as well: If building with the optional VLC video player, then run this as well:
@ -768,6 +770,11 @@ Note that most GDB builds for Windows have broken Python support so that pretty
**Other preparations:** **Other preparations:**
In order to get clang-format onto the system you need to download and install Clang: \
[https://llvm.org/builds](https://llvm.org/builds)
Just run the installer and make sure to select the option "Add LLVM to the system PATH for current user".
Install your editor of choice, I use [VSCode](https://code.visualstudio.com). Install your editor of choice, I use [VSCode](https://code.visualstudio.com).
Configure Git. I won't get into the details on how it's done, but there are many resources available online to support with this. The `Git Bash` shell shipped with Git for Windows is very useful though as it's somewhat reproducing a Unix environment using MinGW/MSYS2. Configure Git. I won't get into the details on how it's done, but there are many resources available online to support with this. The `Git Bash` shell shipped with Git for Windows is very useful though as it's somewhat reproducing a Unix environment using MinGW/MSYS2.
@ -1140,6 +1147,37 @@ The theme is not mandatory to start the application, but ES-DE will be basically
So the home directory will always take precedence, and any resources or themes located there will override the ones in the path of the ES-DE executable. So the home directory will always take precedence, and any resources or themes located there will override the ones in the path of the ES-DE executable.
## Using clang-format for automatic code formatting
Although not completed yet as of writing this, ES-DE will have its entire codebase automatically formatted by clang-format. There is a style configuration file named .clang-format located directly at the root of the ES-DE source repository which can be used to apply the formatting anywhere in the source tree.
How to install clang-format is detailed per operating system earlier in this document.
There are two ways to run this tool, from the command line or from inside an editor such as VSCode.
To format a file from the command line, simply run:
```clang-format -i <source file>```
The -i flag will make an inplace edit of the file.
But the recommended way is to run clang-format from within the editor. If using VSCode, there is an extension available named Clang-Format. After installing this, simply open a source file, right click and choose `Format Document` or use the applicable keyboard shortcut. The first time you do this, you will have to make a choice to perform the formatting using clang-format. The rest should be completely automatic.
In some instances you want to avoid getting code formatted, and you accomplish this by simply enclosing the code by the two comments "clang-format off" and "clang-format on", such as this:
```c++
// clang-format off
CollectionSystemDecl systemDecls[] = {
// Type Name Long name Theme folder isCustom
{ AUTO_ALL_GAMES, "all", "all games", "auto-allgames", false },
{ AUTO_LAST_PLAYED, "recent", "last played", "auto-lastplayed", false },
{ AUTO_FAVORITES, "favorites", "favorites", "auto-favorites", false },
{ CUSTOM_COLLECTION, myCollectionsName, "collections", "custom-collections", true }
};
// clang-format on
```
## CA certificates and MAME ROM information ## CA certificates and MAME ROM information
**CA certificates:** **CA certificates:**

12
USERGUIDE-DEV.md
View file

@ -215,7 +215,7 @@ _The help system is displayed at the bottom of the screen, showing the various a
## General navigation ## General navigation
The built-in help system will provide a contextual summary of the available navigation options, but here's still a general overview. These are the inputs you mapped in the previous input device configuration step. Note that this is not an exhaustive list, but it covers most situations. The built-in help system will provide a contextual summary of the available navigation options, but here's still a general overview. These are the buttons optionally mapped in the previous input device configuration step. Note that this is not an exhaustive list, but it covers most situations. The button names are based on the Xbox 360 controller as that is the naming convention used by the SDL library which handles the controller input in ES-DE.
The default keyboard mappings are shown in brackets. The default keyboard mappings are shown in brackets.
@ -234,7 +234,7 @@ _(Escape)_
Opens and closes the main menu. Opens and closes the main menu.
**Select button**\ **Back button**\
_(F1)_ _(F1)_
Opens and closes the game options menu in the gamelist view, or toggles the screensaver in the system view (if the _Enable screensaver controls_ setting is activated). Opens and closes the game options menu in the gamelist view, or toggles the screensaver in the system view (if the _Enable screensaver controls_ setting is activated).
@ -257,7 +257,7 @@ Jumps to a random game or system depending on whether pressed when in the system
**A button**\ **A button**\
_(Enter)_ _(Enter)_
Select button to open gamelists from the system view, launch games, choose menu entries etc. Used to open gamelists from the system view, launch games, choose menu entries etc.
**B button**\ **B button**\
_(Back key)_ _(Back key)_
@ -988,7 +988,7 @@ The screensaven type to use; _Dim_, _Black_, _Slideshow_ or _Video_.
**Enable screensaver controls** **Enable screensaver controls**
This includes the ability to start the screensaver manually using the _Select_ button from the system view, but also while the screensaver is running to jump to a new random game using the _Left_ and _Right_ buttons, to launch the game currently shown using the _A_ button and to jump to the game in its gamelist using the _Y_ button. If this setting is disabled, any key or button press will stop the screensaver. This includes the ability to start the screensaver manually using the _Back_ button from the system view, but also while the screensaver is running to jump to a new random game using the _Left_ and _Right_ buttons, to launch the game currently shown using the _A_ button and to jump to the game in its gamelist using the _Y_ button. If this setting is disabled, any key or button press will stop the screensaver.
#### Slideshow screensaver settings #### Slideshow screensaver settings
@ -1242,7 +1242,7 @@ Self explanatory.
This menu is opened from the gamelist views, and can't be accessed from the system view. The menu changes slightly depending on the context, for example if a game file or a folder is selected, or whether the current system is a collection or a normal game platform. This menu is opened from the gamelist views, and can't be accessed from the system view. The menu changes slightly depending on the context, for example if a game file or a folder is selected, or whether the current system is a collection or a normal game platform.
You open the menu using the **Select** button, and by pressing **B** or selecting the **Apply** button any settings such as letter jumping using the quick selector or sorting changes are applied. If you instead press the Select button again, the menu is closed without applying any changes. You open the menu using the **Back** button, and by pressing **B** or selecting the **Apply** button any settings such as letter jumping using the quick selector or sorting changes are applied. If you instead press the Back button again, the menu is closed without applying any changes.
![alt text](images/current/es-de_game_options_menu.png "ES-DE Game Options Menu") ![alt text](images/current/es-de_game_options_menu.png "ES-DE Game Options Menu")
_The game options menu as laid out when opening it from within a custom collection, which adds the menu entry to add or remove games from the collection._ _The game options menu as laid out when opening it from within a custom collection, which adds the menu entry to add or remove games from the collection._
@ -1449,7 +1449,7 @@ Numerous options can be set for these screensavers, as detailed [here](USERGUIDE
The Dim screensaver simply dims and desaturates the current view and Black will show a black screen. The Slideshow and Video screensavers are more interesting as they can display images and videos from your game collection. In addition to this, the Slideshow screensaver can be configured to only show images from a specified directory. The Dim screensaver simply dims and desaturates the current view and Black will show a black screen. The Slideshow and Video screensavers are more interesting as they can display images and videos from your game collection. In addition to this, the Slideshow screensaver can be configured to only show images from a specified directory.
If the option **Enable screensaver controls** has been activated, you can manually toggle the screensaver from the system view by pressing the **Select** key. In addition to this, for the Slideshow and Video screensavers, the controls will allow you to jump to a new random image or video using the **Left** and **Right** buttons on your keyboard or controller. It's also possible to launch the game currently displayed using the **A** button, and the **Y** button will jump to the game in its gamelist without starting it. If the option **Enable screensaver controls** has been activated, you can manually toggle the screensaver from the system view by pressing the **Back** button. In addition to this, for the Slideshow and Video screensavers, the controls will allow you to jump to a new random image or video using the **Left** and **Right** buttons on your keyboard or controller. It's also possible to launch the game currently displayed using the **A** button, and the **Y** button will jump to the game in its gamelist without starting it.
If the Video screensaver has been selected and there are no videos available, a fallback to the Dim screensaver will take place. The same is true for the Slideshow screensaver if no game images are available. If the Video screensaver has been selected and there are no videos available, a fallback to the Dim screensaver will take place. The same is true for the Slideshow screensaver if no game images are available.