Documentation update

CHANGELOG.md

@@ -42,6 +42,7 @@ For the Linux AppImage releases a built-in application updater has been added so
 * Added ares [Benesse Pocket Challenge V2] standalone as an alternative emulator for the wonderswan system
 * Added the .sh file extension to the ags system on Unix and macOS and set the %STARTDIR% variable to the game directory
 * (Linux) Changed a lot of find rules so that emulator AppImages are always searched before Flatpaks
+* (Linux) Removed the AppImage systempath find rule entry for RetroArch
 * (Linux) Added "AppImage (Suspend ES-DE)" and "AppImage (Keep ES-DE running)" as alternative emulators for the windows system
 * (Linux) Added the .AppImage file extension to the windows system
 * (Linux) Added support for the official Citra AppImage release

INSTALL-DEV.md

@@ -1510,6 +1510,13 @@ Here's an example es_find_rules.xml file for Unix (this is not the complete file
 <?xml version="1.0"?>
 <!-- This is the ES-DE find rules configuration file for Unix -->
 <ruleList>
+    <emulator name="OS-SHELL">
+        <!-- Operating system shell -->
+        <rule type="systempath">
+            <entry>bash</entry>
+            <entry>sh</entry>
+        </rule>
+    </emulator>
     <emulator name="RETROARCH">
         <rule type="systempath">
             <entry>retroarch</entry>
@@ -1517,11 +1524,11 @@ Here's an example es_find_rules.xml file for Unix (this is not the complete file
             <entry>RetroArch-Linux-x86_64.AppImage</entry>
         </rule>
         <rule type="staticpath">
+            <entry>~/Applications/RetroArch-Linux*.AppImage</entry>
+            <entry>~/.local/bin/RetroArch-Linux*.AppImage</entry>
+            <entry>~/bin/RetroArch-Linux*.AppImage</entry>
             <entry>/var/lib/flatpak/exports/bin/org.libretro.RetroArch</entry>
             <entry>~/.local/share/flatpak/exports/bin/org.libretro.RetroArch</entry>
-            <entry>~/Applications/RetroArch-Linux-x86_64.AppImage</entry>
-            <entry>~/.local/bin/RetroArch-Linux-x86_64.AppImage</entry>
-            <entry>~/bin/RetroArch-Linux-x86_64.AppImage</entry>
         </rule>
     </emulator>
     <core name="RETROARCH">
@@ -1544,7 +1551,7 @@ Here's an example es_find_rules.xml file for Unix (this is not the complete file
             <entry>/usr/pkg/lib/libretro</entry>
         </rule>
     </core>
-    <emulator name="DOSBOX_STAGING">
+    <emulator name="DOSBOX-STAGING">
         <!-- DOS emulator DOSBox Staging -->
         <rule type="systempath">
             <entry>dosbox-staging</entry>
@@ -1552,6 +1559,7 @@ Here's an example es_find_rules.xml file for Unix (this is not the complete file
         </rule>
         <rule type="staticpath">
             <entry>/var/lib/flatpak/exports/bin/io.github.dosbox-staging</entry>
+            <entry>~/.local/share/flatpak/exports/bin/io.github.dosbox-staging</entry>
         </rule>
     </emulator>
     <emulator name="YUZU">
@@ -1559,13 +1567,13 @@ Here's an example es_find_rules.xml file for Unix (this is not the complete file
         <rule type="systempath">
             <entry>yuzu</entry>
             <entry>org.yuzu_emu.yuzu</entry>
-            <entry>yuzu.AppImage</entry>
         </rule>
         <rule type="staticpath">
-            <entry>/var/lib/flatpak/exports/bin/org.yuzu_emu.yuzu</entry>
             <entry>~/Applications/yuzu*.AppImage</entry>
             <entry>~/.local/bin/yuzu*.AppImage</entry>
             <entry>~/bin/yuzu*.AppImage</entry>
+            <entry>/var/lib/flatpak/exports/bin/org.yuzu_emu.yuzu</entry>
+            <entry>~/.local/share/flatpak/exports/bin/org.yuzu_emu.yuzu</entry>
         </rule>
     </emulator>
 </ruleList>
@@ -1631,6 +1639,13 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
 <?xml version="1.0"?>
 <!-- This is the ES-DE find rules configuration file for macOS -->
 <ruleList>
+    <emulator name="OS-SHELL">
+        <!-- Operating system shell -->
+        <rule type="systempath">
+            <entry>zsh</entry>
+            <entry>bash</entry>
+        </rule>
+    </emulator>
     <emulator name="RETROARCH">
         <rule type="staticpath">
             <entry>/Applications/RetroArch.app/Contents/MacOS/RetroArch</entry>
@@ -1672,6 +1687,12 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
 <?xml version="1.0"?>
 <!-- This is the ES-DE find rules configuration file for Windows -->
 <ruleList>
+    <emulator name="OS-SHELL">
+        <!-- Operating system shell -->
+        <rule type="systempath">
+            <entry>cmd.exe</entry>
+        </rule>
+    </emulator>
     <emulator name="RETROARCH">
         <rule type="winregistrypath">
             <!-- Check for an App Paths entry in the Windows Registry -->
@@ -1698,10 +1719,8 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
             <!-- Portable installation -->
             <entry>%ESPATH%\Emulators\RetroArch-Win64\retroarch.exe</entry>
             <entry>%ESPATH%\Emulators\RetroArch\retroarch.exe</entry>
-            <entry>%ESPATH%\RetroArch-Win64\retroarch.exe</entry>
+            <entry>%ESPATH%\..\Emulators\RetroArch-Win64\retroarch.exe</entry>
-            <entry>%ESPATH%\RetroArch\retroarch.exe</entry>
+            <entry>%ESPATH%\..\Emulators\RetroArch\retroarch.exe</entry>
-            <entry>%ESPATH%\..\RetroArch-Win64\retroarch.exe</entry>
-            <entry>%ESPATH%\..\RetroArch\retroarch.exe</entry>
         </rule>
     </emulator>
     <core name="RETROARCH">
@@ -1711,18 +1730,14 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
     </core>
     <emulator name="PCSX2">
         <!-- Sony PlayStation 2 emulator PCSX2 -->
-        <rule type="winregistryvalue">
-            <entry>SOFTWARE\PCSX2\Install_Dir|\pcsx2.exe</entry>
-        </rule>
         <rule type="systempath">
-            <entry>pcsx2.exe</entry>
+            <entry>pcsx2-qt.exe</entry>
+            <entry>pcsx2-qtx64.exe</entry>
+            <entry>pcsx2-qtx64-avx2.exe</entry>
         </rule>
         <rule type="staticpath">
-            <entry>C:\Program Files (x86)\PCSX2\pcsx2.exe</entry>
+            <entry>%ESPATH%\Emulators\PCSX2-Qt\pcsx2-qt*.exe</entry>
-            <entry>D:\Program Files (x86)\PCSX2\pcsx2.exe</entry>
+            <entry>%ESPATH%\..\Emulators\PCSX2-Qt\pcsx2-qt*.exe</entry>
-            <entry>%ESPATH%\Emulators\PCSX2\pcsx2.exe</entry>
-            <entry>%ESPATH%\PCSX2\pcsx2.exe</entry>
-            <entry>%ESPATH%\..\PCSX2\pcsx2.exe</entry>
         </rule>
     </emulator>
     <emulator name="YUZU">
@@ -1733,8 +1748,7 @@ For reference, here are also example es_find_rules.xml files for macOS and Windo
         <rule type="staticpath">
             <entry>~\AppData\Local\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
             <entry>%ESPATH%\Emulators\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
-            <entry>%ESPATH%\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
+            <entry>%ESPATH%\..\Emulators\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
-            <entry>%ESPATH%\..\yuzu\yuzu-windows-msvc\yuzu.exe</entry>
         </rule>
     </emulator>
 </ruleList>

USERGUIDE-DEV.md

@@ -657,6 +657,46 @@ The following emulators are supported in AppImage format when using the bundled
 
 _RMG = Rosalie's Mupen GUI_
 
+## AppImage vs Flatpak search order on Linux
+
+As of ES-DE 2.1.0 emulator AppImages are always searched before Flatpaks while in previous releases the opposite was true.
+
+To clarify with an example, this is what the find rule entry for the Dolphin emulator looks like:
+```
+<emulator name="DOLPHIN">
+    <!-- Nintendo GameCube and Wii emulator Dolphin -->
+    <rule type="systempath">
+        <entry>dolphin-emu</entry>
+        <entry>org.DolphinEmu.dolphin-emu</entry>
+    </rule>
+    <rule type="staticpath">
+        <entry>~/Applications/Dolphin_Emulator*.AppImage</entry>
+        <entry>~/.local/bin/Dolphin_Emulator*.AppImage</entry>
+        <entry>~/bin/Dolphin_Emulator*.AppImage</entry>
+        <entry>/var/lib/flatpak/exports/bin/org.DolphinEmu.dolphin-emu</entry>
+        <entry>~/.local/share/flatpak/exports/bin/org.DolphinEmu.dolphin-emu</entry>
+    </rule>
+</emulator>
+```
+
+The _staticpath_ rules are always parsed in the order they are defined, and as the AppImage entries are listed above the Flatpak entries, these will be searched first.
+
+There is however a workaround available to launch the Flatpak first, should you prefer that. As you can see in the above example there is also a _systempath_ entry for the Flatpak launch file, and by manually defining the path to your Flatpak bin directory you can make use of this systempath entry instead, which will always be executed before the staticpath entries.
+
+For example if using the ES-DE AppImage release, this would be the command to execute:
+```
+PATH=/var/lib/flatpak/exports/bin:~/.local/share/flatpak/exports/bin:$PATH ./EmulationStation-DE-x64.AppImage
+```
+
+Obviously you would need to change the path to the AppImage if it's not in your current working directory.
+
+You can also set the PATH variable permanently in your shell environment configuration file:
+```
+export PATH=/var/lib/flatpak/exports/bin:~/.local/share/flatpak/exports/bin:$PATH
+```
+
+Refer to your operating system documentation for more details of how the PATH environmental variable works and how to customize your shell environment.
+
 ## Using manually downloaded emulators on Linux
 
 Normally on Linux you would install emulators using either one of the established cross-distribution package formats, i.e. AppImage, Snap or Flatpak, or you would install them using the operating system repository (including the AUR if available on your OS). Less likely would be to manually build from source code and install to a standard system directory. In all these instances ES-DE should be able to find the emulator when launching a game. But in some cases you may instead manually download an emulator as an archive file to unzip somewhere on the file system. Normally you would want to place these files in your home directory, and if running a distribution that has an immutable filesystem (such as SteamOS or Fedora Silverblue), you don't even have the choice to install them to a standard system directory.