mirror of
https://github.com/RetroDECK/ES-DE.git
synced 2024-11-24 23:25:38 +00:00
Documentation update.
This commit is contained in:
Leon Styhre
parent
4b9dc1e0c4
commit
d49d0e3c86
|
|
@ -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
|
||||
* 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)
|
||||
* 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
|
||||
* 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
|
||||
|
|
@ -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 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
|
||||
* Added a clang-format style configuration file to use for automatic code formatting
|
||||
* Added the NanoSVG library as a proper Git subtree
|
||||
* Changed the language standard from C++11 to C++14
|
||||
|
||||
|
|
|
|||
|
|
@ -87,36 +87,20 @@ To see which features have been implemented in previous versions, please refer t
|
|||
|
||||
### 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 \
|
||||
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 `/* */`
|
||||
* Always write comments in C++ style, i.e. `//` instead of `/* */`
|
||||
* 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
|
||||
* 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
|
||||
* As a general rule, use C++ syntax instead of C syntax, for example `static_cast<int>(someFloatVariable)` instead of `(int)someFloatVariable`
|
||||
* 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 with an `s` such as `sMyStaticVariable`
|
||||
* 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 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)
|
||||
* Name member variables starting with an `m` such as `mMyMemberVariable` and name static variables starting with an `s` such as `sMyStaticVariable`
|
||||
* Single-line function definitions can be placed in either the .h or .cpp files depending on the situation
|
||||
|
||||
* Inline functions makes perfect sense to use, but don't overdo it by using them for code that won't be called very frequently
|
||||
* 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! :)
|
||||
|
||||
### Building and configuring
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
For automatic code formatting clang-format is used.
|
||||
|
||||
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:
|
||||
```
|
||||
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:
|
||||
|
|
@ -39,7 +41,7 @@ sudo apt-get install vlc libvlc-dev
|
|||
|
||||
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.
|
||||
|
|
@ -56,7 +58,7 @@ sudo dnf install vlc vlc-devel
|
|||
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:
|
||||
|
|
@ -82,7 +84,7 @@ Clang/LLVM and cURL should already be installed in the base OS image.
|
|||
|
||||
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:
|
||||
|
|
@ -90,13 +92,13 @@ If building with the optional VLC video player, the following package is also ne
|
|||
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**
|
||||
|
||||
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:
|
||||
|
|
@ -416,7 +418,7 @@ Be aware that Homebrew can be really slow, especially when it compiles packages
|
|||
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:
|
||||
|
|
@ -768,6 +770,11 @@ Note that most GDB builds for Windows have broken Python support so that pretty
|
|||
|
||||
**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).
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## 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:**
|
||||
|
|
|
|||
|
|
@ -215,7 +215,7 @@ _The help system is displayed at the bottom of the screen, showing the various a
|
|||
|
||||
## 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.
|
||||
|
||||
|
|
@ -234,7 +234,7 @@ _(Escape)_
|
|||
|
||||
Opens and closes the main menu.
|
||||
|
||||
**Select button**\
|
||||
**Back button**\
|
||||
_(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).
|
||||
|
|
@ -257,7 +257,7 @@ Jumps to a random game or system depending on whether pressed when in the system
|
|||
**A button**\
|
||||
_(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**\
|
||||
_(Back key)_
|
||||
|
|
@ -988,7 +988,7 @@ The screensaven type to use; _Dim_, _Black_, _Slideshow_ or _Video_.
|
|||
|
||||
**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
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
_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.
|
||||
|
||||
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue