Native Termux/Android port of mango 0.18.5, running inside Termux:X11 without PRoot. Qualcomm Adreno only. The session uses a private KGSL Mesa
.debstack: use at your own risk and back up your data first.
- 1. Overview
- 2. Requirements
- 3. Build
- 4. Quick Start
- 5. Launcher and Environment
- 6. Configuration
- 7. Rendering and GPU
- 8. Native Noctalia
- 9. Integrations and Helper Scripts
- 10. Troubleshooting
- 11. Documentation
Mango is a Wayland compositor. This repository is its native Termux/Android port, based on wlroots 0.20. It is a regular Termux program, not a PRoot wrapper.
Architecture:
- Termux:X11 owns the Android surface and display.
- Mango is an X11 client of Termux:X11, uses the wlroots X11 backend, and creates a nested Wayland session.
- The default compositor path is Mesa Zink on Freedreno Vulkan (Turnip).
- Session clients default to the private Freedreno/KGSL Mesa 27 stack.
- Alternative paths are Android EGL/AHardwareBuffer (
ahb) and software rendering (pixman). - Nested Xwayland is created for X11 applications and normally uses display
:1.
Limitations:
- Adreno only. MediaTek, Exynos, Tensor and other SoCs are unsupported.
- Termux:X11 has no DRI3, so AHB frames are copied through SHM. Expect copy overhead.
- The default Xwayland server is a stable no-glamor server with indirect GLX, not a DRI3 server.
- High
vkmarknumbers measure GPU submission throughput, not display refresh. - The private KGSL Mesa stack comes from pinned third-party
.debpackages and is installed outside the stock Termux Mesa tree.
- Android arm64 device with a Qualcomm Adreno GPU.
- Termux, the Termux:X11 app, and the
termux-x11-nightlypackage. - No PRoot, systemd, udev, libinput, or DRM/KMS is required.
- Bundled
scenefx0.5 sources are pre-patched; scenefx is not available as a Termux package. - The
wlroots0.20 package is required. - Private KGSL Mesa 27 is optional, but required for hardware GL in session clients.
Install the build dependencies:
pkg install x11-repo
pkg update
pkg install termux-x11-nightly
pkg install clang pkg-config ninja patchelf git python-pip \
wlroots libwayland libwayland-protocols libxkbcommon libpixman \
libdrm libxcb xcb-util-wm xcb-util-renderutil xwayland \
libglvnd-dev mesa mesa-dev mesa-vulkan-icd-freedreno \
littlecms vulkan-loader pcre2 pango cjson libandroid-wordexp \
dpkg curl
python -m pip install mesonmesa-dev provides gbm.h; missing it is a common build error.
The supported path is ./build-termux.sh. The script:
- checks native tools and pkg-config dependencies;
- applies or reverts the bundled
scenefxpatch fromtermux-compat/scenefx-termux.patch; - builds scenefx and mango as release with
-O3; - installs into
$PREFIX; - creates
$PREFIX/lib/mango-termux/with the AHB binary and privatelibwlroots-0.20.so/libscenefx-0.5.so, patched to Android EGL/GLES; - creates
~/.config/mango/config.confandconfig.tomlonly if absent, enabling visible effects for new configs; - installs the private Freedreno/KGSL Mesa 27 stack when
/dev/kgsl-3d0exists; - runs
mango-integrate, installs the Firefox wrapper, and installs the native Noctalia launcher when a usable rootfs is found.
Build-time variables:
PREFIX— Termux prefix; default/data/data/com.termux/files/usr.SCENEFX_DIR— alternative scenefx source tree.MANGO_SKIP_KGSL=1— skip the private Mesa 27 stack.MANGO_SKIP_INTEGRATIONS=1— skipmango-integrate.MANGO_SKIP_FIREFOX_FIX=1— skip the Firefox WebGL wrapper.
./build-termux.sh
MANGO_SKIP_KGSL=1 ./build-termux.sh
MANGO_SKIP_INTEGRATIONS=1 ./build-termux.sh
MANGO_SKIP_FIREFOX_FIX=1 ./build-termux.shVerify the installation:
mango -vreports version 0.18.5.- Installed commands include
mango,mango-termux,mango-x11-check,mango-integrate,mango-noctalia,noctalia-exec,noctalia-terminal,mango-firefox, andmango-gpu-run. - After source changes, run
./build-termux.shagain and restart the session.
Open the Termux:X11 app before starting Mango. Start the launcher from Termux with mango-termux.
The first run creates configs and may install the KGSL stack and integrations. Existing config files are never overwritten by the build; visible effects are enabled only in newly created configs.
mango-termux
mango-termux --restart
MANGO_TERMUX_RENDERER=ahb mango-termux
MANGO_TERMUX_RENDERER=pixman mango-termuxIf the session does not appear, check the Termux:X11 app and the launcher log at $PREFIX/tmp/termux-x11.log.
mango-termux is the installed copy of run-mango.sh. It:
- sets
PREFIX,TMPDIR,XDG_RUNTIME_DIR, a nativeSHELL, andTERMINAL; - exports native XKB defaults:
XKB_CONFIG_ROOT=$PREFIX/share/X11/xkb,XKB_DEFAULT_LAYOUT=us,ru,XKB_DEFAULT_OPTIONS=grp:win_space_toggle,XKB_DEFAULT_RULES=evdev, andXKB_DEFAULT_MODEL=pc105; - writes
$PREFIX/tmp/mango-session.envfor Noctalia children; - removes stale
wayland-*sockets and locks; - starts or reuses Termux:X11;
- configures the stable Xwayland wrapper;
- selects the renderer and binary;
- runs
mango-integrateunless skipped; - reuses a running Mango instance through
MANGO_INSTANCE_SIGNATUREunless--restartis used.
| Variable | Default | Purpose |
|---|---|---|
MANGO_BACKEND |
x11 |
x11, wayland, or headless |
MANGO_X11_DISPLAY |
$DISPLAY or :0 |
Termux:X11 display |
MANGO_BIN |
auto | Override the Mango binary |
MANGO_TERMUX_RENDERER |
turnip |
turnip, ahb, or pixman |
MANGO_TERMUX_GPU |
auto | Compatibility alias: 1/ahb, 0/pixman, turnip/zink |
MANGO_RESTART |
0 |
Stop a running Mango before starting |
MANGO_XWAYLAND_GLAMOR |
0 |
1 opts into the DRI3/glamor Xwayland server |
WLR_XWAYLAND |
auto | Override the Xwayland binary |
XDG_RUNTIME_DIR |
$PREFIX/tmp |
Wayland/X11 runtime directory |
NOCTALIA_ROOTFS |
auto | Rootfs used by the native Noctalia installer |
TERMINAL and the XKB_* defaults are set automatically; override them only when necessary.
MANGO_X11_DISPLAY=:1 mango-termux
MANGO_TERMUX_RENDERER=ahb mango-termux
MANGO_XWAYLAND_GLAMOR=1 mango-termux
WLR_XWAYLAND=/path/to/Xwayland mango-termux
mango-termux --restart -s footExtra arguments are passed to Mango itself.
Mango searches for a config in this order:
$HOME/.config/mango/config.conf$HOME/.config/mango/config.toml$PREFIX/etc/mango/config.conf$PREFIX/etc/mango/config.toml
config.conf and config.toml are alternative formats; config.conf is the installed default on Termux. Modular configs are supported with source=./file.conf; common split files are binds.conf, env.conf, input.conf, mics.conf, monitors.conf, windows.conf, animations.conf, layouts.conf, and tags.conf.
Reload the shipped default with Super+R. User configs may remap it. Enable visible effects with:
blur=1
blur_layer=1
shadows = 1
layer_shadows = 1
border_radius=12Effects require the GPU path (mango-termux), not software pixman.
Default keybindings from the shipped assets/config.conf:
Super+R— reload config.Super+M— quit Mango.Alt+Q— close focused window.Alt+Return— launchfoot.Alt+Space— launchrofi -show drun.Super+Tab— focus next window.Alt+Tab— toggle jump.Alt+F— toggle fullscreen.
User configs and binds.conf may override these defaults. Validate or migrate a config with:
mango -p
mango -p -c "$HOME/.config/mango/config.conf"
./termux-compat/fix-mango-config.sh --dry-run
./termux-compat/fix-mango-config.shfix-mango-config.sh accepts -n/--dry-run, --no-validate, an optional positional CONFIG_DIR, and -h/--help. It creates timestamped backups.
Default turnip mode:
- Mango itself renders through Mesa Zink on Freedreno Vulkan/Turnip.
- Child clients get the native KGSL Mesa 27 environment, not global Zink.
- The private root is
$PREFIX/opt/mesa-kgslwhenlib/dri/kgsl_dri.soexists; otherwise stock$PREFIXis used if it has the KGSL driver. - The launcher sets
LD_LIBRARY_PATH,LIBGL_DRIVERS_PATH,GBM_BACKENDS_PATH,MESA_LOADER_DRIVER_OVERRIDE=kgsl,GALLIUM_DRIVER=kgsl,__EGL_VENDOR_LIBRARY_FILENAMES,VK_DRIVER_FILES, andVK_ICD_FILENAMESas applicable. - If KGSL is missing, the launcher warns and clients may fall back to llvmpipe.
ahb mode uses $PREFIX/lib/mango-termux/mango with Android system EGL/GLES and AHardwareBuffer support. It has no DRI3 and uses the bundled private libwlroots-0.20.so and libscenefx-0.5.so. Select it with MANGO_TERMUX_RENDERER=ahb or MANGO_TERMUX_GPU=1.
pixman mode is software rendering with the normal Mesa binary; select it with MANGO_TERMUX_RENDERER=pixman or MANGO_TERMUX_GPU=0.
The private KGSL stack is installed by termux-compat/install-freedreno-kgsl.sh. It uses the pinned lfdevs release freedreno-27.0.0-devel-20261025-r2, verifies SHA-256, backs up an old tree as mesa-kgsl.bak.<timestamp>, and does not replace stock Termux Mesa.
AHB caveat: Termux:X11 presents through SHM copies, so AHB removes GPU and driver limits but does not eliminate the copy to the Android surface.
Xwayland:
- The default wrapper is
$PREFIX/tmp/mango-xwayland. It setsXWAYLAND_NO_GLAMOR=1andLIBGL_DRI3_DISABLE=1, then execsXwayland +iglx -shm. MANGO_XWAYLAND_GLAMOR=1opts into DRI3/glamor and clears those limits.WLR_XWAYLANDoverrides the real server.- X11 apps usually see
DISPLAY=:1; the outer Termux:X11 root is:0.
Noctalia 5.4.1 runs natively in Termux with the Termux glibc loader. The Arch rootfs supplies the Noctalia binary, Qt/Noctalia resources, and libraries. PRoot is used only for optional rootfs bootstrap and package setup, never at runtime.
Rootfs discovery order:
--rootfs PATHNOCTALIA_ROOTFS$PREFIX/var/lib/proot-distro/installed-rootfs/*$PREFIX/var/lib/proot-distro/containers/*/rootfs
The installer bootstraps archlinuxarm and Noctalia when no usable rootfs exists (network required); --no-bootstrap makes that an error. It:
- builds a private runtime under
$PREFIX/libexec/mango-termux; - copies required rootfs libraries into
rootfs-libs; - uses
$PREFIX/glibc/lib/ld-linux-aarch64.so.1; - creates a patched fallback cache with
patchelfwhen possible; - writes
runtime.env; - installs the
noctaliaandmango-noctalialaunchers; - installs
noctalia-execandnoctalia-terminal; - clears foreign IM/XKB variables and restores native XKB paths for children.
./install-noctalia-termux.sh
./install-noctalia-termux.sh --rootfs /path/to/rootfs
./install-noctalia-termux.sh --check
./install-noctalia-termux.sh --force --no-integrateInstaller flags: --rootfs PATH, --force, --check, --no-integrate, --bootstrap-rootfs, --no-bootstrap, --quiet, and -h/--help. --check is read-only; --force rebuilds the private runtime.
noctalia-exec rebuilds a clean native Termux child environment. It keeps the Wayland/X11 socket, D-Bus, XDG runtime, cursor, and KGSL/Turnip overrides; drops rootfs EGL/Mesa paths and inherited GTK_IM_MODULE, QT_IM_MODULE, SDL_IM_MODULE, GLFW_IM_MODULE, XMODIFIERS, INPUT_METHOD, and XKB_*; and resolves TERMINAL to an installed terminal.
noctalia-terminal is used because Noctalia runInTerminal calls $TERMINAL directly. It routes through noctalia-exec and prefers Wayland-native foot, then kitty, then ghostty.
Noctalia settings for this port:
launch_apps_custom_command = "noctalia-exec $CMD";reserve_space = truefor the top and bottom bars so client titlebars are not drawn underneath them;- overlay launchers may take keyboard focus; top and bottom layer bars must not steal focus from clients.
After changes, run mango-integrate --check and mango-termux --restart.
mango-integrate is idempotent and normally runs from the build or launcher. It restores terminal desktop entries, patches Firefox entries and the launcher, maintains native Noctalia launchers and env.conf (TERMINAL=noctalia-terminal), and creates safe shell defaults. Backups end in .mango-bak.
Flags: --quiet, --check, --no-firefox, --no-terminals, and -h/--help.
Helper scripts:
termux-compat/install-freedreno-kgsl.sh— private Mesa 27 KGSL stack.termux-compat/install-firefox-webgl.sh— Firefox WebGL wrapper; supports--check; can be skipped withMANGO_SKIP_FIREFOX_FIX=1.termux-compat/install-benchmark-fixes.sh— native glmark2 wrappers and glibc vkmark/assimp/Turnip fixes.termux-compat/build-arch-turnip.sh— Arch rootfs Turnip build for vkmark; optional, benchmark-only, and not part of the normal runtime.termux-compat/fix-mango-config.sh— config key migration.termux-compat/scenefx-termux.patch— bundled scenefx AHB/Termux patch.termux-compat/mango-*,termux-compat/noctalia-*— installed launchers and helpers.
mango-integrate
mango-integrate --check
mango-integrate --no-firefox --quiet
pkg install glmark2 libjpeg-turbo patchelf binutils
./termux-compat/install-benchmark-fixes.sh
./termux-compat/build-arch-turnip.sh
glmark2
glmark2-es2
grun --shell vkmarkThe benchmark group is optional. build-arch-turnip.sh is only for the Arch/PRoot benchmark environment and is not required for normal sessions.
echo "DISPLAY=$DISPLAY WAYLAND_DISPLAY=$WAYLAND_DISPLAY"
mango -v
mango-termux --restart -d
glxinfo -B 2>/dev/null | grep -E 'OpenGL renderer|OpenGL version'
vulkaninfo --summary 2>/dev/null | grep -E 'deviceName|driverName'Common issues:
gbm.hmissing:pkg install mesa-dev.- Termux:X11 not reachable: open the app, run
mango-x11-check, and read$PREFIX/tmp/termux-x11.log. - llvmpipe or no effects: install the KGSL stack, verify
$PREFIX/opt/mesa-kgsl/lib/dri/kgsl_dri.so, then runmango-termux --restart. - Nested Xwayland dies or an X11 GL client aborts: keep
MANGO_XWAYLAND_GLAMOR=0(default) and do not force glamor. - An X11 app opens on the outer
:0: make sure it inheritsDISPLAY=:1from the Mango session, and rebuild with Xwayland enabled. - Firefox WebGL fails: run
mango-integrate, thentermux-compat/install-firefox-webgl.sh, and restart the session. - Noctalia has no rootfs: use
--bootstrap-rootfsor--rootfs; validate with--check;patchelfis needed for the fallback binary. - Noctalia app shortcuts or IME are broken: launch through
noctalia-exec, keep the nativeXKB_CONFIG_ROOT, and do not inherit rootfs IM variables. vkmarkshows thousands of FPS: that is GPU submission throughput, not Termux:X11 refresh; judge smoothness visually.
Rebuild and restart with ./build-termux.sh && mango-termux --restart.
- README.md / README_ru.md — current bilingual overview.
- TERMUX_NOCTALIA.md / TERMUX_NOCTALIA_ru.md — detailed native Noctalia setup, runtime, verification, and troubleshooting guide; the installer remains canonical.
- docs/ — upstream MangoWM configuration documentation: bindings, configuration, visuals, window management, and patches.
- Upstream project: mangowm/mango
- License: see LICENSE.