From 8ea8eff272fa4a6841454747b1391c422b7ab372 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Wed, 2 Feb 2022 21:26:06 +0100 Subject: [PATCH] Documentation update. --- CHANGELOG.md | 3 +++ INSTALL-DEV.md | 18 +++++++----------- INSTALL.md | 18 +++++++----------- README.md | 8 ++------ USERGUIDE-DEV.md | 16 ++++++---------- USERGUIDE.md | 17 ++++++----------- 6 files changed, 31 insertions(+), 49 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index de43e4139..bab55f4cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,7 @@ * Added scraping of fan art and updated the media viewer to display these images * Added scraping of box back covers when using TheGamesDB * Set the option "Scrape actual folders" as enabled by default and moved it higher up in the scraper options menu +* Set the option "Play audio for screensaver videos" as enabled by default * Added the ability to set a manual sortname specifically for custom collections using the metadata editor * When scraping in semi-automatic mode, horizontal scrolling of long game names are no longer reset when automatically selecting the result * Reduced CPU usage significantly when a menu is open by not rendering the bottom of the stack @@ -35,6 +36,8 @@ * Added renderer support for supplying a separate format than internalFormat when creating textures (although not really supported by the OpenGL standard) * Added the rlottie library as a Git subtree * On Windows all dependencies were moved in-tree to the "external" directory to greatly simplify the build environment +* Updated the build scripts to support native M1/ARM builds on macOS +* Improved the in-tree build on macOS to not needing to install any libraries when compiling the "external" dependencies * Large refactoring to improve thread safety and improve singleton pattern usage * Moved all Platform functions to the utility namespace instead of using the global namespace * Implemented proper XML attribute support in ThemeData that eliminated the risk of name collisions diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index 529fac31f..338e6b5e7 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -432,9 +432,13 @@ Install the Command Line Tools which include Clang/LLVM, Git, make etc. Simply o Following this, install the Homebrew package manager which will simplify the installation of some additional required packages. Run the following in a terminal window: ``` -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +If running on an M1 Mac, you also need to add the following to your `~/.zshrc` shell profile file: +``` +export PATH=/opt/homebrew/bin:$PATH ``` -Be aware that Homebrew can be really slow, especially when it compiles packages from source code. **Package installation with Homebrew** @@ -444,20 +448,12 @@ Install the required tools: brew install clang-format cmake pkg-config nasm yasm ``` -**Some additional/optional steps** +**Developer mode** Enable developer mode to avoid annoying password requests when attaching the debugger to a process: ``` sudo /usr/sbin/DevToolsSecurity --enable ``` -It makes me wonder who designed this functionality and what was their thinking, quite strange. - -If required, define SDKROOT. This is only needed if during compilation you get error messages regarding missing include files. Running the following will properly setup the development environment paths: -``` -export SDKROOT=$(xcrun --sdk macosx --show-sdk-path) -``` - -I suppose you should add this to your shell profile file or similar, but I didn't have to do this step so I'm not sure. **Cloning and compiling** diff --git a/INSTALL.md b/INSTALL.md index df6cf30b8..135757ee1 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -472,9 +472,13 @@ Install the Command Line Tools which include Clang/LLVM, Git, make etc. Simply o Following this, install the Homebrew package manager which will simplify the installation of some additional required packages. Run the following in a terminal window: ``` -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +If running on an M1 Mac, you also need to add the following to your `~/.zshrc` shell profile file: +``` +export PATH=/opt/homebrew/bin:$PATH ``` -Be aware that Homebrew can be really slow, especially when it compiles packages from source code. **Package installation with Homebrew** @@ -490,20 +494,12 @@ If building with the optional VLC video player, then run this as well: brew install --cask vlc ``` -**Some additional/optional steps** +**Developer mode** Enable developer mode to avoid annoying password requests when attaching the debugger to a process: ``` sudo /usr/sbin/DevToolsSecurity --enable ``` -It makes me wonder who designed this functionality and what was their thinking, quite strange. - -If required, define SDKROOT. This is only needed if during compilation you get error messages regarding missing include files. Running the following will properly setup the development environment paths: -``` -export SDKROOT=$(xcrun --sdk macosx --show-sdk-path) -``` - -I suppose you should add this to your shell profile file or similar, but I didn't have to do this step so I'm not sure. **Cloning and compiling** diff --git a/README.md b/README.md index b59b0cdb4..b547388f8 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ The following operating systems have been tested (all for the x86 architecture u * Windows 10 * Windows 8.1 -* macOS 10.14 "Mojave" to 12 "Monterey" (the M1 processor is supported via Rosetta 2) +* macOS 10.14 "Mojave" to 12 "Monterey" (M1/arm64 and Intel/x86) * macOS 10.11 "El Capitan" (legacy release) * Ubuntu 20.04 to 21.10 * Linux Mint 20.2 @@ -33,9 +33,6 @@ The following operating systems have been tested (all for the x86 architecture u * NetBSD 9.1 * OpenBSD 6.8 -If using a Mac with an M1 processor you need to install the x86 version of RetroArch and any other emulators, or you won't be able to launch any games. This will be fixed whenever a native macOS M1 build of ES-DE is released. - - ### Download The latest version is 1.2.0 (released 2021-12-28) @@ -44,6 +41,7 @@ The latest version is 1.2.0 (released 2021-12-28) | :------------------- | :------------------------------------------------------ | :----------- | :------------- | | Windows installer | Windows 10 and 8.1 (probably Windows 11 as well) | x64 (x86) | [EmulationStation-DE-1.2.0-x64.exe](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023950/download)| | macOS DMG installer | macOS 10.14 "Mojave" to 12 "Monterey" | x64 (x86) | [EmulationStation-DE-1.2.0-x64.dmg](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023939/download)| +| macOS DMG installer | macOS 11 "Big Sur" to 12 "Monterey" | arm64 (M1) | [EmulationStation-DE-1.2.0-arm64.dmg](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/27932188/download)| | macOS DMG installer | Legacy macOS 10.11 "El Capitan" to 10.13 "High Sierra" | x64 (x86) | [EmulationStation-DE-1.2.0-x64_legacy.dmg](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023954/download)| | Debian DEB package | Ubuntu 20.04 to 21.10, Linux Mint 20.2, possibly others | x64 (x86) | [emulationstation-de-1.2.0-x64.deb](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023934/download)| | Fedora RPM package | Fedora Workstation 35, possibly others | x64 (x86) | [emulationstation-de-1.2.0-x64.rpm](https://gitlab.com/leonstyhre/emulationstation-de/-/package_files/25023958/download)| @@ -63,12 +61,10 @@ If using FreeBSD, NetBSD or OpenBSD you will need to build ES-DE from source cod Please refer to [CHANGELOG.md](CHANGELOG.md) for more information about the releases, including known issues. - ### Contributing If you would like to contribute to the development of ES-DE, then that's great! Please read how to participate [here](CONTRIBUTING.md) where you can also read about planned future releases and features. - # Additional information [USERGUIDE.md](USERGUIDE.md) is a comprehensive guide on how to use ES-DE and it also contains a complete reference to all application settings. diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index ec722a1af..568402a59 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -35,7 +35,7 @@ The following operating systems have been tested (all for the x86 architecture u * Windows 10 * Windows 8.1 -* macOS 10.14 "Mojave" to 12 "Monterey" (the M1 processor is supported via Rosetta 2) +* macOS 10.14 "Mojave" to 12 "Monterey" (M1/arm64 and Intel/x86) * macOS 10.11 "El Capitan" (legacy release) * Ubuntu 20.04 to 21.10 * Linux Mint 20.2 @@ -47,8 +47,6 @@ The following operating systems have been tested (all for the x86 architecture u * NetBSD 9.1 * OpenBSD 6.8 -If using a Mac with an M1 processor you need to install the x86 version of RetroArch and any other emulators, or you won't be able to launch any games. This will be fixed whenever a native macOS ARM build of ES-DE is released. - Additional known issues are detailed in [CHANGELOG.md](CHANGELOG.md#known-issues). As for display resolutions, the minimum pixel value is 224 and the maximum is 7680. This means that you can run ES-DE at for instance 320x224 all the way up to 7680x4320 (8K UHD). Vertical screen orientation is also supported, as well as ultra-wide resolutions like 3840x1440. Note that there could be some minor visual glitches when running in vertical orientation (this will be fixed in future ES-DE releases) and for the best experience you will probably need to use a customized theme set when running at extreme or unusual resolutions. @@ -197,17 +195,15 @@ An issue on Windows is that some emulators are not shipped with proper installer ## Specific notes for macOS -The main issue with macOS is lack of emulator support and missing (or buggy) controller drivers. +As macOS does not support Vulkan some emulators are not available, and some that do exist have not been updated for this operating system in recent years. As well many emulators available for download are not codesigned and notarized which requires you to override the operating system's security settings to be able to use them. If you see an error popup stating the application couldn't be checked for malicious software or that the developer couldn't be verified, go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button under the _General_ tab. Just note that doing so comes with some potential risks of virus infections and similar. Additionally some emulators are available via the Homebrew package manager, and these do not have the security issues just mentioned so they should be fine to use. Most RetroArch cores are also available on macOS so overall this operating system is still fine for retrogaming albeit with some restrictions. -As macOS does not support Vulkan some emulators are simply not available, and other emulators exist but have not been updated for this operating system in recent years. As well many emulators are available for download but are not codesigned or notarized which require you to override the operating system's security settings to be able to use them. If you see an error popup stating the application couldn't be checked for malicious software or that the developer couldn't be verified, go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button under the _General_ tab. Just note that doing so comes with some potential risks of virus infections and similar. Additionally some emulators are available via the Homebrew package manager, and these do not have the security issues just mentioned so they should be fine to use. Most RetroArch cores are also available on macOS so overall this operating system is still fine for retrogaming albeit with some restrictions. +Lack of controller support is a problem though, and in some instances controller drivers are available but quite buggy. In general it seems as if Sony PlayStation controllers are better supported than Microsoft Xbox controllers. For third party controllers you need to investgate the macOS support as it seems to differ quite a lot. -Lack of controller support is another problem, and in some instances controller drivers are available but quite buggy. In general it seems as if Sony PlayStation controllers are better supported than Microsoft Xbox controllers. For third party controllers you need to investgate the macOS support as it seems to differ quite a lot. +ES-DE is available both as an Intel/x86 build and as a native M1 build. If running on an M1 Mac it's possible to launch either M1 or Intel emulators from ES-DE and in some instances it's recommended to go for the Intel versions. The reason is that some emulators are not yet working properly on the M1 architecture, and for RetroArch some cores are only available for the x86 platform. So investigate what makes most sense for your setup. Over time this situation should improve as M1 support matures. -ES-DE currently ships only as an x86/Intel binary so if you run it on an M1 Mac, you need to also install x86 versions of all emulators including RetroArch. That's also the case for any emulators installed via Homebrew. The reason this is needed is that the Rosetta 2 translation environment does not support mixing of ARM and x86 architectures. +A macOS-specific requirement is that the RetroArch setting "Start in Fullscreen mode" is set as enabled or ES-DE will not be able to switch to the emulator window when launching games. As a workaround you can switch to the window manually using Command + Tab but it probably doesn't make sense to run emulators in windowed mode anyway. It's unclear if only RetroArch is affected by this issue, at least it has not been observed for any other emulators so far. The standalone PlayStation 2 emulator PCSX2 has a similar issue but that seems to be GPU driver related and is problematic also on other operating systems. If using this emulator you need to manually switch to the PCSX2 window using Command + Tab after launching a game. -Another macOS-specific requirement is that the RetroArch setting "Start in Fullscreen mode" must be enabled or ES-DE will not be able to switch to the emulator window. As a workaround you can switch to the window manually using Command + Tab but it probably doesn't make sense to run emulators in windowed mode anyway. It's currently unclear if other emulators than RetroArch are affected by this issue, at least until now none of the other emulators tested have displayed this behavior. The standalone PlayStation 2 emulator PCSX2 has a similar issue but that seems to be GPU driver related and is problematic also on other operating systems. If using this emulator you need to manually switch to the PCSX2 window using Command + Tab after launching the game from ES-DE. - -The first time you launch a game from within ES-DE, the operating system will present you with a security option with the following description: +The first time you launch a RetroArch-emulated game from within ES-DE the operating system will present you with a security option with the following description: `"EmulationStation Desktop Edition" would like to access files in your Documents folder.` diff --git a/USERGUIDE.md b/USERGUIDE.md index 42231eb88..6333ae6a5 100644 --- a/USERGUIDE.md +++ b/USERGUIDE.md @@ -33,7 +33,7 @@ The following operating systems have been tested (all for the x86 architecture u * Windows 10 * Windows 8.1 -* macOS 10.14 "Mojave" to 12 "Monterey" (the M1 processor is supported via Rosetta 2) +* macOS 10.14 "Mojave" to 12 "Monterey" (M1/arm64 and Intel/x86) * macOS 10.11 "El Capitan" (legacy release) * Ubuntu 20.04 to 21.10 * Linux Mint 20.2 @@ -45,8 +45,6 @@ The following operating systems have been tested (all for the x86 architecture u * NetBSD 9.1 * OpenBSD 6.8 -If using a Mac with an M1 processor you need to install the x86 version of RetroArch and any other emulators, or you won't be able to launch any games. This will be fixed whenever a native macOS ARM build of ES-DE is released. - Additional known issues are detailed in [CHANGELOG.md](CHANGELOG.md#known-issues). As for display resolutions, the minimum pixel value is 224 and the maximum is 7680. This means that you can run ES-DE at for instance 320x224 all the way up to 7680x4320 (8K UHD). Vertical screen orientation is also supported, as well as ultra-wide resolutions like 3840x1440. Note that there could be some minor visual glitches when running in vertical orientation (this will be fixed in future ES-DE releases) and for the best experience you will probably need to use a customized theme set when running at extreme or unusual resolutions. @@ -192,20 +190,17 @@ Another possibility is that OpenGL drivers are actually installed but the GPU do An issue on Windows is that some emulators are not shipped with proper installers that implement any mechanism to inform ES-DE where they have been installed (like adding a Registry key with the installation path). This is the case for instance for RPCS3, xemu and xenia. Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These type of emulators are simply shipped as a ZIP file that can be unpacked anywhere on the filesystem. So in order for ES-DE to find them, the directories need to be manually added to the operating system's Path environment variable. This is very easy to do, just open the _Settings_ application and then search for _path_ in the _Find a setting_ search box. Select the _Edit the system environment variables_ entry and then click the _Environment variables..._ button and add the emulator directory to the _Path_ variable. You need to restart ES-DE after changing the variable, but following this the emulator should be found when launching a game. - ## Specific notes for macOS -The main issue with macOS is lack of emulator support and missing (or buggy) controller drivers. +As macOS does not support Vulkan some emulators are not available, and some that do exist have not been updated for this operating system in recent years. As well many emulators available for download are not codesigned and notarized which requires you to override the operating system's security settings to be able to use them. If you see an error popup stating the application couldn't be checked for malicious software or that the developer couldn't be verified, go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button under the _General_ tab. Just note that doing so comes with some potential risks of virus infections and similar. Additionally some emulators are available via the Homebrew package manager, and these do not have the security issues just mentioned so they should be fine to use. Most RetroArch cores are also available on macOS so overall this operating system is still fine for retrogaming albeit with some restrictions. -As macOS does not support Vulkan some emulators are simply not available, and other emulators exist but have not been updated for this operating system in recent years. As well many emulators are available for download but are not codesigned or notarized which require you to override the operating system's security settings to be able to use them. If you see an error popup stating the application couldn't be checked for malicious software or that the developer couldn't be verified, go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button under the _General_ tab. Just note that doing so comes with some potential risks of virus infections and similar. Additionally some emulators are available via the Homebrew package manager, and these do not have the security issues just mentioned so they should be fine to use. Most RetroArch cores are also available on macOS so overall this operating system is still fine for retrogaming albeit with some restrictions. +Lack of controller support is a problem though, and in some instances controller drivers are available but quite buggy. In general it seems as if Sony PlayStation controllers are better supported than Microsoft Xbox controllers. For third party controllers you need to investgate the macOS support as it seems to differ quite a lot. -Lack of controller support is another problem, and in some instances controller drivers are available but quite buggy. In general it seems as if Sony PlayStation controllers are better supported than Microsoft Xbox controllers. For third party controllers you need to investgate the macOS support as it seems to differ quite a lot. +ES-DE is available both as an Intel/x86 build and as a native M1 build. If running on an M1 Mac it's possible to launch either M1 or Intel emulators from ES-DE and in some instances it's recommended to go for the Intel versions. The reason is that some emulators are not yet working properly on the M1 architecture, and for RetroArch some cores are only available for the x86 platform. So investigate what makes most sense for your setup. Over time this situation should improve as M1 support matures. -ES-DE currently ships only as an x86/Intel binary so if you run it on an M1 Mac, you need to also install x86 versions of all emulators including RetroArch. That's also the case for any emulators installed via Homebrew. The reason this is needed is that the Rosetta 2 translation environment does not support mixing of ARM and x86 architectures. +A macOS-specific requirement is that the RetroArch setting "Start in Fullscreen mode" is set as enabled or ES-DE will not be able to switch to the emulator window when launching games. As a workaround you can switch to the window manually using Command + Tab but it probably doesn't make sense to run emulators in windowed mode anyway. It's unclear if only RetroArch is affected by this issue, at least it has not been observed for any other emulators so far. The standalone PlayStation 2 emulator PCSX2 has a similar issue but that seems to be GPU driver related and is problematic also on other operating systems. If using this emulator you need to manually switch to the PCSX2 window using Command + Tab after launching a game. -Another macOS-specific requirement is that the RetroArch setting "Start in Fullscreen mode" must be enabled or ES-DE will not be able to switch to the emulator window. As a workaround you can switch to the window manually using Command + Tab but it probably doesn't make sense to run emulators in windowed mode anyway. It's currently unclear if other emulators than RetroArch are affected by this issue, at least until now none of the other emulators tested have displayed this behavior. The standalone PlayStation 2 emulator PCSX2 has a similar issue but that seems to be GPU driver related and is problematic also on other operating systems. If using this emulator you need to manually switch to the PCSX2 window using Command + Tab after launching the game from ES-DE. - -The first time you launch a game from within ES-DE, the operating system will present you with a security option with the following description: +The first time you launch a RetroArch-emulated game from within ES-DE the operating system will present you with a security option with the following description: `"EmulationStation Desktop Edition" would like to access files in your Documents folder.`