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

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2021-12-01 19:54:25 +01:00
parent 8c32c5d28c
commit c470abf2da
2 changed files with 18 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
INSTALL-DEV.md
View file

@ -499,14 +499,16 @@ To clone the source repository, run the following:
git clone https://gitlab.com/leonstyhre/emulationstation-de.git git clone https://gitlab.com/leonstyhre/emulationstation-de.git
``` ```
For macOS all dependencies are built in-tree in the `external` directory tree. There are two scripts in the tools directory that automate this entirely. They are executed such as this: For macOS all dependencies are built in-tree in the `external` directory tree. There are two scripts in the tools directory that automate this entirely and they are executed such as this:
``` ```
cd emulationstation-de cd emulationstation-de
tools/macOS_dependencies_setup.sh tools/macOS_dependencies_setup.sh
tools/macOS_dependencies_build.sh tools/macOS_dependencies_build.sh
``` ```
This can take quite a while as multiple packages are downloaded and compiled. Re-running macOS_dependencies_setup.sh will delete and download all dependencies again, and running macOS_dependencies_build.sh will clean and rebuild all packages. If you want to recompile a single package, make sure to first set the MACOSX_DEPLOYMENT_TARGET variable: This can take quite a while as multiple packages are downloaded and compiled. It's important to not have any of the dependency libraries installed using Homebrew as they will interfere with the in-tree build.
Re-running macOS_dependencies_setup.sh will delete and download all dependencies again, and re-running macOS_dependencies_build.sh will clean and rebuild all packages. If you want to recompile a single package, make sure to first set the MACOSX_DEPLOYMENT_TARGET variable:
``` ```
export MACOSX_DEPLOYMENT_TARGET=10.14 export MACOSX_DEPLOYMENT_TARGET=10.14
``` ```
@ -517,7 +519,7 @@ cd external/pugixml
rm CMakeCache.txt rm CMakeCache.txt
cmake . cmake .
make clean make clean
make make -j4
cp libpugixml.a ../.. cp libpugixml.a ../..
``` ```
@ -591,28 +593,31 @@ Running ES-DE from the build directory may be a bit flaky as there is no Info.pl
**Building for the M1 (ARM) processor:** **Building for the M1 (ARM) processor:**
The build steps detailed above should in theory work identically on an M1 processor but possibly some of the dependencies will not build correctly and may need manual patching. Cross-compiling using an Intel processor has been attempted but failed due to multiple issues with depedencies refusing to build. Whenever we'll get access to an M1 Mac the build will be done on this architecture. The build steps detailed above should in theory work identically on an M1 processor but possibly some of the dependencies will not build correctly and may need manual patching. Cross-compiling using an Intel processor has been attempted but failed due to multiple issues with dependencies refusing to build.
**Code signing:** **Code signing:**
Due to the Apple notarization requirement implemented as of macOS 10.14.5 a build with simple code signing is needed for versions up to 10.13 and another build with both code signing and notarization is required for version 10.14 and higher. Due to the Apple notarization requirement implemented as of macOS 10.14.5 a build with simple code signing is needed for versions up to 10.13 and another build with both code signing and notarization is required for version 10.14 and higher.
macOS code signing is beyond the scope of this document, but the option MACOS_CODESIGN_IDENTITY is used to specify the code signing certificate identity, for example: macOS code signing is beyond the scope of this document, but the CMake option MACOS_CODESIGN_IDENTITY is used to specify the code signing certificate identity, for example:
``` ```
cmake -DMACOS_CODESIGN_IDENTITY="My Name" . cmake -DMACOS_CODESIGN_IDENTITY="My Name" .
``` ```
Assuming the code signing ceritificate is properly setup in Keychain Access, the process will be automatic and the resulting DMG package can be notarized as-is. Assuming the code signing ceritificate is properly setup in Keychain Access, the process will be automatic and the resulting DMG package can be notarized as-is. For some reason code signing fails if run via an SSH session, so in order for the cpack command to succeed it needs to run from a terminal window started via the GUI.
**Legacy build:** **Legacy build:**
Normally ES-DE is meant to be built for macOS 10.14 and higher, but a legacy build for earlier operating system versions can be enabled. This has been tested with a minimum version of 10.11. It's unclear if it works with even older macOS versions. Normally ES-DE is meant to be built for macOS 10.14 and higher, but a legacy build for earlier operating system versions can be enabled. This has been tested with a minimum version of 10.11. It's unclear if it works with even older macOS releases.
To enable a legacy build, change the CMAKE_OSX_DEPLOYMENT_TARGET variable in CMakeLists.txt from 10.14 to whatever version you would like to build for. This will disable Hardened Runtime if signing is enabled and it will add 'legacy' to the DMG installer file name when running CPack. To enable a legacy build, change the CMAKE_OSX_DEPLOYMENT_TARGET variable in CMakeLists.txt from 10.14 to whatever version you would like to build for. This will disable Hardened Runtime if signing is enabled and it will add "legacy" to the DMG installer file name when running CPack.
You also need to modify es-app/assets/EmulationStation-DE_Info.plist and set the key SMinimumSystemVersion to the version you're building for. And finally CMAKE_OSX_DEPLOYMENT_TARGET needs to be updated in tools/macOS_dependencies_build.sh. You also need to modify es-app/assets/EmulationStation-DE_Info.plist and set the key SMinimumSystemVersion to the version you're building for. And finally CMAKE_OSX_DEPLOYMENT_TARGET needs to be updated in tools/macOS_dependencies_build.sh. This script then needs to be executed to rebuild all dependencies for the configured macOS version.
Due to issues with getting FFmpeg to compile on some older macOS versions, ES-DE v1.0.1 is the last version where a legacy build has been tested. As some older macOS releases no longer have valid TLS/SSL certificates and Apple is not providing any updates, ES-DE should be built to use the bundled certificates:
```
cmake -DBUNDLED_CERTS=on .
```
**Installing:** **Installing:**

6
USERGUIDE-DEV.md
View file

@ -43,7 +43,7 @@ The following operating systems have been tested (all for the x86 architecture u
* NetBSD 9.1 * NetBSD 9.1
* OpenBSD 6.8 * OpenBSD 6.8
* macOS 10.14 "Mojave" to 12 "Monterey" (the M1 processor is supported via Rosetta 2) * macOS 10.14 "Mojave" to 12 "Monterey" (the M1 processor is supported via Rosetta 2)
* macOS 10.11 "El Capitan" (v1.0 release only) * macOS 10.11 "El Capitan" (legacy release)
* Windows 10 * Windows 10
* Windows 8.1 * Windows 8.1
@ -185,7 +185,7 @@ If you accidentally refused ES-DE the folder access, you can fix this by opening
Another issue on macOS 11 Big Sur (and possibly older OS versions) is that when connecting a Sony DualShock 4 controller either via Bluetooth or using a USB cable, two separate controller devices are registered in parallel. This is a bug in either macOS or the DualShock driver and it makes it seem as if ES-DE is registering double button presses when actually two separate controller devices are generating identical input. A workaround if using Bluetooth mode is to plug in the USB cable just after connecting the controller, wait a second or two and then remove the cable again. This will remove the cabled device, leaving only the Bluetooth device active. Another workaround is to enable the setting _Only accept input from first controller_ in the ES-DE input device settings. The reason why this bug may not be visible in some other games and applications is that ES-DE enables and auto-configures all connected controllers. The issue appears to be resolved in macOS Monterey. Another issue on macOS 11 Big Sur (and possibly older OS versions) is that when connecting a Sony DualShock 4 controller either via Bluetooth or using a USB cable, two separate controller devices are registered in parallel. This is a bug in either macOS or the DualShock driver and it makes it seem as if ES-DE is registering double button presses when actually two separate controller devices are generating identical input. A workaround if using Bluetooth mode is to plug in the USB cable just after connecting the controller, wait a second or two and then remove the cable again. This will remove the cabled device, leaving only the Bluetooth device active. Another workaround is to enable the setting _Only accept input from first controller_ in the ES-DE input device settings. The reason why this bug may not be visible in some other games and applications is that ES-DE enables and auto-configures all connected controllers. The issue appears to be resolved in macOS Monterey.
In macOS 12 Monterey there has been a quite serious OpenGL driver bug introduced by Apple which disables VSync, making the operating system always try to render as many frames as it can. This slows down ES-DE quite a lot and consumes lots of machine resources. The issue is discussed [here](https://github.com/libsdl-org/SDL/issues/4918). There is a temporary workaround available which can be enabled via the _macOS Monterey VSync bug workaround_ setting in the _Other settings_ menu. This will add a short 10 millisecond delay after each frame if the last frame was swapped in less than 3 milliseconds. It's not a proper fix but it should at least make ES-DE usable on Monterey until Apple releases a patch for the bug. In macOS 12 Monterey there has been a quite serious OpenGL driver bug introduced by Apple which disables VSync, making the operating system always try to render as many frames as it can. This slows down ES-DE quite a lot and consumes lots of machine resources. The issue is discussed [here](https://github.com/libsdl-org/SDL/issues/4918). There is a temporary workaround available via the _macOS Monterey VSync bug workaround_ setting in the _Other settings_ menu (which is enabled by default). This will add a short 10 millisecond delay after each frame if the last frame was swapped in less than 3 milliseconds. It's not a proper fix but it should at least make ES-DE usable on Monterey until Apple releases a patch for the bug.
## Specific notes for Raspberry Pi ## Specific notes for Raspberry Pi
@ -1368,7 +1368,7 @@ With this setting enabled, the taskbar will be hidden when launching ES-DE, and
**macOS Monterey VSync bug workaround** _(macOS only and hopefully only temporary)_ **macOS Monterey VSync bug workaround** _(macOS only and hopefully only temporary)_
In macOS 12 Monterey an OpenGL driver bug was introduced that causes VSync to always be disabled. This makes the operating system try to render as many frames as it can which slows down ES-DE quite a lot as well as consuming lots of machine resources. By enabling this setting, a small 10 millisecond delay will be introduced after each frame if it took less than 3 milliseconds to swap the last one. This is not a proper solution, and it's not an accurate solution but it's at least something until Apple (hopefully) fixes the bug via an OS update. Earlier macOS versions are unaffected by this issue. To check if you have this problem, enable the _Display GPU statistics overlay_ setting and if your FPS counter shows really high numbers (like in the hundreds of frames per second) then enable this option and the FPS counter should decrease significantly. In macOS 12 Monterey an OpenGL driver bug was introduced that causes VSync to always be disabled. This makes the operating system try to render as many frames as it can which slows down ES-DE quite a lot as well as consuming lots of machine resources. Using this setting (which is enabled by default), a small 10 millisecond delay is introduced after each frame if it took less than 3 milliseconds to swap the last one. This is not a proper solution, and it's not an accurate solution but it's at least something until Apple hopefully fixes the bug via an OS update. Earlier macOS releases are unaffected by this issue. To check if you have this problem, disable the setting and then enable the _Display GPU statistics overlay_ option. If your FPS counter shows really high numbers (like in the hundreds of frames per second) then the issue is present on your machine.
**Run in background (while game is launched)** **Run in background (while game is launched)**