bananarchy/AGENTS.md

Bananarchy Linux — Agent Guide (AGENTS.md)

1. Project Overview

Bananarchy is a keypad-first Linux distribution (armv7 / Alpine edge / postmarketOS v26.06 hardfork) for Qualcomm MSM8905 (Snapdragon 205) and MSM8909 (Snapdragon 210) smart feature phones with 240x320 QVGA non-touch SPI displays and 12-key T9 keypads (nokia-argon, nokia-beatles, nokia-tough, nokia-sparkler, nokia-leo).

It uses a pure X11 (Xlibre + sxmo-de-dwm) stack (no Wayland) optimized for < 2 ms UI wakeup latency and < 95 MB idle RAM on 512 MB devices.

2. Repository Layout

• src/sxmo-dwm/: Patched dwm window manager (240x320 vertical bstack layout, 24px Pango status bar, desktop "Menu"/"Names" softkey bar, C-level SW_LID slider and locked-key wake handling, live .Xresources reload, and .so plugin loader via dwm_plugin.h).
• src/sxmo-dmenu/: Zero-lag resident DWM menu plugin (dmenu.so) and /tmp/dwm_plugin_dmenu.sock client (dmenu / xdmenu), featuring built-in Sxmo menus (sys, applications, scripts, modem, config, power, audio, notifications, wm, timezone, games, st, nano, sthotkeys) and fcitx5-t9 XIM input.
• src/dwm-plugins/: Preloaded C++20 240x320 DWM plugins and shared headers:
  • theme.h: Unified .Xresources / ~/.xthemes/*.xth parser, proportional font sizing (theme.baseFontSize), automatic shade derivation, and live Xft/Pango theme reloading (PluginTheme).
  • phone_data.h: Shared X11 geometry (240x296 below the 24px bar), FIFO IPC (/tmp/dwm_plugin_<name>.fifo), softkey chord detection, Sxmo TSV contact/call/SMS parsers, and libjpeg/libpng helpers.
  • dialer_plugin.cpp (dialer.so / xdialer), calllog_plugin.cpp (calllog.so / xcalllog), callscreen_plugin.cpp (callscreen.so / xcallscreen), contacts_plugin.cpp (contacts.so / xcontacts), sms_plugin.cpp (sms.so / xsms), files_plugin.cpp (files.so / xfiles), camera_plugin.cpp (camera.so / xcamera), themes_plugin.cpp (themes.so / xthemes), modem_plugin.cpp (modem.so / xmodem), networks_plugin.cpp (networks.so / xnetworks / xbluetooth), ringtones_plugin.cpp (ringtones.so / xringtones), wallpapers_plugin.cpp (wallpapers.so / xwallpapers / xbackground), music_plugin.cpp (music.so / xmusic / xplayer).
  • dwm_plugin_runner.c: Lightweight /usr/bin/dwm-plugin launcher symlinked by xdrawer, xdialer, xcalllog, xcallscreen, xcontacts, xsms, xfiles, xcamera, xthemes, xmodem, xnetworks, xbluetooth, xringtones, xwallpapers, xbackground, xmusic, xplayer, dmenu, and xdmenu.
• src/xdrawer/: Global phone controls overlay (xdrawer.so / xdrawer), toggled by pressing both softkeys simultaneously.
• src/sxmo-st/: Patched st terminal with HarfBuzz OpenType ligatures (Fira Code), XIM (fcitx5-t9), and live SIGUSR1 .Xresources reload.
• src/fcitx5-t9/: 6-mode keypad input method (abc, Abc, ABC, Sym, Ctl, 123 + * long-press Ctrl+ latch) with fixed bottom preedit bar (Y=290, H=30).
• src/games/: Standalone keypad-driven 240x320 X11 games (snake.cpp -> /usr/bin/snake, tetris.cpp -> /usr/bin/tetris) with built-in 5x7 bitmap fonts, timerfd-driven pacing, and offscreen Pixmap double buffering.
• src/msm8905-cam/ & src/leds-msm8905-torch/: Out-of-tree Linux 6.12.1-msm8916 kernel modules for the rear GC2395 camera (/dev/video0) and SY7807 torch LED (white:torch) / WCD codec init / PM8909 PON shutdown.
• overlay/rootfs/: System configuration overlay applied over the target rootfs (kept in sync with prebuilt/).
• prebuilt/: Cross-compiled armv7 binaries and kernel modules (sxmo-x11, fcitx5-t9, xlibre, kernel-6.12.1-msm8916, bantam, games).
• devices/ & patches/: Device trees (.dts/.dtb), MIPI-DBI panel init sequences, and upstream patch sets.

3. Build & Image Generation Commands

All cross-compilation scripts run inside rootless Docker (alpine:3.24 armv7 sysroot) and automatically update both prebuilt/ and overlay/rootfs/:

• ./scripts/build-sxmo-x11.sh — Builds st, dmenu.so, dwm, dwm-plugin, sxmo_vibrate, and all C++ .so plugins (xdrawer, dialer, calllog, callscreen, contacts, sms, files, camera, themes, modem, networks, ringtones, wallpapers, music).
• ./scripts/build-dmenu.sh — Rebuilds only dmenu.so, stest, dmenu_path, and dmenu_run.
• ./scripts/build-games.sh — Builds standalone X11 games in src/games/ (snake, tetris).
• ./scripts/build-fcitx5-t9.sh — Builds src/fcitx5-t9 (libt9.so / t9.so).
• ./scripts/build-kernel-audio.sh — Builds 6.12.1-msm8916 QDSP6 audio, torch LED, camera .ko modules, and device .dtb files.
• ./scripts/build-xlibre.sh — Builds Xlibre Xorg and libinput/fbdev DDX drivers.
• ./scripts/build-bantam.sh — Fetches and cross-compiles the bantam AI agent.
• ./scripts/generate-artwork.py — Regenerates wallpapers, splashes, and icons from artwork/icon-large.png.
• ./scripts/version.sh [--print | target_rootfs] — Computes the date-based release version (<year-letter><MM><DD> with 2026 = a) and substitutes @BANANARCHY_VERSION@ in etc/os-release, etc/issue, and etc/motd (invoked automatically during overlay application and image builds).
• ./chroot-shell.sh — Opens an armv7 container shell to manage packages in rootfs/ (pkg-add, pkg-del, pkg-search).
• ./rebuild-image.sh <device> [--mkinitfs] — Applies overlay/rootfs/ + prebuilt/ into rootfs/ and produces flashable images in images/.
• sudo ./flash-edl.sh [device] — Flashes lk2nd and the system image over Qualcomm USB EDL (05c6:9008).

4. Coding & Architecture Conventions

• Indentation: Always use 2-space indentation in C, C++, Python, and shell scripts (tabs only in Makefiles and TSV files).
• No Emojis: Never use emojis in source code, UI strings, logs, or commit messages (use Nerd Font PUA codepoints defined in phone_data.h / dmenu.c for UI icons).
• Unified Theming: Never hardcode UI colors or font sizes in dwm, dmenu, st, or any DWM plugin. Read colors and proportional font sizes from PluginTheme (src/dwm-plugins/theme.h) / .Xresources (theme.*), and handle RELOAD_THEME on the plugin FIFO.
• Zero-Lag Plugin Model: Phone UI apps must run as preloaded resident daemons (--preload) guarded by /tmp/dwm_plugin_<name>.lock, sleeping at 0% CPU on poll() over ConnectionNumber(dpy) and /tmp/dwm_plugin_<name>.fifo, and rendering into an offscreen Pixmap (240x296 at X=0, Y=24) copied with XCopyArea to prevent flicker.
• Documentation: Keep README.md and MANUAL.md synchronized with any new user-facing features or keybindings, and do not leave third-party .md files inside src/ or edl/.