From 79dca0c05ffa56f29770b0503dc0e4e0ee6ae0cf Mon Sep 17 00:00:00 2001 From: Donleon <2455653548@qq.com> Date: Tue, 27 Oct 2026 10:40:20 +0800 Subject: [PATCH 1/3] docs: add tested CM5 desktop launcher instructions --- docs/guides/armsom-cm5.md | 83 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/docs/guides/armsom-cm5.md b/docs/guides/armsom-cm5.md index 49fa48c14f..9ac33461c8 100644 --- a/docs/guides/armsom-cm5.md +++ b/docs/guides/armsom-cm5.md @@ -141,6 +141,89 @@ After exiting the game, you can launch the menu separately: --config "$HOME/retroarch-source-validation/config/retroarch.cfg" --menu ``` +## Create a desktop shortcut + +Run this section as the same regular user who is logged into the XFCE desktop. A launcher created in root's home directory will not appear on another user's desktop. The executable and configuration must also be accessible to that desktop user. + +If you followed the guide as a regular user, skip the recovery subsection and proceed to **Create the launcher**. + +### Recover an installation made as root + +If your shell prompt starts with `root@`, then `~` and `$HOME` refer to `/root`. For the native image's `armsom` desktop account, the following commands copy the existing installation and runtime data into that user's home, update the runtime paths, and set ownership. They leave the original files in `/root` in place. + +Run this block **as root**. It stops if either destination already exists; in that case, inspect the existing installation instead of overwriting it. These paths assume the desktop account is `armsom`. + +```bash +( +set -eu +test ! -e /home/armsom/.local/retroarch-upstream +test ! -e /home/armsom/retroarch-source-validation +cp -a /root/.local/retroarch-upstream /home/armsom/.local/ +cp -a /root/retroarch-source-validation /home/armsom/ +sed -i 's|/root/retroarch-source-validation/|/home/armsom/retroarch-source-validation/|g' /home/armsom/retroarch-source-validation/config/retroarch.cfg +chown -R armsom:armsom /home/armsom/.local/retroarch-upstream /home/armsom/retroarch-source-validation +runuser -u armsom -- /home/armsom/.local/retroarch-upstream/bin/retroarch --version +id armsom +) +``` + +Then switch to the desktop user: + +```bash +su - armsom +``` + +### Create the launcher + +Run this block in the regular user's Bash shell. It creates both a desktop icon and an application-menu entry. It uses `xdg-user-dir` when available, otherwise reads the user's configured desktop directory, falling back to `~/Desktop`. Installing `xdg-user-dirs` is not required. + +```bash +( +set -eu +if [ "$(id -u)" -eq 0 ]; then + printf '%s\n' 'Run this block as the user logged into the XFCE desktop, not root.' >&2 + exit 1 +fi + +retroarch_bin="$HOME/.local/retroarch-upstream/bin/retroarch" +retroarch_config="$HOME/retroarch-source-validation/config/retroarch.cfg" +test -x "$retroarch_bin" +test -r "$retroarch_config" + +desktop_dir="$HOME/Desktop" +if command -v xdg-user-dir >/dev/null 2>&1; then + desktop_dir="$(xdg-user-dir DESKTOP)" +elif [ -r "$HOME/.config/user-dirs.dirs" ]; then + . "$HOME/.config/user-dirs.dirs" + desktop_dir="${XDG_DESKTOP_DIR:-$desktop_dir}" +fi +mkdir -p "$desktop_dir" "$HOME/.local/share/applications" + +cat > "$HOME/.local/share/applications/retroarch-source.desktop" < Date: Tue, 27 Oct 2026 11:09:35 +0800 Subject: [PATCH 2/3] docs: verify CM5 menu assets and restore official icon and mouse --- docs/guides/armsom-cm5.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/guides/armsom-cm5.md b/docs/guides/armsom-cm5.md index 9ac33461c8..cb582e7b08 100644 --- a/docs/guides/armsom-cm5.md +++ b/docs/guides/armsom-cm5.md @@ -15,8 +15,14 @@ sudo apt-get -o Dpkg::Use-Pty=0 install -y --no-install-recommends \ libasound2-dev libudev-dev libx11-dev libxext-dev libxinerama-dev \ libxrandr-dev libxxf86vm-dev libfreetype6-dev zlib1g-dev libssl-dev \ retroarch-assets libretro-core-info + +test -r /usr/share/libretro/assets/ozone/png/icons/pointer.png +test -r /usr/share/libretro/assets/ozone/regular.ttf +test -d /usr/share/libretro/info ``` +Wait for package installation to finish successfully before continuing. The checks above must succeed: the Ozone menu needs its icons, pointer texture, and font. Missing assets can produce blank icons or a square mouse pointer. + ## Download the source Use a new source directory. These commands select the exact upstream revision used for this test. @@ -81,10 +87,13 @@ input_pause_toggle = "p" input_exit_emulator = "escape" quit_press_twice = "true" menu_driver = "ozone" +menu_mouse_enable = "true" core_info_cache_enable = "false" config_save_on_exit = "false" assets_directory = "/usr/share/libretro/assets" libretro_info_path = "/usr/share/libretro/info" +libretro_directory = "$HOME/retroarch-source-validation/core-package/extracted/usr/lib/aarch64-linux-gnu/libretro" +rgui_browser_directory = "$HOME/retroarch-source-validation/content" savefile_directory = "$HOME/retroarch-source-validation/runtime/saves" savestate_directory = "$HOME/retroarch-source-validation/runtime/states" system_directory = "$HOME/retroarch-source-validation/runtime/system" @@ -187,8 +196,10 @@ fi retroarch_bin="$HOME/.local/retroarch-upstream/bin/retroarch" retroarch_config="$HOME/retroarch-source-validation/config/retroarch.cfg" +retroarch_icon="$HOME/.local/retroarch-upstream/share/pixmaps/com.libretro.RetroArch.svg" test -x "$retroarch_bin" test -r "$retroarch_config" +test -r "$retroarch_icon" desktop_dir="$HOME/Desktop" if command -v xdg-user-dir >/dev/null 2>&1; then @@ -206,7 +217,7 @@ Type=Application Name=RetroArch (Source Build) Comment=Open the RetroArch graphical menu Exec="$retroarch_bin" --config "$retroarch_config" --menu -Icon=applications-games +Icon=$retroarch_icon Terminal=false Categories=Game;Emulator; StartupNotify=false @@ -222,7 +233,7 @@ On the HDMI desktop, double-click **RetroArch (Source Build)**. If XFCE asks whe The serial console is used here to create the files, not to display the graphical interface. Launch the icon from the active XFCE desktop; do not run RetroArch as root to work around display or permission errors. -The launcher and recovery steps were tested on October 27, 2026, on the native Debian 12 XFCE image with `xdg-user-dir` absent. The desktop user was `armsom`; opening the menu and relaunching by double-clicking the icon were verified. +The launcher and recovery steps were tested on October 27, 2026, on the native Debian 12 XFCE image with `xdg-user-dir` absent. The desktop user was `armsom`; opening the menu and relaunching by double-clicking the icon were verified. After installing the menu assets and enabling mouse input, the official launcher icon, mouse pointer, mouse menu selection, and keyboard back navigation were also verified. ## Tested functionality From bde698a11b0701d852f849f79dde69e282b055d7 Mon Sep 17 00:00:00 2001 From: Donleon <2455653548@qq.com> Date: Tue, 27 Oct 2026 11:29:54 +0800 Subject: [PATCH 3/3] docs: add validated CM5 homebrew games and desktop launchers Add Falling, GBAtris and Snake desktop launchers, fixed-version downloads, ROM checksums, mGBA setup, source/license notices, and a keyboard reference. Hardware gameplay, HDMI audio, exit and desktop relaunch were verified on CM5. All 14 Bash blocks pass syntax checks; mkdocs build --strict passes. --- docs/guides/armsom-cm5.md | 163 +++++++++++++++++++++++++++++++++++++- 1 file changed, 162 insertions(+), 1 deletion(-) diff --git a/docs/guides/armsom-cm5.md b/docs/guides/armsom-cm5.md index cb582e7b08..6644cbddea 100644 --- a/docs/guides/armsom-cm5.md +++ b/docs/guides/armsom-cm5.md @@ -78,6 +78,8 @@ input_player1_left = "left" input_player1_right = "right" input_player1_a = "x" input_player1_b = "z" +input_player1_l = "q" +input_player1_r = "w" input_player1_start = "enter" input_player1_select = "rshift" input_menu_toggle = "f1" @@ -233,10 +235,169 @@ On the HDMI desktop, double-click **RetroArch (Source Build)**. If XFCE asks whe The serial console is used here to create the files, not to display the graphical interface. Launch the icon from the active XFCE desktop; do not run RetroArch as root to work around display or permission errors. -The launcher and recovery steps were tested on October 27, 2026, on the native Debian 12 XFCE image with `xdg-user-dir` absent. The desktop user was `armsom`; opening the menu and relaunching by double-clicking the icon were verified. After installing the menu assets and enabling mouse input, the official launcher icon, mouse pointer, mouse menu selection, and keyboard back navigation were also verified. +### Create a Falling game shortcut + +**RetroArch (Source Build)** opens the main menu because its command includes `--menu`. To start the test game directly, create a separate **Falling - NES Demo** launcher that specifies both the Nestopia core and `Falling.nes`. + +After completing the core and game download steps, run this block as the desktop user: + +```bash +( +set -eu +test "$(id -u)" -ne 0 +retroarch_bin="$HOME/.local/retroarch-upstream/bin/retroarch" +retroarch_config="$HOME/retroarch-source-validation/config/retroarch.cfg" +retroarch_icon="$HOME/.local/retroarch-upstream/share/pixmaps/com.libretro.RetroArch.svg" +core="$HOME/retroarch-source-validation/core-package/extracted/usr/lib/aarch64-linux-gnu/libretro/nestopia_libretro.so" +game="$HOME/retroarch-source-validation/content/Falling.nes" +test -x "$retroarch_bin" +test -r "$retroarch_config" +test -r "$retroarch_icon" +test -r "$core" +test -r "$game" + +desktop_dir="$HOME/Desktop" +if command -v xdg-user-dir >/dev/null 2>&1; then + desktop_dir="$(xdg-user-dir DESKTOP)" +elif [ -r "$HOME/.config/user-dirs.dirs" ]; then + . "$HOME/.config/user-dirs.dirs" + desktop_dir="${XDG_DESKTOP_DIR:-$desktop_dir}" +fi +mkdir -p "$desktop_dir" "$HOME/.local/share/applications" +launcher="$HOME/.local/share/applications/falling-source.desktop" + +cat > "$launcher" </dev/null 2>&1; then + desktop_dir="$(xdg-user-dir DESKTOP)" +elif [ -r "$HOME/.config/user-dirs.dirs" ]; then + . "$HOME/.config/user-dirs.dirs" + desktop_dir="${XDG_DESKTOP_DIR:-$desktop_dir}" +fi +mkdir -p "$desktop_dir" "$HOME/.local/share/applications" +retroarch_bin="$HOME/.local/retroarch-upstream/bin/retroarch" +retroarch_config="$HOME/retroarch-source-validation/config/retroarch.cfg" +retroarch_icon="$HOME/.local/retroarch-upstream/share/pixmaps/com.libretro.RetroArch.svg" +mgba_core="$HOME/retroarch-source-validation/core-package/mgba/extracted/usr/lib/aarch64-linux-gnu/libretro/mgba_libretro.so" +test -x "$retroarch_bin" +test -r "$retroarch_config" +test -r "$retroarch_icon" +test -r "$mgba_core" + +create_game_launcher() { + title="$1" + slug="$2" + game="$3" + test -r "$game" + launcher="$HOME/.local/share/applications/$slug-source.desktop" + cat > "$launcher" <