Porting to Arch R
Libraries, graphics APIs, GPU drivers, paths and launch environment for developers who build or adapt game ports for Arch R
This page is for people who build a port for Arch R or adapt an existing PortMaster port to it. It describes Arch R 3.1.0 on the RK3326 (R36S and clones, Mali-G31 GPU). Every path and variable here was read from the Arch R sources or checked on an R36S. Where something could not be checked, the page says so.
The same material comes as a skill for coding assistants, archr-ports-dev: install it and Claude Code (or another assistant that reads Agent Skills) can adapt a port, find why one fails or prepare one for PortMaster from these rules. See AI skills.
The platform in one table
| CPU | Rockchip RK3326, 4 × Cortex-A35, aarch64 |
| Userland | Arch Linux ARM, glibc 2.40, 64-bit in /usr/lib, 32-bit armhf in /usr/lib32 |
| 32-bit loader | /lib/ld-linux-armhf.so.3 → /usr/lib32/ld-linux-armhf.so.3 |
| GPU | Mali-G31 MC1 (Bifrost) |
| Display | sway (Wayland), WAYLAND_DISPLAY=wayland-1, XDG_RUNTIME_DIR=/var/run/0-runtime-dir |
| Screen | 640×480 on the R36S (DISPLAY_WIDTH/DISPLAY_HEIGHT from PortMaster) |
| Audio | PipeWire with pipewire-pulse; SDL_AUDIODRIVER=pulseaudio |
| User | everything, ports included, runs as root; HOME=/storage |
| Ports folder | /storage/roms/ports (/roms is a link to /storage/roms) |
/lib is a link to /usr/lib. The 32-bit side is found through /etc/ld.so.conf.d/arm-lib32.conf, which lists /usr/lib32. The library cache lives at /storage/.cache/ld.so.cache and is rebuilt at boot whenever the GPU driver changes.
Two GPU drivers
The user picks one in Settings › System › GPU driver, stored as gpu.driver in /storage/.config/system/configs/system.cfg. The change applies after a reboot. The default is libmali.
libmali (default) | panfrost | |
|---|---|---|
| Kernel module | mali_kbase | panfrost |
| User space | ARM blob libmali.so.1 (g24p0, Wayland + GBM build) | Mesa 26.2.7 |
| OpenGL ES | 1.1, 2.0, 3.x (the blob reports 3.2) | up to 3.1 |
| Desktop OpenGL | none (libGL.so is hidden) | 3.1 |
| Vulkan | none | 1.0 through PanVK |
| OpenCL | in libmali.so.1, see OpenCL | none |
| EGL / GBM | from libmali | from Mesa |
At boot, /usr/bin/gpudriver --start loads the module and puts the right libraries in place with bind mounts. Nothing in the file names changes, so a port links against the same names under both drivers.
What libmali does at boot
- Every file in
/usr/lib/maliand/usr/lib32/maliis bind-mounted over the file of the same name one folder up:libEGL.so.1,libGLESv1_CM.so.1,libGLESv2.so.2,libgbm.so.1,libwayland-egl.so.1(and their.solinks). These small libraries come from thelibmalipackage and forward tolibmali.so.1throughlibmali-hook.so.1. - The GLES-only SDL2 in
/usr/lib/glesonlyand/usr/lib32/glesonlyis mounted overlibSDL2-2.0.so.0.3200.10. That SDL2 was built without desktop OpenGL, soSDL_GL_*with a compatibility or core profile fails and an ES profile works. /dev/nullis mounted over/usr/lib/libGL.soand/usr/lib32/libGL.so, so nothing loads Mesa's GL by accident./dev/nullis mounted over/usr/share/vulkan/icd.d/panfrost_icd.*.json, so the Vulkan loader finds no driver.
What panfrost does at boot
None of the mounts above. Mesa's libEGL, libGLESv2, libgbm, libglvnd's libGL.so.1 and the PanVK ICD are visible in their normal places. The variable PAN_I_WANT_A_BROKEN_VULKAN_DRIVER=1 is exported to every process (see Vulkan).
When pacman updates a graphics package, its hooks (archr-gpu-bind unbind|bind and archr-sdl-bind unbind|bind) lift the mounts and put them back over the new files. A port never has to touch these mounts.
Where the libraries are
All paths are 64-bit first, 32-bit second.
| Library | File | libmali | panfrost |
|---|---|---|---|
| EGL | /usr/lib/libEGL.so.1, /usr/lib32/libEGL.so.1 | libmali (mounted) | libglvnd → libEGL_mesa.so.0 |
| GLES 2/3 | /usr/lib/libGLESv2.so.2, /usr/lib32/libGLESv2.so.2 | libmali (mounted) | libglvnd → Mesa |
| GLES 1 | /usr/lib/libGLESv1_CM.so.1, /usr/lib32/… | libmali (mounted) | libglvnd → Mesa |
| GBM | /usr/lib/libgbm.so.1, /usr/lib32/libgbm.so.1 | libmali (mounted) | Mesa |
| wayland-egl | /usr/lib/libwayland-egl.so.1, /usr/lib32/… | libmali (mounted) | wayland |
| Desktop GL | /usr/lib/libGL.so.1, libOpenGL.so.0, libGLX.so.0; same in /usr/lib32 | libGL.so is /dev/null | libglvnd → Mesa |
| Mesa DRI | /usr/lib/dri/panfrost_dri.so, /usr/lib32/dri/panfrost_dri.so | unused | used |
| Vulkan loader | /usr/lib/libvulkan.so.1 (64-bit only) | present, no device | present |
| Vulkan ICD | /usr/share/vulkan/icd.d/panfrost_icd.*.json → /usr/lib/libvulkan_panfrost.so | masked with /dev/null | active |
| libmali itself | /usr/lib/libmali.so.1, /usr/lib32/libmali.so.1 | used | present, unusable (no /dev/mali0) |
| SDL2 | /usr/lib/libSDL2-2.0.so.0, /usr/lib32/libSDL2-2.0.so.0 (2.32.10) | GLES-only build (mounted) | full build |
There is no 32-bit Vulkan: /usr/lib32 has no libvulkan.so.1. A Vulkan port has to be 64-bit.
Only the 64-bit full SDL2 (/usr/lib/libSDL2-2.0.so.0 under panfrost) is built with Vulkan support. SDL_Vulkan_LoadLibrary fails on the GLES-only build and on the 32-bit builds.
Debian-style paths
Ports made for ArkOS or dArkOS often name Debian's multiarch folders. Arch R has them as links:
/usr/lib/aarch64-linux-gnu -> . (that is, /usr/lib)
/usr/lib/arm-linux-gnueabihf -> ../lib32/lib/aarch64-linux-gnu and /lib/arm-linux-gnueabihf work too, since /lib is /usr/lib. LD_PRELOAD=/usr/lib/arm-linux-gnueabihf/libSDL2-2.0.so.0 resolves to the 32-bit SDL2.
Older Debian libraries
/usr/lib/compat holds Debian 11 era sonames that ports expect and Arch no longer ships (libavcodec.so.58, libcrypto.so.1.1, libjpeg.so.62, libx264.so.160, libx265.so.192 and others). PortMaster's get_controls sets LD_LIBRARY_PATH=/usr/lib/compat/ (the clibs variable). List the folder on the console to see the full set; a port that needs a library not there should bundle it in its own libs.aarch64 or libs.armhf folder.
OpenGL, OpenGL ES and gl4es
Write for OpenGL ES 2.0 or 3.0 through EGL. That runs on both drivers without asking the user for anything.
Desktop OpenGL only exists on panfrost (Mesa reports 3.1 Mesa, compatibility and core). On libmali, libGL.so is /dev/null, so a program linked against libGL.so.1 fails to start, or gets no context from SDL.
Ports that need desktop GL usually ship gl4es, which translates GL 2.1 to GLES 2. PortMaster ports source a libgl_<CFW>.txt file for its settings, and Arch R provides libgl_ArchR.txt in /roms/ports/PortMaster/:
export LIBGL_ES=2
export LIBGL_GL=21
if [ -d /sys/module/panfrost ]; then
export LIBGL_FB=3 # PBuffer: the GBM backend draws nothing under sway on panfrost
else
export LIBGL_FB=4 # GBM
fi
[ -e /dev/dri/card0 ] || export LIBGL_FB=2
# then prepends $PWD/gl4es[.$DEVICE_ARCH] and $PWD/libs[.$DEVICE_ARCH] to LD_LIBRARY_PATHSource it from the port's folder, after cd "$GAMEDIR", because it uses $PWD.
mod_ArchR.txt also exports LIBGL_DRIVERS_PATH=/usr/lib32/dri:/usr/lib/dri for every port.
Mesa settings exported to every process by /etc/profile.d/041-panfrost: MESA_NO_ERROR=1 (no GL error checking), MESA_SHADER_CACHE_DIR=/var/cache/mesa, MESA_SHADER_CACHE_MAX_SIZE=128MB. A port that depends on glGetError under panfrost has to unset MESA_NO_ERROR itself.
Window system: Wayland, not KMS
sway owns the display the whole time a game runs. A port must open a Wayland window (or go through Xwayland if the port needs X11; not checked on this release). Direct KMS/DRM output cannot get the screen.
SDL_VIDEODRIVER=waylandis exported globally.- Arch R's SDL2 is patched so that
SDL_VIDEODRIVER=kmsdrm, set by many ArkOS ports, falls back to the normal order (Wayland first) whenWAYLAND_DISPLAYis set or KMSDRM fails to start.ARCHR_SDL_KMSDRM=1keeps KMSDRM forced, which only makes sense outside sway. - EGL on Wayland works on both drivers: libmali is the
wayland-gbmbuild and exportswl_egl_window_create. - The window is made fullscreen by
pm_platform_helperinmod_ArchR.txt, which callssway_fullscreenon the program's name (swayapp_id). Callpm_platform_helper "$GAMEDIR/<binary>"before starting the game, as PortMaster ports already do, or set anapp_idthat matches the binary name. /dev/dri/card0,/dev/dri/card1and/dev/dri/renderD128exist on panfrost. On libmali the GPU node is/dev/mali0.
MALI_WAYLAND_AFBC=0 and MALI_SCHED_RT_THREAD_PRIORITY=95 are exported for libmali.
Vulkan
Vulkan is available when the GPU driver is panfrost. It is Mesa's PanVK on the Mali-G31.
| Loader | /usr/lib/libvulkan.so.1 (vulkan-loader 1.4.354), 64-bit only |
| ICD | /usr/share/vulkan/icd.d/panfrost_icd.armv8-a+crc+fp+simd.json → /usr/lib/libvulkan_panfrost.so |
| Device | Mali-G31 MC1, driverName = panvk, driverID = DRIVER_ID_MESA_PANVK, vendor 0x13b5 |
| API version | 1.0 (apiVersion = 1.0.354); instance version 1.4.354 |
| Conformance | none (conformanceVersion = 0.0.0.0) |
| WSI | VK_KHR_wayland_surface, VK_KHR_display, VK_KHR_xcb_surface, VK_KHR_xlib_surface |
| Implicit layer | VK_LAYER_MANGOHUD_overlay_aarch64 |
PanVK only reports 1.1 and later on Mali v10 GPUs and newer; the G31 is v7 and stays at 1.0. Check for every extension you use; do not assume what Vulkan 1.1 promises. Tested on an R36S: vkcube, vkmark (scenes with textures had GPU job faults), PPSSPP and RetroArch on the Vulkan renderer.
The variable
On Mali v7, PanVK refuses to create a device unless PAN_I_WANT_A_BROKEN_VULKAN_DRIVER=1 is set. Without it the loader prints panvk is not well-tested on v7 and vkEnumeratePhysicalDevices returns no GPU. /etc/profile.d/041-panfrost exports it whenever /sys/module/panfrost exists, so with panfrost active every process started through /etc/profile has it, ports included. Do not set it yourself; if it is missing, Vulkan is not supposed to be used.
MESA_VK_VERSION_OVERRIDE makes PanVK report a higher API version. The features behind that version are not there; use it only for experiments.
With libmali
There is no Vulkan device. The loader is installed but the panfrost ICD is /dev/null, and libmali for the G31 has no Vulkan driver. vkCreateInstance works and vkEnumeratePhysicalDevices returns zero devices.
Detecting it and falling back
In code, follow the usual order and treat every failure as "no Vulkan":
dlopen("libvulkan.so.1")(orSDL_Vulkan_LoadLibrary(NULL)).vkCreateInstancewithVK_KHR_surfaceandVK_KHR_wayland_surface.vkEnumeratePhysicalDevicesreturns at least one device.- The device supports the extensions and formats you need.
If any step fails, start the GLES renderer. A port that only has a Vulkan renderer should declare that it needs panfrost (next section) so the user gets the switch offer instead of a crash.
In a launch script:
if [ -d /sys/module/panfrost ] && vulkaninfo --summary >/dev/null 2>&1; then
RENDERER=vulkan
else
RENDERER=gles
fivulkaninfo exits 0 when a device is found and 1 when none is (checked on the R36S with and without the variable).
Emulators
Emulators run on GLES by default; Settings › Games › Renderer picks GLES or Vulkan per system (RetroArch video_driver = vulkan, the Vulkan backend of PPSSPP and Flycast standalone). On libmali a Vulkan choice falls back to GL. See GPU driver. This setting is for emulators only; a port chooses its own renderer as above.
OpenCL
What is on the system:
/etc/OpenCL/vendors/mali.icd(from thelibmalipackage) nameslibMaliOpenCL.so.1.libMaliOpenCL.so.1is only in/usr/lib/maliand/usr/lib32/mali. Unlike the GL libraries, there is no file of that name in/usr/lib, so the boot mounts do not put it on the library path.libmali.so.1exports the OpenCL API itself (clGetPlatformIDs,clIcdGetPlatformIDsKHRand 152 othercl*symbols).- There is no ICD loader (
libOpenCL.so.1) on the system, and Mesa is built without Rusticl.
So OpenCL is only possible on libmali, and only by linking libmali.so.1 directly or by dlopen("/usr/lib/mali/libMaliOpenCL.so.1"). A port that wants an ICD loader must bundle its own libOpenCL.so.1; the loader will read mali.icd and then needs /usr/lib/mali in LD_LIBRARY_PATH to find libMaliOpenCL.so.1. On panfrost there is no OpenCL at all (/dev/mali0 does not exist).
Arch R has not tested an OpenCL program on the R36S. Treat this section as the layout of the files, not as a statement that OpenCL kernels run.
Telling the system your port needs panfrost
When a port can only run on panfrost (desktop GL without gl4es, Vulkan only, or a crash inside libmali), declare it. archr-launcher checks this when the user starts the port from the Ports list and the configured driver is libmali. Instead of launching, it shows:
<title>needs the panfrost driver This game uses OpenGL, which the current GPU driver (libmali) does not have. The switch applies to the whole system and the console restarts. To go back: Settings › System › GPU driver.
A (Switch and restart) sets gpu.driver=panfrost through gpudriver and reboots. B cancels and the port does not start. On panfrost the port starts normally.
The check only works for a script with the PortMaster header in its first 10 lines:
#!/bin/bash
# PORTMASTER: mygame.zip, My Game.shThe name before the comma (mygame.zip) is the package name. The port needs panfrost when either is true:
-
Its
port.jsonsays so (preferred). The launcher reads every<ports folder>/*/port.jsonnext to the script, takes the one whose"name"equals the package name (case does not matter), and looks for"opengl"inattr.reqs(case does not matter):{ "version": 4, "name": "mygame.zip", "items": ["My Game.sh", "mygame/"], "attr": { "title": "My Game", "reqs": ["opengl"] } }This is the PortMaster field, so the same
port.jsonworks on other systems. Putport.jsonin the port's folder (/storage/roms/ports/mygame/port.json), as PortMaster installs it. -
The package is on Arch R's list,
/usr/share/archr/portmaster/panfrost.txt: one package name per line,#starts a comment, case does not matter. The file belongs to the system package (source:projects/ArchR/packages/apps/portmaster/share/panfrost.txtin the distribution repository) and an update replaces it, so do not edit it on the console. It is for catalogue ports that fail on libmali but whoseport.jsondoes not say so. To add one, open an issue or a pull request on archr-linux/Arch-R.
The question is never asked when the port is started some other way (from the PortMaster app, from a script, over SSH). A port that needs panfrost should still check the driver itself and print a clear message.
The dialog says "OpenGL" for every port on the list, Vulkan-only ones included.
Detecting the active driver
Use the kernel state, which reflects the running boot:
if [ -d /sys/module/panfrost ]; then
GPU=panfrost
elif [ -e /dev/mali0 ]; then
GPU=libmali
else
GPU=none # neither bound: software rendering
fi/sys/bus/platform/drivers/panfrost/ff400000.gpu also exists when panfrost is bound.
gpudriver with no argument prints the configured driver (gpu.driver). It can differ from the running one: after a switch that waits for a reboot, or for one boot after a failed probe. Never call gpudriver panfrost or gpudriver libmali from a port; that changes the user's setting for the next boot.
In a program, the GL string tells you too: GL_RENDERER is Mali-G31 MC1 (Panfrost) on Mesa.
Launch environment
Ports are started by runemu.sh as /usr/bin/bash "<script>", pinned to the CPU cores chosen for the game, with output in /var/log/exec.log. Before running the script it:
- makes sure PortMaster's files in
/roms/ports/PortMastermatch the system's (control.txt,mod_ArchR.txt,libgl_ArchR.txt) and refreshes them if not; - sets the execute bit on the script, and on ELF files and
#!scripts inside the port's folder (up to 4 levels) and inPortMaster/that lack it; - checks the runtimes in
port.jsonattr.runtime(orruntime="…"in the script), downloads a missing one if there is network, and otherwise refuses to start with a message; - removes stale bind mounts left by ports that were deleted.
Accepted extensions in the Ports list: .sh and .appimage.
Variables from PortMaster's control.txt (values on an R36S)
| Variable | Value |
|---|---|
controlfolder | /roms/ports/PortMaster |
directory | roms (run/archr/roms2 when the port sits on the second card) |
CFW_NAME | ArchR (from NAME in /etc/os-release) |
CFW_VERSION | the build date, such as 20261105 |
DEVICE_NAME | R36S |
DEVICE_CPU | RK3326 |
DEVICE_ARCH | aarch64 |
DEVICE_HAS_ARMHF, DEVICE_HAS_AARCH64 | Y |
DEVICE_HAS_X86, DEVICE_HAS_X86_64 | N |
DEVICE_RAM | 1 |
DISPLAY_WIDTH × DISPLAY_HEIGHT | 640 × 480 |
ASPECT_X:ASPECT_Y | 4:3 |
ANALOG_STICKS | 2 |
LOWRES | Y |
param_device | ogs |
ESUDO | empty (everything already runs as root) |
GPTOKEYB | /roms/ports/PortMaster/gptokeyb -1 |
GPTOKEYB2 | env LD_PRELOAD=/roms/ports/PortMaster/libinterpose.aarch64.so /roms/ports/PortMaster/gptokeyb2 -1 |
clibs | /usr/lib/compat/ |
SDLDBUSERFILE | /storage/.config/SDL-GameControllerDB/gamecontrollerdb.txt |
GODOT_OPTS | --resolution 640x480 -f (GODOT2_OPTS: -r 640x480 -f) |
get_controls writes the pad mapping to /tmp/gamecontrollerdb.txt, exports SDL_GAMECONTROLLERCONFIG_FILE pointing there, fills sdl_controllerconfig with its contents and sets LD_LIBRARY_PATH=/usr/lib/compat/.
Variables from /etc/profile (every process)
HW_DEVICE=RK3326, QUIRK_DEVICE (the device tree model, Game Console R36S here), UI_SERVICE, WAYLAND_DISPLAY, XDG_RUNTIME_DIR, SDL_VIDEODRIVER=wayland, SDL_AUDIODRIVER=pulseaudio, DISPLAY=:0.0, the Mesa variables above and, on panfrost, PAN_I_WANT_A_BROKEN_VULKAN_DRIVER=1. PAN_MESA_DEBUG=forcepack is set only when the user turns on the forcepack option for that system or game.
Standard script start
#!/bin/bash
# PORTMASTER: mygame.zip, My Game.sh
XDG_DATA_HOME=${XDG_DATA_HOME:-$HOME/.local/share}
if [ -d "/opt/system/Tools/PortMaster/" ]; then
controlfolder="/opt/system/Tools/PortMaster"
elif [ -d "/opt/tools/PortMaster/" ]; then
controlfolder="/opt/tools/PortMaster"
elif [ -d "$XDG_DATA_HOME/PortMaster/" ]; then
controlfolder="$XDG_DATA_HOME/PortMaster"
else
controlfolder="/roms/ports/PortMaster"
fi
source $controlfolder/control.txt
[ -f "${controlfolder}/mod_${CFW_NAME}.txt" ] && source "${controlfolder}/mod_${CFW_NAME}.txt"
get_controls
GAMEDIR="/$directory/ports/mygame"
cd "$GAMEDIR"On Arch R, controlfolder ends up as /roms/ports/PortMaster and mod_ArchR.txt is sourced.
32-bit ports
32-bit armhf binaries run natively with the libraries in /usr/lib32 (Mesa and libmali both have 32-bit builds, and the mounts cover /usr/lib32 too). Set PORT_32BIT="Y" before sourcing mod_ArchR.txt, which then exports SPA_PLUGIN_DIR=/usr/lib32/spa-0.2 and PIPEWIRE_MODULE_DIR=/usr/lib32/pipewire-0.3/ so 32-bit PipeWire clients find their plugins. 32-bit libpulse.so.0, libasound.so.2 and libpipewire-0.3.so.0 are installed. There is no 32-bit Vulkan.
Audio
PipeWire runs with pipewire-pulse and WirePlumber. The PulseAudio socket is /var/run/0-runtime-dir/pulse/native. SDL uses the PulseAudio backend (SDL_AUDIODRIVER=pulseaudio). ALSA programs see one card, rk817int. Use SDL or PulseAudio; opening the ALSA device directly competes with PipeWire for it.
Input
The built-in pad is r36s_Gamepad (driver odroidgo3-joypad, /dev/input/by-path/platform-odroidgo3-joypad-event-joystick). Use the SDL GameController API with the mapping that get_controls prepares. For a game that only reads keyboard and mouse, run $GPTOKEYB "<binary>" -c "<file>.gptk" & (or $GPTOKEYB2); /dev/uinput is writable by everyone. oga_controls from older ports is in PortMaster/ as well, and control.txt maps param_device to ogs on the R36S so it finds the right joypad path.
Files and saves
| Path | Use |
|---|---|
/storage/roms/ports/<Name>.sh | the launcher script shown in the Ports list |
/storage/roms/ports/<name>/ | the port's files (GAMEDIR), including port.json |
/storage/roms/ports/PortMaster/ | PortMaster, control.txt, mod_ArchR.txt, libgl_ArchR.txt, runtimes in libs/ |
/storage/.config/PortMaster/ | the copies PortMaster's files are refreshed from |
/storage ($HOME) | ~/.config, ~/.local/share and dot folders the game writes |
/var/log/exec.log | the output of the last launch |
/storage/.config/gpudriver.log | what the driver switch did at boot |
/storage is ext4, so permissions and symbolic links work. Keep saves inside GAMEDIR (PortMaster's bind_directories does this) so they go with the port when it is copied or deleted.
Packaging for PortMaster
Follow PortMaster's own packaging rules; Arch R needs nothing extra beyond them:
- the script with the
# PORTMASTER:header and the standard start above; - the port folder with
port.json, fillingattr.reqs("opengl"when it needs panfrost),attr.arch(aarch64,armhf) andattr.runtime; - libraries the system does not have in
libs.aarch64/libs.armhf, and gl4es ingl4es.aarch64/gl4es.armhfwhen used; pm_platform_helperbefore the game starts,pm_finishafter it ends.
Do not bundle libEGL, libGLES*, libgbm, libGL, libwayland-egl, libvulkan or an ICD JSON. They have to be the system's, or the program talks to the wrong driver.
Test checklist on the console
Over SSH (root, password archr):
cat /etc/os-releaseandgpudriver;ls -d /sys/module/panfrost /dev/mali0to see which driver is running.file <binary>, thenldd <binary> | grep "not found"for a 64-bit binary.lddanswersnot a dynamic executablefor a 32-bit one; list its libraries withreadelf -d <binary> | grep NEEDEDand look for each in/usr/lib32and in the port'slibs.armhf.- Start the port from the Ports list, not from the shell, so
runemu.shand the panfrost check run. Read/var/log/exec.log. - With libmali: does it start, or does the panfrost question appear when it should?
- With panfrost: same test. If it uses Vulkan,
vulkaninfo --summarymust listMali-G31 MC1. - Controls, sound, exit back to the launcher, a second start (saves kept).
- Copy the port from a PC over Samba once, to check it does not depend on permissions the copy loses.
Switching drivers means a reboot each time: Settings › System › GPU driver.
Common problems
| Symptom | Cause and fix |
|---|---|
Permission denied on the binary | the execute bit was lost in a copy. runemu.sh restores it for ELF and #! files when started from the Ports list; from the shell, chmod +x it |
libGL.so.1: cannot open shared object file, or SDL cannot create a GL context | libmali has no desktop GL. Use GLES, bundle gl4es, or declare panfrost |
kmsdrm not available | sway holds the display. Remove SDL_VIDEODRIVER=kmsdrm; Arch R's SDL2 already falls back to Wayland |
vkEnumeratePhysicalDevices returns no GPU | the driver is libmali, or PAN_I_WANT_A_BROKEN_VULKAN_DRIVER was unset. Fall back to GLES |
a 32-bit program cannot find libvulkan.so.1 | there is no 32-bit Vulkan |
a library under /usr/lib/aarch64-linux-gnu/ or /usr/lib/arm-linux-gnueabihf/ is missing | the folders exist as links; the library itself is missing. Bundle it or check /usr/lib/compat |
an old soname (libcrypto.so.1.1, libavcodec.so.58) is missing | call get_controls (it sets LD_LIBRARY_PATH to /usr/lib/compat), or bundle it |
| black screen with gl4es on panfrost | use libgl_ArchR.txt, which sets LIBGL_FB=3 on panfrost |
| the window is not fullscreen | call pm_platform_helper with the binary path, or match app_id to the binary name |
| the game writes nowhere | HOME is /storage; check the port's binds in /proc/self/mountinfo |
See also GPU driver and PortMaster.
Create modules
Reference for archr-launcher modules (API 2 to 4) - execution model, module.toml, permissions, extension points, JSON-RPC protocol, Module store and two examples.
AI skills
Install the ArchR skills so Claude Code or another coding assistant can build themes, modules and game ports for Arch R from its real rules.