diff --git a/Documentation/Anland.md b/Documentation/Anland.md new file mode 100644 index 00000000..36a654d0 --- /dev/null +++ b/Documentation/Anland.md @@ -0,0 +1,148 @@ + + +# Anland (Wayland) Usage Guide + +Anland is an optional Wayland display path for Droidspaces. It uses a buffer-sharing protocol where a Linux compositor, such as KWin or Weston, renders desktop content into GPU buffers, and the Anland display surface on Android presents those buffers. A lightweight daemon bridges the Linux container and Android app over a Unix domain socket. + +Unlike the Termux:X11 path, Anland is designed for Wayland compositor workflows. It is useful when you want to run desktop environments such as KDE Plasma Wayland inside a Droidspaces container. + +### Quick Navigation + +- [Prerequisites](#requirements) +- [Step 1: Install an Anland-supported Backend](#backend) + - [Method 1: Build and Install Inside the Container](#manual-build) + - [Method 2: Use the Droidspaces Rootfs Builder](#rootfs-builder) +- [Step 2: Install the Anland App](#app) +- [Step 3: Configure the Droidspaces Container](#container-config) + +--- + + + +## Prerequisites + +Before configuring Anland, make sure the following requirements are met: + +1. **An Android device that supports Droidspaces**: Anland works together with Droidspaces and requires `Anland Display` to be enabled in the container configuration. +2. **An Anland-supported display backend**: The compositor backend must be patched for Anland. `KWin` is the main supported backend. See the [Anland producers directory](https://github.com/superturtlee/anland/tree/main/producers) for available backends. +3. **A Qualcomm Snapdragon / Adreno device is recommended**: Anland depends heavily on device-side GPU and buffer-sharing behavior, and Qualcomm platforms usually provide better compatibility. + +> [!NOTE] +> +> Anland only handles the display path. Container management, rootfs handling, permissions, GPU access, and startup flow are still managed by Droidspaces. + +--- + + + +## Step 1: Install an Anland-supported Backend + +The desktop environment inside the container must use an Anland-supported backend. Otherwise, the Android side cannot receive the Wayland output. + + + +### Method 1: Build and Install Inside the Container + +Use this method if you want to choose a specific desktop environment, target distribution, or debug the backend manually. + +1. **Enter the Droidspaces container.** + +2. **Clone the Anland source code.** + + ```bash + git clone https://github.com/superturtlee/anland.git + ``` + +3. **Choose the matching desktop environment and distribution under the `producers` directory.** + + For example, the KDE backend layout looks like this: + + ```txt + producers + └── kde + ├── anland_backend_debian13_v5 + ├── anland_backend_v5 + ├── Debian13_v5 + ├── Fedora43_v5 + └── ubuntu2604_v5 + └── other desktops + ``` + +4. **Run the matching `build.sh` script as root.** + + The build script installs the required dependencies and installs the matching Anland backend into the container. + +5. **Start the desktop with the project's `startup.sh` script.** + + + +### Method 2: Use the Droidspaces Rootfs Builder + +If you mainly use KDE Plasma, the automated rootfs builder is recommended. It is simpler and better suited for repeatable deployments. + +Project: [Droidspaces-rootfs-KDE-builder](https://github.com/Goldzxcbug/Droidspaces-rootfs-KDE-builder) + +> [!IMPORTANT] +> +> This method currently supports KDE Plasma only. + +1. **Fork the project.** +2. Open the GitHub **Actions** page and find the `编译并发布Droidspaces Rootfs` workflow. +3. Run the workflow manually and enable the `Wayland 支持` option. +4. Wait for the build to finish. This usually takes about 15 minutes. +5. Open the project's **Releases** page, download the generated rootfs package, and import it into Droidspaces. +6. If KDE desktop auto-start is not enabled, enter the container as a normal user and run: + + ```bash + startplasma-wayland + ``` + +--- + + + +## Step 2: Install the Anland App + +1. Download the **Anland APK** from the [latest Anland release](https://github.com/superturtlee/anland/releases/latest). +2. Install the APK on your Android device. +3. Grant **root permission** to Anland on first launch. + +--- + + + +## Step 3: Configure the Droidspaces Container + +Edit the target container configuration in Droidspaces and set the following options. + +### Required Settings + +1. Enable **GPU Access**. +2. Enable **Anland Display**. +3. Disable **Configure Termux:X11**. + +> [!IMPORTANT] +> +> Anland and Termux:X11 are separate display paths. When using Anland, disable the Termux:X11 configuration to avoid conflicting environment variables and display services. + +### Recommended Settings + +1. **Disable Configure PulseAudio**. + + Anland provides its own audio handling path, so the Droidspaces PulseAudio configuration is usually unnecessary. After disabling it, also clear any existing `PULSE_SERVER` environment variable inside the container so applications do not continue connecting to an old PulseAudio service. + +2. **Keep SELinux Permissive Mode disabled by default**. + + Try running Anland under SELinux enforcing mode first. If Anland fails to start or display correctly on a specific device, enable **SELinux Permissive Mode** temporarily as a compatibility troubleshooting step. + +### KDE Plasma Notes + +> [!IMPORTANT] +> +> When running KDE Plasma Wayland in a Debian or Ubuntu container, make sure the kernel has User Namespace (User-NS) support enabled, and enable `noseccomp` in Droidspaces privileged mode. Otherwise, KDE Plasma may become noticeably slow or unresponsive. diff --git a/Documentation/zh-CN/Anland.md b/Documentation/zh-CN/Anland.md new file mode 100644 index 00000000..ff8237eb --- /dev/null +++ b/Documentation/zh-CN/Anland.md @@ -0,0 +1,148 @@ + + +# Anland (Wayland) 使用指南 + +Anland 是 Droidspaces 的可选 Wayland 显示方案。它通过一套缓冲区共享协议，让 Linux 合成器（如 KWin / Weston）将桌面内容渲染到 GPU 缓冲区，再由 Android 端的 Anland 显示表面进行呈现。Linux 容器与 Android 应用之间通过轻量级守护进程和 Unix 域套接字完成桥接。 + +与 Termux:X11 路径不同，Anland 面向 Wayland 合成器工作流，适合希望在 Droidspaces 容器中运行 KDE Plasma Wayland 等桌面环境的场景。 + +### 快速导航 + +- [前提条件](#requirements) +- [第 1 步：安装支持 Anland 的后端](#backend) + - [方式一：在容器内手动编译安装](#manual-build) + - [方式二：使用 Droidspaces Rootfs 自动构建项目](#rootfs-builder) +- [第 2 步：安装 Anland 应用](#app) +- [第 3 步：配置 Droidspaces 容器](#container-config) + +--- + + + +## 前提条件 + +在配置 Anland 之前，请先确认满足以下条件： + +1. **支持 Droidspaces 的 Android 设备**：Anland 与 Droidspaces 配合使用，需要在容器配置中启用 `Anland Display`。 +2. **支持 Anland 的显示后端**：需要使用打过 Anland 补丁的合成器后端。目前主要支持 `KWin`，相关后端可参考 [Anland producers 目录](https://github.com/superturtlee/anland/tree/main/producers)。 +3. **推荐高通 Snapdragon / Adreno 设备**：Anland 更依赖设备侧 GPU 与缓冲区共享能力，高通平台通常兼容性更好。 + +> [!NOTE] +> +> Anland 只负责显示链路。容器、rootfs、权限、GPU 访问和启动流程仍由 Droidspaces 管理。 + +--- + + + +## 第 1 步：安装支持 Anland 的后端 + +容器内的桌面环境必须使用支持 Anland 的后端，否则 Android 端无法接收到 Wayland 画面。 + + + +### 方式一：在容器内手动编译安装 + +这种方式适合希望自行选择桌面环境、发行版或调试后端的用户。 + +1. **进入 Droidspaces 容器。** + +2. **拉取 Anland 源码。** + + ```bash + git clone https://github.com/superturtlee/anland.git + ``` + +3. **在 `producers` 目录中选择对应的桌面环境和发行版。** + + 以 KDE 后端为例： + + ```txt + producers + └── kde + ├── anland_backend_debian13_v5 + ├── anland_backend_v5 + ├── Debian13_v5 + ├── Fedora43_v5 + └── ubuntu2604_v5 + └── other desktops + ``` + +4. **以 root 身份执行对应目录中的 `build.sh`。** + + 构建脚本会处理依赖安装，并将对应的 Anland 后端安装到容器中。 + +5. **使用项目提供的 `startup.sh` 启动桌面。** + + + +### 方式二：使用 Droidspaces Rootfs 自动构建项目 + +如果你主要使用 KDE Plasma，推荐使用自动构建的 rootfs，流程更简单，也更适合重复部署。 + +项目地址：[Droidspaces-rootfs-KDE-builder](https://github.com/Goldzxcbug/Droidspaces-rootfs-KDE-builder) + +> [!IMPORTANT] +> +> 该方式目前仅支持 KDE Plasma 桌面。 + +1. **Fork 该项目。** +2. 进入 GitHub **Actions** 页面，找到 `编译并发布Droidspaces Rootfs` 工作流。 +3. 手动运行工作流，并启用 `Wayland 支持` 选项。 +4. 等待构建完成，通常约 15 分钟。 +5. 进入项目的 **Releases** 页面，下载生成的 rootfs 包，并导入 Droidspaces。 +6. 如果没有启用 KDE 桌面自启动，请进入容器中的普通用户环境，运行： + + ```bash + startplasma-wayland + ``` + +--- + + + +## 第 2 步：安装 Anland 应用 + +1. 从 [Anland 最新发布版本](https://github.com/superturtlee/anland/releases/latest) 下载 **Anland APK**。 +2. 在 Android 设备上安装 APK。 +3. 首次启动时授予 Anland **Root 权限**。 + +--- + + + +## 第 3 步：配置 Droidspaces 容器 + +在 Droidspaces 中编辑目标容器配置，并设置以下选项。 + +### 必需设置 + +1. 启用 **GPU 访问**。 +2. 启用 **Anland Display**。 +3. 关闭 **配置 Termux:X11**。 + +> [!IMPORTANT] +> +> Anland 与 Termux:X11 是两条不同的显示路径。使用 Anland 时应关闭 Termux:X11 相关配置，避免环境变量和显示服务互相干扰。 + +### 推荐设置 + +1. **关闭配置 PulseAudio**。 + + Anland 自带音频处理链路，通常不需要 Droidspaces 的 PulseAudio 配置。关闭该选项后，还需要清理容器内已有的 `PULSE_SERVER` 环境变量，避免应用继续连接旧的 PulseAudio 服务。 + +2. **默认关闭 SELinux 宽容模式。** + + 建议优先在 SELinux enforcing 模式下运行。若某些设备在强制模式下无法正常启动或显示 Anland，再临时启用 **SELinux 宽容模式** 作为兼容性排查手段。 + +### KDE Plasma 注意事项 + +> [!IMPORTANT] +> +> 在 Debian 或 Ubuntu 容器中运行 KDE Plasma Wayland 时，请确保内核启用了 User Namespace（User-NS）支持，并在 Droidspaces 特权模式中启用 `noseccomp`。否则 KDE Plasma 可能出现明显卡顿或响应迟缓。 diff --git a/README.md b/README.md index adff5872..b70c06db 100644 --- a/README.md +++ b/README.md @@ -144,6 +144,7 @@ What makes Droidspaces unique is its **zero-dependency, native execution** on bo - [Installation](#installation) - [Usage](#usage) - [Display, Audio & Desktop](#display-audio-desktop) +- [Anland (Wayland)](#anland-wayland) - [Security & Isolation Philosophy](#security-model) - [Additional Documentation](#additional-documentation) - [Troubleshooting](./Documentation/Troubleshooting.md) @@ -178,6 +179,7 @@ The entire runtime is a **single static binary** under 400KB, compiled against m | **Namespace Isolation** | Complete isolation via PID, MNT, UTS, IPC, and Cgroup namespaces. Each container has its own process tree, mount table, hostname, IPC resources, and cgroup hierarchy. | | **Network Isolation** | **4 Networking Modes (Host, NAT, None, Gateway)**. Pure network isolation via `CLONE_NEWNET` (NAT/None/Gateway modes) or shared host networking (Host mode). NAT auto-detects the active uplink (or pin it with `--upstream`); Gateway delegates LAN/DHCP/firewall to another container like OpenWRT. Works on both Android and Linux. | | **Android Display & GPU** | Three acceleration modes: **llvmpipe** (software, all devices), **VirGL** (Mali/PowerVR), and **Turnip** (native Qualcomm/Adreno). As of v6.3.0, the X server and VirGL server launch automatically when the container starts - zero manual Termux commands required. Environment variables (`DISPLAY=:5`, `GALLIUM_DRIVER=virpipe`) are injected automatically. [[More info](./Documentation/Graphics-and-Audio.md)] | +| **Anland Wayland Display** | Optional Wayland display path using Anland's buffer-sharing protocol. A patched Linux compositor such as KWin/Weston renders into GPU buffers that Android presents through Anland; enable `Anland Display` in Droidspaces and use an Anland-supported backend. [[Setup guide](./Documentation/Anland.md)] | | **Android Sound** | PulseAudio daemon runs on the host as the Termux user so Android's audio HAL grants it device access. The socket is bind-mounted into the container at `/tmp/.pulse-socket` and `PULSE_SERVER` is injected automatically - audio just works. [[More info](./Documentation/Graphics-and-Audio.md#pulseaudio)] | | **Linux GPU Acceleration** | Zero-configuration GPU acceleration for AMD and Intel GPUs on Linux desktop hosts. [[More info](./Documentation/Graphics-and-Audio.md)] | | **Port Forwarding** | Forward host ports to the container in NAT mode (e.g., `--port 22:22`). Supports TCP and UDP, as well as ranges like `1-500:1-500`. | @@ -350,6 +352,18 @@ For GPU acceleration methods, sound setup, DE auto-boot internals, and Linux des --- + + +## Anland (Wayland) + +Anland provides an optional Wayland display path for Android devices. Instead of X11, a patched Linux compositor such as KWin/Weston renders the desktop into GPU buffers, and Anland presents them on Android through a lightweight Unix-socket bridge. + +To use it, install an Anland-supported backend inside the Droidspaces container, install the Anland APK on Android, then enable `GPU Access` and `Anland Display` in the container configuration. Qualcomm Snapdragon/Adreno devices are recommended. + +See the **[Anland (Wayland) Usage Guide](./Documentation/Anland.md)** for backend installation, rootfs builder usage, APK setup, and required Droidspaces container settings. + +--- + ## Security & Isolation Philosophy @@ -390,6 +404,7 @@ For GPU acceleration methods, sound setup, DE auto-boot internals, and Linux des | [Feature Deep Dives](Documentation/Features.md) | Detailed explanation of each major feature. | | [Networking From Zero](Documentation/Networking-From-Zero.md) | Beginner-friendly guide to every networking concept behind Droidspaces - NAT, automatic uplink detection, `--upstream` pinning, and gateway mode with OpenWRT. | | [Display, Audio & Desktop Guide](Documentation/Graphics-and-Audio.md) | GPU acceleration, PulseAudio sound, and desktop environment auto-boot on Android and Linux. | +| [Anland (Wayland) Usage Guide](Documentation/Anland.md) | Wayland display setup through Anland, including patched backend installation, APK setup, and Droidspaces container settings. | | [Cool Things You Can Do (Tailscale, Docker, etc.)](Documentation/Cool-things-you-can-do.md) | Practical recipes for running Tailscale, Docker, and other tools inside containers. | | [Uninstallation Guide](Documentation/Uninstallation.md) | How to remove Droidspaces from your system. | diff --git a/README_CN.md b/README_CN.md index ce1e4527..8e5e0456 100644 --- a/README_CN.md +++ b/README_CN.md @@ -143,6 +143,7 @@ Droidspaces 的独特之处在于其对 Android 和 Linux 本身**零依赖**、 - [安装指南](#installation) - [使用指南](#usage) - [显示、音频与桌面](#display-audio-desktop) +- [Anland (Wayland)](#anland-wayland) - [安全与隔离的理念](#security-model) - [更多文档](#additional-documentation) - [疑难解答](./Documentation/zh-CN/Troubleshooting.md) @@ -177,6 +178,7 @@ Droidspaces 的设计目标是原生运行在任何搭载 Linux 内核的设备 | **命名空间隔离** | 通过 PID、MNT、UTS、IPC 以及 Cgroup 命名空间实现完全隔离。每个容器拥有自己的进程树、挂载表、主机名、IPC 资源和 cgroup 层级。 | | **网络隔离** | **3 种网络模式（Host、NAT、None）**。通过 `CLONE_NEWNET` 实现纯网络隔离（NAT/None 模式）或共享宿主机网络（Host 模式）。在 Android 和 Linux 版本上均可使用。 | | **Android 显示与 GPU** | 三种加速模式：**llvmpipe**（软件渲染，适用所有设备）、**VirGL**（Mali/PowerVR）和 **Turnip**（原生高通/Adreno）。自 v6.3.0 起，X 服务器和 VirGL 服务器在容器启动时自动拉起，无需任何 Termux 命令。环境变量（`DISPLAY=:5`、`GALLIUM_DRIVER=virpipe`）自动注入。[[更多信息](./Documentation/zh-CN/Graphics-and-Audio.md)] | +| **Anland Wayland 显示** | 可选的 Wayland 显示方案，使用 Anland 缓冲区共享协议。打过补丁的 Linux 合成器（如 KWin/Weston）将桌面渲染进 GPU 缓冲区，再由 Android 端的 Anland 进行呈现；在 Droidspaces 中启用 `Anland Display` 并使用支持 Anland 的后端即可。[[配置指南](./Documentation/zh-CN/Anland.md)] | | **Android 音效** | PulseAudio 守护进程以 Termux 用户身份在宿主机上运行，使 Android 音频 HAL 授予其设备访问权限。套接字以绑定挂载方式挂载到容器的 `/tmp/.pulse-socket`，`PULSE_SERVER` 自动注入，音效开箱即用。[[更多信息](./Documentation/zh-CN/Graphics-and-Audio.md#pulseaudio)] | | **Linux GPU 加速** | 在 Linux 桌面端上无需额外配置 AMD 和 Intel GPU 硬件加速。[[更多信息](./Documentation/zh-CN/Graphics-and-Audio.md)] | | **端口转发** | 在 NAT 模式下将宿主机端口转发到容器（例如 `--port 22:22`）。支持 TCP 和 UDP，以及端口范围如 `1-500:1-500`。 | @@ -349,6 +351,18 @@ GPU 加速方式、音效配置、桌面环境自动启动原理以及 Linux 桌 --- + + +## Anland (Wayland) + +Anland 为 Android 设备提供可选的 Wayland 显示路径。它不走 X11，而是让打过补丁的 Linux 合成器（如 KWin/Weston）将桌面渲染进 GPU 缓冲区，再通过轻量级 Unix 套接字桥接由 Android 端的 Anland 呈现。 + +使用时需要在 Droidspaces 容器内安装支持 Anland 的后端，在 Android 上安装 Anland APK，然后在容器配置中启用 `GPU 访问` 和 `Anland Display`。推荐使用高通 Snapdragon/Adreno 设备。 + +后端安装、Rootfs 自动构建、APK 安装以及 Droidspaces 容器设置请参阅 **[Anland (Wayland) 使用指南](./Documentation/zh-CN/Anland.md)**。 + +--- + ## 安全与隔离理念 @@ -388,6 +402,7 @@ GPU 加速方式、音效配置、桌面环境自动启动原理以及 Linux 桌 |----------|-------------| | [功能深度解析](./Documentation/zh-CN/Features.md) | 每个主要功能的详细说明。 | | [显示、音频与桌面指南](./Documentation/zh-CN/Graphics-and-Audio.md) | Android 和 Linux 上的 GPU 加速、PulseAudio 音效与桌面环境自动启动。 | +| [Anland (Wayland) 使用指南](./Documentation/zh-CN/Anland.md) | 通过 Anland 配置 Wayland 显示，包括后端安装、APK 设置与 Droidspaces 容器选项。 | | [你可以做的酷炫事情（Tailscale、Docker 等）](./Documentation/zh-CN/Cool-things-you-can-do.md) | 在容器内运行 Tailscale、Docker 等工具的实用配置方案。 | | [卸载指南](./Documentation/zh-CN/Uninstallation.md) | 如何从系统中移除 Droidspaces。 |