docs/termux_guide.md

# Running X11 Desktop on Android (Termux)

This guide explains how to run a full Linux desktop environment on your Android device using Termux and X11.

## Prerequisites

1.  **Termux**: Install from F-Droid (Google Play version is outdated).
2.  **Termux:X11**: Install the companion app (check GitHub releases for the latest nightly build).

### Note on X11 Repository
Packages from `x11-repo` are now maintained along with the main repo. However, the repository is not enabled in Termux by default. You must enable it to install X11 packages:
```bash
pkg install x11-repo
```

## Method 1: Proot-distro (Recommended)

This method uses `proot-distro` to run a Linux distribution (like Debian or Arch) without root access.

### 1. Install Dependencies

Open Termux and install the necessary packages:

```bash
pkg update
pkg install proot-distro x11-repo
pkg install termux-x11-nightly
```

### 2. Install a Distro

Install a distribution, for example, Debian:

```bash
proot-distro install debian
```

### 3. Login and Setup

Login to the distro with shared temporary directory support:

```bash
proot-distro login --user user debian --shared-tmp
```

*Note: You may need to create a user first if one doesn't exist.*

### 4. Launch Desktop Environment

Start the X11 server and launch your desktop environment (e.g., XFCE4):

1.  Open the **Termux:X11** app on your phone.
2.  Go back to **Termux**.
3.  Run the following command:

```bash
termux-x11 :0 -xstartup "dbus-launch --exit-with-session xfce4-session"
```

### Tips
- **Keyboard**: Press the "Back" button to toggle the Android keyboard.
- **Shortcuts**: Install "Hacker's Keyboard" for a full PC layout.

---

## Method 2: Chroot (Root Required)

This method requires a rooted device but offers better performance.

### 1. Setup

1.  Launch **Termux:X11**.
2.  Go back to **Termux**.
3.  Start the X server:

```bash
termux-x11 :0 -ac &
```

### 2. Mount Directories

Mount Termux's tmp to the chroot environment (assuming Ubuntu):

```bash
sudo busybox mount --bind $PREFIX/tmp /data/local/tmp/ubuntu/tmp
```

### 3. Start Session

Log into your chroot environment and start the session:

```bash
# Login script (adjust path as needed)
sh /data/local/tmp/startu.sh

# Inside chroot
sudo chmod -R 777 /tmp
export DISPLAY=:0 
export PULSE_SERVER=tcp:127.0.0.1:4713
dbus-launch --exit-with-session startxfce4 &
```

---

## Advanced Features

### Wayland Session

Termux:X11 is an X server, but you can run nested Wayland sessions.

1.  Install Weston: `pkg install weston`
2.  Run: `weston`

### GPU Acceleration

For hardware acceleration, refer to `virglrenderer` tutorials for Termux.

### Input Methods (Chinese/CJK)

1.  In Termux:X11, go to **Preferences** -> **Keyboard**.
2.  Enable **"Workaround to enable CJK Gboard"**.
3.  Press "Back" to show the keyboard.
4.  Scroll the bottom toolbar to the left to find the text input box.

### Building Packages from Source

You can build X11 packages manually using the provided Docker image.

1.  Clone the repository:
    ```bash
    git clone https://github.com/termux/x11-packages
    ```
2.  Enter the build environment:
    ```bash
    cd ./x11-packages
    ./start-builder.sh
    ```
3.  Build a package (replace `${arch}` and `${package name}`):
    ```bash
    ./build-package.sh -a ${arch} ${package name}
    ```