From 4f12ebfc9f30b5f0bc11e2c6d664f0d39a3c4cd3 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Sun, 12 Jun 2022 16:48:52 +0200 Subject: [PATCH] Documentation update. --- CHANGELOG.md | 4 ++-- CREDITS.md | 4 ++-- INSTALL-DEV.md | 20 +++++++++++++++----- INSTALL.md | 18 ++++++++++++++---- README.md | 4 ++-- THEMES-DEV.md | 2 +- USERGUIDE-DEV.md | 12 ++++++++++-- USERGUIDE.md | 10 ++++++++-- 8 files changed, 54 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9fe5d2524..f4cd42246 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -163,6 +163,8 @@ v1.2 maintenance release. * Added support for asterisks/wildcards for emulator name matching, usable both in es_find_rules.xml and es_systems.xml * (Linux) Changed to find rule wildcard matching for the AppImages for Dolphin, mGBA, Play!, RPCS3, Xemu and Yuzu * Changed the sorting in the Alternative emulators interface to use short system names instead of full system names +* Added scraper support for the ti99 platform +* Added TheGamesDB scraper support for the oric platform * Added the pcwindows platform to the lutris system on Unix to improve scraping * Renamed the "Exit button combo" menu option to "Keyboard quit shortcut" * Changed the default quit shortcut from F4 to Alt + F4 on Windows and Unix @@ -849,8 +851,6 @@ Many bugs have been fixed, and numerous features that were only partially implem * On Raspberry Pi OS 11 there are various graphics issues and sometimes the application or emulator completely freezes which requires a power cycle of the machine. This is seemingly due to GPU driver bugs and we can only wait for OS updates to address these problems. These issues have not been encountered on Raspberry Pi OS 10. -* On Fedora 35 a problem has been observed where the screen turns completely black or flickers intensely when starting ES-DE for the first time. A workaround for this is to simply exit the application with F4 or Alt+F4 and starting it again. Everything should then render correctly, and any subsequent startups will work fine including after suspending/resuming the computer. It's currently unclear if this is limited to only Intel GPU drivers or if it's a general issue under Fedora and/or Wayland. At least Wayland on Ubuntu 21.10 does not trigger the same issue. - * There is some screen tearing present on Unix/Linux which is especially visible during horizontal slide transitions. The problem exists on both x86 and ARM as well as on Intel, AMD and Nvidia GPUs and on the Broadcom VideoCore. The problem seems to be Xorg-related as tearing has not been observed when using Wayland, and it's not present on macOS or Windows either. * Sometimes when RetroArch has been upgraded to a newer version, it apparently requires a startup to get properly initialized. When ES-DE starts RetroArch it always does so by passing some specific emulator core parameters, which does not seem to initialize RetroArch after such an upgrade. What happens in this case is that the RetroArch loading screen will be shown and then it will quit right back to ES-DE. If confirmed to be the case, this is not an ES-DE issue but a RetroArch issue and starting RetroArch separately once should fix the problem (at least until the next upgrade). diff --git a/CREDITS.md b/CREDITS.md index d2d10d3c1..9d10f5c49 100644 --- a/CREDITS.md +++ b/CREDITS.md @@ -5,10 +5,10 @@ **Original version**\ Alec Lofquist -**RetroPie Fork**\ +**RetroPie fork**\ RetroPie community -**Desktop Edition fork**\ +**Desktop Edition**\ Leon Styhre \ Sophia Hadash diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index dbded2af0..bb8ab2d5d 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -429,14 +429,24 @@ The process to create a Linux AppImage is completely automated. You simply run t tools/create_AppImage.sh ``` -This script has only been tested on Ubuntu 20.04 LTS and it's recommended to go for an older operating system when building the AppImage to achieve compatibility with a large number of distributions. This does come with some sacrifices though, such as the use of an older SDL version which may not support the latest game controllers. +This script has only been tested on Ubuntu (20.04 LTS and 22.04 LTS) and it's recommended to go for an older operating system when building the AppImage to achieve compatibility with a large number of distributions. This does come with some sacrifices though, such as the use of an older SDL version which may not support the latest game controllers. -The script will delete CMakeCache.txt and run cmake with the BUNDLED_CERTS option, as otherwise scraping wouldn't work on Fedora (and probably on openSUSE and a few other distributions as well). - -Both _appimagetool_ and _linuxdeploy_ are required for the build process but they will be downloaded automatically by the script if they don't exist. So to force an update to the latest build tools, delete these two AppImages prior to running create_AppImage.sh. +The script will delete CMakeCache.txt and run cmake with the BUNDLED_CERTS option, as otherwise scraping wouldn't work on Fedora (and probably not on openSUSE and a few other distributions as well). After creating the AppImage it's recommended to delete CMakeCache.txt manually so the BUNDLED_CERTS option is not accidentally enabled when building the other packages. +To build the Steam Deck-specific AppImage, run the following: +``` +tools/create_AppImage_SteamDeck.sh +``` + +This is similar to the regular AppImage but does not build with the BUNDLED_CERTS option and changes some settings like the VRAM limit. + +Both _appimagetool_ and _linuxdeploy_ are required for the build process but they will be downloaded automatically by the script if they don't exist. So to force an update to the latest build tools, delete these two AppImages prior to running the build script. Be aware though that some releases of linuxdeploy may be broken and could lead to the inclusion of invalid dependencies that will make the package unusable on some distributions. The release with the following -V output has been tested and is working correctly: +``` +linuxdeploy version 1-alpha (git commit ID 9aa59f3), GitHub actions build 41 built on 2021-11-20 01:00:04 UTC +``` + ## Building on macOS ES-DE for macOS is built using Clang/LLVM which is the default compiler for this operating system. It's pretty straightforward to build software on this OS. The main problem is that there is no native package manager, but as there are several third party package managers available, this can be partly compensated for. The use of one of them, [Homebrew](https://brew.sh), is detailed below. @@ -711,7 +721,7 @@ 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) +[https://releases.llvm.org](https://releases.llvm.org) Just run the installer and make sure to select the option _Add LLVM to the system PATH for current user_. diff --git a/INSTALL.md b/INSTALL.md index c0bf12c42..53df00a0a 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -453,14 +453,24 @@ The process to create a Linux AppImage is completely automated. You simply run t tools/create_AppImage.sh ``` -This script has only been tested on Ubuntu 20.04 LTS and it's recommended to go for an older operating system when building the AppImage to achieve compatibility with a large number of distributions. This does come with some sacrifices though, such as the use of an older SDL version which may not support the latest game controllers. +This script has only been tested on Ubuntu (20.04 LTS and 22.04 LTS) and it's recommended to go for an older operating system when building the AppImage to achieve compatibility with a large number of distributions. This does come with some sacrifices though, such as the use of an older SDL version which may not support the latest game controllers. -The script will delete CMakeCache.txt and run cmake with the BUNDLED_CERTS option, as otherwise scraping wouldn't work on Fedora (and probably on openSUSE and a few other distributions as well). - -Both _appimagetool_ and _linuxdeploy_ are required for the build process but they will be downloaded automatically by the script if they don't exist. So to force an update to the latest build tools, delete these two AppImages prior to running create_AppImage.sh. +The script will delete CMakeCache.txt and run cmake with the BUNDLED_CERTS option, as otherwise scraping wouldn't work on Fedora (and probably not on openSUSE and a few other distributions as well). After creating the AppImage it's recommended to delete CMakeCache.txt manually so the BUNDLED_CERTS option is not accidentally enabled when building the other packages. +To build the Steam Deck-specific AppImage, run the following: +``` +tools/create_AppImage_SteamDeck.sh +``` + +This is similar to the regular AppImage but does not build with the BUNDLED_CERTS option and changes some settings like the VRAM limit. + +Both _appimagetool_ and _linuxdeploy_ are required for the build process but they will be downloaded automatically by the script if they don't exist. So to force an update to the latest build tools, delete these two AppImages prior to running the build script. Be aware though that some releases of linuxdeploy may be broken and could lead to the inclusion of invalid dependencies that will make the package unusable on some distributions. The release with the following -V output has been tested and is working correctly: +``` +linuxdeploy version 1-alpha (git commit ID 9aa59f3), GitHub actions build 41 built on 2021-11-20 01:00:04 UTC +``` + ## Building on macOS ES-DE for macOS is built using Clang/LLVM which is the default compiler for this operating system. It's pretty straightforward to build software on this OS. The main problem is that there is no native package manager, but as there are several third party package managers available, this can be partly compensated for. The use of one of them, [Homebrew](https://brew.sh), is detailed below. diff --git a/README.md b/README.md index a96afd010..33b68aedd 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ The following operating systems have been tested (all for the x86 architecture u * Ubuntu 20.04 to 22.04 * Linux Mint 20 * Manjaro 21 -* Fedora 35 Workstation +* Fedora 36 Workstation * SteamOS 3.0 * elementary OS 6 * Raspberry Pi OS 10 and 11 (armv7l and aarch64) @@ -47,7 +47,7 @@ The latest version is 1.2.4 (released 2022-05-27) | macOS DMG installer | macOS 10.14 "Mojave" to 12 "Monterey" | x64 (x86) | [EmulationStation-DE-1.2.4-x64.dmg](https://gitlab.com/es-de/emulationstation-de/-/package_files/40175816/download)| | macOS DMG installer | macOS 11 "Big Sur" to 12 "Monterey" | arm64 (M1) | [EmulationStation-DE-1.2.4-arm64.dmg](https://gitlab.com/es-de/emulationstation-de/-/package_files/40175605/download)| | Debian DEB package | Ubuntu 20.04 to 22.04, Linux Mint 20, possibly others | x64 (x86) | [emulationstation-de-1.2.4-x64.deb](https://gitlab.com/es-de/emulationstation-de/-/package_files/40175731/download)| -| Fedora RPM package | Fedora Workstation 35, possibly others | x64 (x86) | [emulationstation-de-1.2.4-x64.rpm](https://gitlab.com/es-de/emulationstation-de/-/package_files/40176214/download)| +| Fedora RPM package | Fedora Workstation 36, possibly others | x64 (x86) | [emulationstation-de-1.2.4-x64.rpm](https://gitlab.com/es-de/emulationstation-de/-/package_files/40176214/download)| | Arch User Repository | Arch Linux, Manjaro, possibly others | x64 (x86) | [https://aur.archlinux.org/packages/emulationstation-de](https://aur.archlinux.org/packages/emulationstation-de)| | Linux AppImage | Most Linux distributions | x64 (x86) | [EmulationStation-DE-x64.AppImage](https://gitlab.com/es-de/emulationstation-de/-/package_files/40176382/download)| | Linux AppImage | Current Linux distributions with libc 2.34 or later | x64 (x86) | [EmulationStation-DE-x64_Current.AppImage](https://gitlab.com/es-de/emulationstation-de/-/package_files/40176633/download)| diff --git a/THEMES-DEV.md b/THEMES-DEV.md index 4563fc356..ab4c6cc56 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -84,7 +84,7 @@ The following are the most important changes compared to the legacy theme struct * The `forceUppercase` property has been replaced with the more versatile `letterCase` property * Many property names for the carousel have been renamed, with _logo_ being replaced by _item_ as this element can now be used in both the gamelist and system views. As well, setting the alignment will not automatically add any margins as is the case for legacy themes. These can still be set manually using the `horizontalOffset` and `verticalOffset` properties if needed. The way that alignment works in general for both carousel items and the overall carousel has also changed * The carousel text element hacks `systemInfo` and `logoText` have been removed and replaced with proper carousel properties -* The carousel property maxLogoCount is now in float format for more granular control of logo placement compared to integer format for legacy themes. However some legacy theme authors thought this property supported floats (as the theme documentation incorrectly stated this) and have therefore set it to fractional values such as 3.5. This was actually rounded up when loading the theme configuration, and this logic is retained for legacy themes for backward compatibility. But for current themes the float value is correctly interpreted which means a manual rounding of the value is required in order to retain an identical layout when porting theme sets to the new theme engine +* The carousel property maxItemCount (formerly named maxLogoCount) is now in float format for more granular control of logo placement compared to integer format for legacy themes. However some legacy theme authors thought this property supported floats (as the theme documentation incorrectly stated this) and have therefore set it to fractional values such as 3.5. This was actually rounded up when loading the theme configuration, and this logic is retained for legacy themes for backward compatibility. But for current themes the float value is correctly interpreted which means a manual rounding of the value is required in order to retain an identical layout when porting theme sets to the new theme engine * The helpsystem `textColorDimmed` and `iconColorDimmed` properties (which apply when opening a menu) were always defined under the system view configuration which meant these properties could not be separately set for the gamelist views. Now these properties work as expected with the possibility to configure separate values for the system and gamelist views * Correct theme structure is enforced more strictly than before, and deviations will generate error log messages and make the theme loading fail * Many additional elements and properties have been added, refer to the [Reference](THEMES-DEV.md#reference) section for more information diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index 61044e0af..5432e9015 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -40,7 +40,7 @@ The following operating systems have been tested (all for the x86 architecture u * Ubuntu 20.04 to 22.04 * Linux Mint 20 * Manjaro 21 -* Fedora 35 Workstation +* Fedora 36 Workstation * SteamOS 3.0 * elementary OS 6 * Raspberry Pi OS 10 and 11 (armv7l and aarch64) @@ -834,7 +834,13 @@ For instance `topgunnr.7z` will be expanded to `Top Gunner`. This is required by the TheGamesDB scraper where the expanded filenames are used for game searches. (Screenscraper natively supports searches using the MAME names). It's also quite nice to have the gamelist populated with the expanded game names even before any scraping has taken place. -If emulating Sega Model 2 games using _Model 2 Emulator_, then you need to change the ROM directory path in the EMULATOR.INI file to point to your Model 2 ROMs. This file is found in the emulator installation directory. +If emulating Sega Model 2 games using _Model 2 Emulator_, then you need to change the ROM directory path in the EMULATOR.INI file to point to your Model 2 ROMs. If you're using a portable ES-DE installation, then you can set the ROM directory path to be relative, for example: +``` +[RomDirs] +Dir1=..\..\ROMs\arcade\Sega Model 2 +``` + +The EMULATOR.INI file is found in the _Model 2 Emulator_ installation directory. #### Vintage systems emulated using MAME @@ -925,6 +931,8 @@ Exec="/var/lib/flatpak/exports/bin/net.rpcs3.RPCS3" --no-gui "/home/myusername/. If using the AppImage release of RPCS3 on Linux another issue may be that the path to the emulator could change when upgrading to a newer release, which may or may not require manual updates to the desktop files. +Regardless of how you've installed RPCS3, make sure to always test the shortcuts outside ES-DE first, because if they don't work from the desktop, then they will not work from inside ES-DE either. + Apart from this you need to install the PS3 system firmware to use the emulator, but that is described in the RPCS3 documentation. #### Commodore Amiga diff --git a/USERGUIDE.md b/USERGUIDE.md index df76aa353..66f78b602 100644 --- a/USERGUIDE.md +++ b/USERGUIDE.md @@ -38,7 +38,7 @@ The following operating systems have been tested (all for the x86 architecture u * Ubuntu 20.04 to 22.04 * Linux Mint 20 * Manjaro 21 -* Fedora 35 Workstation +* Fedora 36 Workstation * SteamOS 3.0 * elementary OS 6 * Raspberry Pi OS 10 and 11 (armv7l and aarch64) @@ -840,7 +840,13 @@ For instance `topgunnr.7z` will be expanded to `Top Gunner`. This is required by the TheGamesDB scraper where the expanded filenames are used for game searches. (Screenscraper natively supports searches using the MAME names). It's also quite nice to have the gamelist populated with the expanded game names even before any scraping has taken place. -If emulating Sega Model 2 games using _Model 2 Emulator_, then you need to change the ROM directory path in the EMULATOR.INI file to point to your Model 2 ROMs. This file is found in the emulator installation directory. +If emulating Sega Model 2 games using _Model 2 Emulator_, then you need to change the ROM directory path in the EMULATOR.INI file to point to your Model 2 ROMs. If you're using a portable ES-DE installation, then you can set the ROM directory path to be relative, for example: +``` +[RomDirs] +Dir1=..\..\ROMs\arcade\Sega Model 2 +``` + +The EMULATOR.INI file is found in the _Model 2 Emulator_ installation directory. #### Vintage systems emulated using MAME