Skip to content

Commit f6b579c

Browse files
GoldzxcbugGoldzxcbug
committed
添加Anland的指南
1 parent 3134eea commit f6b579c

4 files changed

Lines changed: 326 additions & 0 deletions

File tree

‎Documentation/Anland.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
<!--
2+
title: Anland (Wayland) Usage Guide
3+
section: Guides
4+
order: 3
5+
desc: Configure Anland Wayland display for Droidspaces Android containers, including backend installation, APK setup, and container options.
6+
keywords: anland, wayland, droidspaces, android, kwin, weston, kde, plasma, gpu, adreno, snapdragon
7+
-->
8+
9+
# Anland (Wayland) Usage Guide
10+
11+
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.
12+
13+
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.
14+
15+
### Quick Navigation
16+
17+
- [Prerequisites](#requirements)
18+
- [Step 1: Install an Anland-supported Backend](#backend)
19+
- [Method 1: Build and Install Inside the Container](#manual-build)
20+
- [Method 2: Use the Droidspaces Rootfs Builder](#rootfs-builder)
21+
- [Step 2: Install the Anland App](#app)
22+
- [Step 3: Configure the Droidspaces Container](#container-config)
23+
24+
---
25+
26+
<a id="requirements"></a>
27+
28+
## Prerequisites
29+
30+
Before configuring Anland, make sure the following requirements are met:
31+
32+
1. **An Android device that supports Droidspaces**: Anland works together with Droidspaces and requires `Anland Display` to be enabled in the container configuration.
33+
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.
34+
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.
35+
36+
> [!NOTE]
37+
>
38+
> Anland only handles the display path. Container management, rootfs handling, permissions, GPU access, and startup flow are still managed by Droidspaces.
39+
40+
---
41+
42+
<a id="backend"></a>
43+
44+
## Step 1: Install an Anland-supported Backend
45+
46+
The desktop environment inside the container must use an Anland-supported backend. Otherwise, the Android side cannot receive the Wayland output.
47+
48+
<a id="manual-build"></a>
49+
50+
### Method 1: Build and Install Inside the Container
51+
52+
Use this method if you want to choose a specific desktop environment, target distribution, or debug the backend manually.
53+
54+
1. **Enter the Droidspaces container.**
55+
56+
2. **Clone the Anland source code.**
57+
58+
```bash
59+
git clone https://github.com/superturtlee/anland.git
60+
```
61+
62+
3. **Choose the matching desktop environment and distribution under the `producers` directory.**
63+
64+
For example, the KDE backend layout looks like this:
65+
66+
```txt
67+
producers
68+
└── kde
69+
├── anland_backend_debian13_v5
70+
├── anland_backend_v5
71+
├── Debian13_v5
72+
├── Fedora43_v5
73+
└── ubuntu2604_v5
74+
└── other desktops
75+
```
76+
77+
4. **Run the matching `build.sh` script as root.**
78+
79+
The build script installs the required dependencies and installs the matching Anland backend into the container.
80+
81+
5. **Start the desktop with the project's `startup.sh` script.**
82+
83+
<a id="rootfs-builder"></a>
84+
85+
### Method 2: Use the Droidspaces Rootfs Builder
86+
87+
If you mainly use KDE Plasma, the automated rootfs builder is recommended. It is simpler and better suited for repeatable deployments.
88+
89+
Project: [Droidspaces-rootfs-KDE-builder](https://github.com/Goldzxcbug/Droidspaces-rootfs-KDE-builder)
90+
91+
> [!IMPORTANT]
92+
>
93+
> This method currently supports KDE Plasma only.
94+
95+
1. **Fork the project.**
96+
2. Open the GitHub **Actions** page and find the `编译并发布Droidspaces Rootfs` workflow.
97+
3. Run the workflow manually and enable the `Wayland 支持` option.
98+
4. Wait for the build to finish. This usually takes about 15 minutes.
99+
5. Open the project's **Releases** page, download the generated rootfs package, and import it into Droidspaces.
100+
6. If KDE desktop auto-start is not enabled, enter the container as a normal user and run:
101+
102+
```bash
103+
startplasma-wayland
104+
```
105+
106+
---
107+
108+
<a id="app"></a>
109+
110+
## Step 2: Install the Anland App
111+
112+
1. Download the **Anland APK** from the [latest Anland release](https://github.com/superturtlee/anland/releases/latest).
113+
2. Install the APK on your Android device.
114+
3. Grant **root permission** to Anland on first launch.
115+
116+
---
117+
118+
<a id="container-config"></a>
119+
120+
## Step 3: Configure the Droidspaces Container
121+
122+
Edit the target container configuration in Droidspaces and set the following options.
123+
124+
### Required Settings
125+
126+
1. Enable **GPU Access**.
127+
2. Enable **Anland Display**.
128+
3. Disable **Configure Termux:X11**.
129+
130+
> [!IMPORTANT]
131+
>
132+
> Anland and Termux:X11 are separate display paths. When using Anland, disable the Termux:X11 configuration to avoid conflicting environment variables and display services.
133+
134+
### Recommended Settings
135+
136+
1. **Disable Configure PulseAudio**.
137+
138+
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.
139+
140+
2. **Keep SELinux Permissive Mode disabled by default**.
141+
142+
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.
143+
144+
### KDE Plasma Notes
145+
146+
> [!IMPORTANT]
147+
>
148+
> 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.

‎Documentation/zh-CN/Anland.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
<!--
2+
title: Anland (Wayland) 使用指南
3+
section: 指南
4+
order: 3
5+
desc: 在 Droidspaces Android 容器中配置 Anland Wayland 显示，包括后端安装、APK 安装与容器选项。
6+
keywords: anland, wayland, droidspaces, android, kwin, weston, kde, plasma, gpu, adreno, snapdragon
7+
-->
8+
9+
# Anland (Wayland) 使用指南
10+
11+
Anland 是 Droidspaces 的可选 Wayland 显示方案。它通过一套缓冲区共享协议，让 Linux 合成器（如 KWin / Weston）将桌面内容渲染到 GPU 缓冲区，再由 Android 端的 Anland 显示表面进行呈现。Linux 容器与 Android 应用之间通过轻量级守护进程和 Unix 域套接字完成桥接。
12+
13+
与 Termux:X11 路径不同，Anland 面向 Wayland 合成器工作流，适合希望在 Droidspaces 容器中运行 KDE Plasma Wayland 等桌面环境的场景。
14+
15+
### 快速导航
16+
17+
- [前提条件](#requirements)
18+
- [第 1 步：安装支持 Anland 的后端](#backend)
19+
- [方式一：在容器内手动编译安装](#manual-build)
20+
- [方式二：使用 Droidspaces Rootfs 自动构建项目](#rootfs-builder)
21+
- [第 2 步：安装 Anland 应用](#app)
22+
- [第 3 步：配置 Droidspaces 容器](#container-config)
23+
24+
---
25+
26+
<a id="requirements"></a>
27+
28+
## 前提条件
29+
30+
在配置 Anland 之前，请先确认满足以下条件：
31+
32+
1. **支持 Droidspaces 的 Android 设备**：Anland 与 Droidspaces 配合使用，需要在容器配置中启用 `Anland Display`。
33+
2. **支持 Anland 的显示后端**：需要使用打过 Anland 补丁的合成器后端。目前主要支持 `KWin`，相关后端可参考 [Anland producers 目录](https://github.com/superturtlee/anland/tree/main/producers)。
34+
3. **推荐高通 Snapdragon / Adreno 设备**：Anland 更依赖设备侧 GPU 与缓冲区共享能力，高通平台通常兼容性更好。
35+
36+
> [!NOTE]
37+
>
38+
> Anland 只负责显示链路。容器、rootfs、权限、GPU 访问和启动流程仍由 Droidspaces 管理。
39+
40+
---
41+
42+
<a id="backend"></a>
43+
44+
## 第 1 步：安装支持 Anland 的后端
45+
46+
容器内的桌面环境必须使用支持 Anland 的后端，否则 Android 端无法接收到 Wayland 画面。
47+
48+
<a id="manual-build"></a>
49+
50+
### 方式一：在容器内手动编译安装
51+
52+
这种方式适合希望自行选择桌面环境、发行版或调试后端的用户。
53+
54+
1. **进入 Droidspaces 容器。**
55+
56+
2. **拉取 Anland 源码。**
57+
58+
```bash
59+
git clone https://github.com/superturtlee/anland.git
60+
```
61+
62+
3. **在 `producers` 目录中选择对应的桌面环境和发行版。**
63+
64+
以 KDE 后端为例：
65+
66+
```txt
67+
producers
68+
└── kde
69+
├── anland_backend_debian13_v5
70+
├── anland_backend_v5
71+
├── Debian13_v5
72+
├── Fedora43_v5
73+
└── ubuntu2604_v5
74+
└── other desktops
75+
```
76+
77+
4. **以 root 身份执行对应目录中的 `build.sh`。**
78+
79+
构建脚本会处理依赖安装，并将对应的 Anland 后端安装到容器中。
80+
81+
5. **使用项目提供的 `startup.sh` 启动桌面。**
82+
83+
<a id="rootfs-builder"></a>
84+
85+
### 方式二：使用 Droidspaces Rootfs 自动构建项目
86+
87+
如果你主要使用 KDE Plasma，推荐使用自动构建的 rootfs，流程更简单，也更适合重复部署。
88+
89+
项目地址：[Droidspaces-rootfs-KDE-builder](https://github.com/Goldzxcbug/Droidspaces-rootfs-KDE-builder)
90+
91+
> [!IMPORTANT]
92+
>
93+
> 该方式目前仅支持 KDE Plasma 桌面。
94+
95+
1. **Fork 该项目。**
96+
2. 进入 GitHub **Actions** 页面，找到 `编译并发布Droidspaces Rootfs` 工作流。
97+
3. 手动运行工作流，并启用 `Wayland 支持` 选项。
98+
4. 等待构建完成，通常约 15 分钟。
99+
5. 进入项目的 **Releases** 页面，下载生成的 rootfs 包，并导入 Droidspaces。
100+
6. 如果没有启用 KDE 桌面自启动，请进入容器中的普通用户环境，运行：
101+
102+
```bash
103+
startplasma-wayland
104+
```
105+
106+
---
107+
108+
<a id="app"></a>
109+
110+
## 第 2 步：安装 Anland 应用
111+
112+
1. 从 [Anland 最新发布版本](https://github.com/superturtlee/anland/releases/latest) 下载 **Anland APK**。
113+
2. 在 Android 设备上安装 APK。
114+
3. 首次启动时授予 Anland **Root 权限**。
115+
116+
---
117+
118+
<a id="container-config"></a>
119+
120+
## 第 3 步：配置 Droidspaces 容器
121+
122+
在 Droidspaces 中编辑目标容器配置，并设置以下选项。
123+
124+
### 必需设置
125+
126+
1. 启用 **GPU 访问**。
127+
2. 启用 **Anland Display**。
128+
3. 关闭 **配置 Termux:X11**。
129+
130+
> [!IMPORTANT]
131+
>
132+
> Anland 与 Termux:X11 是两条不同的显示路径。使用 Anland 时应关闭 Termux:X11 相关配置，避免环境变量和显示服务互相干扰。
133+
134+
### 推荐设置
135+
136+
1. **关闭配置 PulseAudio**。
137+
138+
Anland 自带音频处理链路，通常不需要 Droidspaces 的 PulseAudio 配置。关闭该选项后，还需要清理容器内已有的 `PULSE_SERVER` 环境变量，避免应用继续连接旧的 PulseAudio 服务。
139+
140+
2. **默认关闭 SELinux 宽容模式。**
141+
142+
建议优先在 SELinux enforcing 模式下运行。若某些设备在强制模式下无法正常启动或显示 Anland，再临时启用 **SELinux 宽容模式** 作为兼容性排查手段。
143+
144+
### KDE Plasma 注意事项
145+
146+
> [!IMPORTANT]
147+
>
148+
> 在 Debian 或 Ubuntu 容器中运行 KDE Plasma Wayland 时，请确保内核启用了 User Namespace（User-NS）支持，并在 Droidspaces 特权模式中启用 `noseccomp`。否则 KDE Plasma 可能出现明显卡顿或响应迟缓。

‎README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,7 @@ What makes Droidspaces unique is its **zero-dependency, native execution** on bo
144144
- [Installation](#installation)
145145
- [Usage](#usage)
146146
- [Display, Audio & Desktop](#display-audio-desktop)
147+
- [Anland (Wayland)](#anland-wayland)
147148
- [Security & Isolation Philosophy](#security-model)
148149
- [Additional Documentation](#additional-documentation)
149150
- [Troubleshooting](./Documentation/Troubleshooting.md)
@@ -178,6 +179,7 @@ The entire runtime is a **single static binary** under 400KB, compiled against m
178179
| **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. |
179180
| **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. |
180181
| **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)] |
182+
| **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)] |
181183
| **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)] |
182184
| **Linux GPU Acceleration** | Zero-configuration GPU acceleration for AMD and Intel GPUs on Linux desktop hosts. [[More info](./Documentation/Graphics-and-Audio.md)] |
183185
| **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
350352

351353
---
352354

355+
<a id="anland-wayland"></a>
356+
357+
## Anland (Wayland)
358+
359+
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.
360+
361+
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.
362+
363+
See the **[Anland (Wayland) Usage Guide](./Documentation/Anland.md)** for backend installation, rootfs builder usage, APK setup, and required Droidspaces container settings.
364+
365+
---
366+
353367
<a id="security-model"></a>
354368

355369
## Security & Isolation Philosophy
@@ -390,6 +404,7 @@ For GPU acceleration methods, sound setup, DE auto-boot internals, and Linux des
390404
| [Feature Deep Dives](Documentation/Features.md) | Detailed explanation of each major feature. |
391405
| [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. |
392406
| [Display, Audio & Desktop Guide](Documentation/Graphics-and-Audio.md) | GPU acceleration, PulseAudio sound, and desktop environment auto-boot on Android and Linux. |
407+
| [Anland (Wayland) Usage Guide](Documentation/Anland.md) | Wayland display setup through Anland, including patched backend installation, APK setup, and Droidspaces container settings. |
393408
| [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. |
394409
| [Uninstallation Guide](Documentation/Uninstallation.md) | How to remove Droidspaces from your system. |
395410

‎README_CN.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,7 @@ Droidspaces 的独特之处在于其对 Android 和 Linux 本身**零依赖**、
143143
- [安装指南](#installation)
144144
- [使用指南](#usage)
145145
- [显示、音频与桌面](#display-audio-desktop)
146+
- [Anland (Wayland)](#anland-wayland)
146147
- [安全与隔离的理念](#security-model)
147148
- [更多文档](#additional-documentation)
148149
- [疑难解答](./Documentation/zh-CN/Troubleshooting.md)
@@ -177,6 +178,7 @@ Droidspaces 的设计目标是原生运行在任何搭载 Linux 内核的设备
177178
| **命名空间隔离** | 通过 PID、MNT、UTS、IPC 以及 Cgroup 命名空间实现完全隔离。每个容器拥有自己的进程树、挂载表、主机名、IPC 资源和 cgroup 层级。 |
178179
| **网络隔离** | **3 种网络模式（Host、NAT、None）**。通过 `CLONE_NEWNET` 实现纯网络隔离（NAT/None 模式）或共享宿主机网络（Host 模式）。在 Android 和 Linux 版本上均可使用。 |
179180
| **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)] |
181+
| **Anland Wayland 显示** | 可选的 Wayland 显示方案，使用 Anland 缓冲区共享协议。打过补丁的 Linux 合成器（如 KWin/Weston）将桌面渲染进 GPU 缓冲区，再由 Android 端的 Anland 进行呈现；在 Droidspaces 中启用 `Anland Display` 并使用支持 Anland 的后端即可。[[配置指南](./Documentation/zh-CN/Anland.md)] |
180182
| **Android 音效** | PulseAudio 守护进程以 Termux 用户身份在宿主机上运行，使 Android 音频 HAL 授予其设备访问权限。套接字以绑定挂载方式挂载到容器的 `/tmp/.pulse-socket`，`PULSE_SERVER` 自动注入，音效开箱即用。[[更多信息](./Documentation/zh-CN/Graphics-and-Audio.md#pulseaudio)] |
181183
| **Linux GPU 加速** | 在 Linux 桌面端上无需额外配置 AMD 和 Intel GPU 硬件加速。[[更多信息](./Documentation/zh-CN/Graphics-and-Audio.md)] |
182184
| **端口转发** | 在 NAT 模式下将宿主机端口转发到容器（例如 `--port 22:22`）。支持 TCP 和 UDP，以及端口范围如 `1-500:1-500`。 |
@@ -349,6 +351,18 @@ GPU 加速方式、音效配置、桌面环境自动启动原理以及 Linux 桌
349351

350352
---
351353

354+
<a id="anland-wayland"></a>
355+
356+
## Anland (Wayland)
357+
358+
Anland 为 Android 设备提供可选的 Wayland 显示路径。它不走 X11，而是让打过补丁的 Linux 合成器（如 KWin/Weston）将桌面渲染进 GPU 缓冲区，再通过轻量级 Unix 套接字桥接由 Android 端的 Anland 呈现。
359+
360+
使用时需要在 Droidspaces 容器内安装支持 Anland 的后端，在 Android 上安装 Anland APK，然后在容器配置中启用 `GPU 访问` 和 `Anland Display`。推荐使用高通 Snapdragon/Adreno 设备。
361+
362+
后端安装、Rootfs 自动构建、APK 安装以及 Droidspaces 容器设置请参阅 **[Anland (Wayland) 使用指南](./Documentation/zh-CN/Anland.md)**。
363+
364+
---
365+
352366
<a id="security-model"></a>
353367

354368
## 安全与隔离理念
@@ -388,6 +402,7 @@ GPU 加速方式、音效配置、桌面环境自动启动原理以及 Linux 桌
388402
|----------|-------------|
389403
| [功能深度解析](./Documentation/zh-CN/Features.md) | 每个主要功能的详细说明。 |
390404
| [显示、音频与桌面指南](./Documentation/zh-CN/Graphics-and-Audio.md) | Android 和 Linux 上的 GPU 加速、PulseAudio 音效与桌面环境自动启动。 |
405+
| [Anland (Wayland) 使用指南](./Documentation/zh-CN/Anland.md) | 通过 Anland 配置 Wayland 显示，包括后端安装、APK 设置与 Droidspaces 容器选项。 |
391406
| [你可以做的酷炫事情（Tailscale、Docker 等）](./Documentation/zh-CN/Cool-things-you-can-do.md) | 在容器内运行 Tailscale、Docker 等工具的实用配置方案。 |
392407
| [卸载指南](./Documentation/zh-CN/Uninstallation.md) | 如何从系统中移除 Droidspaces。 |
393408

0 commit comments

Comments
 (0)