Kokuuuuuun/android-inux
GitHub: Kokuuuuuun/android-inux
Ain 是一个无需模拟器或虚拟机即可在 Linux x86_64 上原生运行 Android APK 的开源兼容层，通过多层翻译机制将 Android 运行时映射到 Linux 原生调用。
Stars: 0 | Forks: 0
# 
Ain — **And**roid **IN**ux：在 Linux 上运行 Android 应用
[](https://github.com/Kokuuuuuun/android-inux/actions/workflows/ci.yml)
[](https://www.rust-lang.org)
[](LICENSE)
[]()
**Ain** = **And**roid **IN**ux。它是一个开源兼容层，可直接在 Linux x86_64 上运行 Android APK —— **无需模拟器，无需容器，无需虚拟机**。你可以把它当作 Linux 中的 Android：就像 Wine 将 Windows API 调用转换为 POSIX 调用一样，Ain 通过结合 LD_PRELOAD shim 库、Box64 动态二进制转换以及重新实现的 Android 守护进程，将 Android 的 Bionic libc、Binder IPC、SurfaceFlinger 和系统服务转换为原生的 Linux 调用。
## ✨ 设计理念
Android 应用本质上只是带有特定 Android 运行环境的 Linux 进程。Ain 利用了这一点，直接将应用所期望的 Android API 映射到原生 Linux 的对应实现上：
| Android 组件 | Ain 转换 | 机制 |
|------------------|----------------|-----------|
| **Bionic libc** | glibc | LD_PRELOAD shim (`libbionic.so`) |
| **Binder IPC** | Unix domain sockets | `ain-binder` 守护进程 + `libbinder.so` |
| **ART / Dalvik** | 原生 ART 加载 | `ain-runtime` 桥接（通过 `dlopen` 加载 `libart.so`） |
| **SurfaceFlinger** | Wayland compositor | `ain-graphics` 守护进程 + ANGLE |
| **OpenGL ES** | Vulkan | ANGLE 转换层 |
| **系统服务** | 自定义守护进程 | `ain-services` (ActivityManager, PackageManager, WindowManager) |
| **ARM64 .so 文件** | x86_64 | Box64 动态重编译 |
## 🚀 项目状态
| 组件 | Crate | 状态 | 描述 |
|-----------|-------|--------|-------------|
| **APK 加载器** | `ain_loader` | ✅ **可用** | ZIP 解压、AXML 清单解析、`LD_PRELOAD` 环境设置 |
| **C Shim 库** | `ain-shims` | ⚠️ **已编译** | 9 个拦截 Android API 的共享库 (libbionic, liblog, libandroid, libbinder, libEGL, libGLESv2, libui, libgui, libcutils) |
| **ART 运行时桥接** | `ain-runtime` | 🔧 **开发中** | 通过 `dlopen` 加载 `libart.so`，`JNI_CreateJavaVM`，DEX 类加载，JNI 桥接 |
| **Binder IPC 守护进程** | `ain-binder` | 🔧 **开发中** | 基于 Unix socket 的服务注册表和带有 8 字节二进制头协议的事务路由器 |
| **图形合成器** | `ain-graphics` | 🔧 **开发中** | Wayland 显示服务器，ANGLE/Vulkan 渲染桥接，三缓冲模型 |
| **系统服务** | `ain-services` | 🔧 **开发中** | 基于 IPC 的 ActivityManager、PackageManager、WindowManager 守护进程 |
| **CLI** | `ain` | 🔧 **开发中** | `ain run`, `ain install`, `ain list`, `ain doctor`, `ain start`, `ain stop` |
### 当前进度里程碑：v0.1.0 — "能够加载"
- [x] APK 解压和 AndroidManifest.xml 二进制解析 (AXML)
- [x] 9 个 LD_PRELOAD shim 库编译并运行成功
- [x] 带有 `LD_PRELOAD` / `LD_LIBRARY_PATH` 配置的环境设置
- [x] 包含 6 个 crates + CLI 二进制文件的 Rust 工作区
- [x] 133 个单元测试 (ain-loader: 56, ain-runtime: 57, ain-graphics: 20)
- [x] CI pipeline (GitHub Actions: Rust 构建+测试，C shim 构建+测试，lint)
- [ ] 用于 ARM64→x86_64 转换的 Box64 集成
- [ ] ART 运行时桥接加载真实的 DEX 文件
- [ ] E2E：启动一个 "Hello World" APK
## 🏗️ 架构概述
Ain 作为一个 **4 层系统** 运行，逐步将 Android 接口转换为 Linux 的对应实现：
```
┌─────────────────────────────────────────────────────────┐
│ Android APK │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │classes.dex│ │ .so libs │ │ AndroidManifest.xml │ │
│ │ (DEX) │ │ (ARM/x86)│ │ (AXML binary) │ │
│ └────┬─────┘ └────┬─────┘ └──────────────────────┘ │
└───────┼──────────────┼──────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────┐
│ Layer 1: LD_PRELOAD C Shims (libbionic, liblog, ...) │
│ Translates Android libc/system APIs → glibc natively │
│ Box64 translates ARM64 .so → x86_64 (DynaRec) │
├─────────────────────────────────────────────────────────┤
│ Layer 2: Rust Daemons (binder, services, graphics) │
│ IPC via Unix sockets (8-byte binary header protocol) │
├─────────────────────────────────────────────────────────┤
│ Layer 3: ART Runtime Bridge (libart.so via dlopen) │
│ JNI_CreateJavaVM → DEX class loading → Java execution │
├─────────────────────────────────────────────────────────┤
│ Layer 4: Linux Native (glibc, Wayland, Vulkan, ALSA) │
└─────────────────────────────────────────────────────────┘
```
### 数据流：启动应用
```
ain run com.example.app
│
▼
┌────────────────┐
│ ain-loader │ 1. Extract APK to ~/.ain/apps//
│ (process.rs) │ 2. Parse AndroidManifest.xml (AXML)
│ │ 3. Detect arch (ARM64→Box64, x86_64→native)
│ │ 4. Build LD_PRELOAD chain
│ │ 5. Configure LD_LIBRARY_PATH
└────────┬───────┘
│
▼
┌────────────────┐
│ ain-shims │ 6. LD_PRELOAD injects libbionic.so, liblog.so,
│ (C libraries) │ libandroid.so, libbinder.so, libEGL.so, ...
│ │ 7. Android API calls → glibc/Linux syscalls
│ │ 8. Box64 translates ARM64 code if needed
└────────┬───────┘
│
▼
┌────────────────┐
│ ain-binder │ 9. Binder IPC → Unix domain sockets
│ (Rust daemon) │ 10. Service lookup via 8-byte header protocol
└────────┬───────┘
│
▼
┌────────────────┐
│ ain-runtime │ 11. dlopen("libart.so") → JNI_CreateJavaVM
│ (ART bridge) │ 12. Load classes.dex → execute Java bytecode
└────────┬───────┘
│
▼
┌────────────────┐
│ ain-graphics │ 13. EGL/GLES calls → ANGLE → Vulkan → Wayland
│ (compositor) │ 14. Triple-buffering via wl_buffer shmem
└────────────────┘
```
## 📦 组件
### ain-shims — C Shim 库 (`src/shims/`)
九个共享库，通过 `LD_PRELOAD` 拦截 Android API 调用，并将其委托给原生 Linux 实现。每个 `.so` 都导出了 Android 原生代码所期望的确切符号。
| 库 | 源码 | 用途 | 关键函数 |
|---------|--------|---------|---------------|
| **libbionic.so** | `src/libbionic/` | Bionic libc → glibc | `malloc`, `pthread_*`, `open/read/write`, `socket`, `dlopen/dlsym`, `futex`, `clock_gettime`, `stat`, 80+ 包装器 |
| **liblog.so** | `src/liblog/` | Android 日志 → syslog/stderr | `__android_log_print`, `__android_log_vprint`, `__android_log_assert` |
| **libandroid.so** | `src/libandroid/` | Android 系统属性 | `__system_property_get/set`, `android_get_application_target_sdk`, `AAssetManager_*` |
| **libbinder.so** | `src/libbinder/` | Binder IPC → Unix sockets | `IPCThreadState`, `BBinder`, `BpBinder`, `Parcel` 读写 |
| **libEGL.so / libGLESv2.so** | `src/libEGL/` | OpenGL ES → Linux EGL | `eglGetDisplay`, `eglCreateContext`, `eglSwapBuffers`, `glClear`, `glDrawArrays` |
| **libui.so** | `src/libui/` | Android UI 工具包存根 | `DisplayInfo`, `Fence`, `Region` |
| **libgui.so** | `src/libgui/` | SurfaceFlinger 客户端 | `BufferQueue`, `SurfaceControl`, `ISurfaceComposer` |
| **libcutils.so** | `src/libcutils/` | Android C 工具库 | `socket_local_server/client`, `property_get/set`, `klog_write`, `native_handle_*` |
所有 shim 均使用 `RTLD_NEXT` 在进行可选适配后链接到真正的 glibc 实现。
### ain-loader — APK 加载器 (`src/loader/`)
- 将 APK (ZIP) 归档文件解压到 `~/.ain/apps//`
- 解析二进制 AXML (`AndroidManifest.xml`) —— 基于分块的解析器，处理字符串池、起始元素、属性、命名空间
- 通过 APK 中的 `lib//` 条目自动检测目标架构
- 构建 `LD_PRELOAD` 链和 `LD_LIBRARY_PATH` 环境
- 通过适当的沙箱机制生成应用进程
### ain-runtime — ART 桥接 (`src/runtime/`)
- 通过 `dlopen` 加载 `libart.so`（从 AOSP 构建、模拟器镜像或设备中获取）
- 调用 `JNI_CreateJavaVM` 来引导启动 Dalvik/ART 虚拟机
- 加载 `classes.dex` 文件以执行 Java/Kotlin 字节码
- 提供供 C/C++ 原生代码回调 Java 的 JNI 桥接函数
### ain-binder — IPC 守护进程 (`src/binder/`)
- 基于 Unix domain sockets 的自定义 IPC 协议
- 8 字节固定长度的二进制头：`[service_id:2][request_code:2][payload_len:4]`
- 服务注册表（添加/查找/列出/移除）
- 将请求转发给已注册守护进程处理程序的事务路由器
- 通过 `tokio` 实现 Async I/O
### ain-graphics — 图形合成器 (`src/graphics/`)
- 使用 `wayland-client` + `wayland-protocols` 的 Wayland 显示服务器
- ANGLE (Almost Native Graphics Layer Engine) 将 OpenGL ES 转换为 Vulkan
- 带有共享内存 (`wl_buffer`) 的三缓冲模型，实现流畅渲染
- 帧同步：`eglSwapBuffers` → `wl_surface.commit` → 呈现
### ain-services — 系统守护进程 (`src/services/`)
- **ActivityManager**：Activity 生命周期、intent 路由、应用进程管理
- **PackageManager**：APK 注册、权限管理、组件查询
- **WindowManager**：窗口层次结构、输入分发、焦点管理
### ain (CLI) — 命令行工具 (`tools/ain/`)
```
USAGE:
ain
COMMANDS:
run Launch an installed application
install Install an APK file
list List installed applications
info Show application details
start Start the background daemon
stop Stop the background daemon
doctor Run system diagnostics
help Print this message or help for a subcommand
FLAGS:
-h, --help Print help information
-v, --version Print version information
```
## 🔧 安装说明
### 依赖项
| 依赖项 | 版本 | 用途 |
|-----------|---------|---------|
| **Linux kernel** | ≥ 5.10 | Namespaces, seccomp, memfd |
| **Wayland** | ≥ 1.20 | 显示服务器协议 |
| **Vulkan** | ≥ 1.2 | GPU 计算和渲染 |
| **glibc** | ≥ 2.35 | 核心系统库 |
| **Rust** | ≥ 1.85 (2024 edition) | 构建系统 |
| **GCC** | ≥ 12 | C shim 编译 |
| **Box64** (可选) | ≥ 0.3 | ARM64→x86_64 转换 |
| **ANGLE** (可选) | 最新 | OpenGL ES→Vulkan 转换 |
| **ART** (可选) | AOSP 15+ | DEX 字节码执行 |
### 从源码构建
```
# 克隆
git clone https://github.com/ain-project/ain.git
cd ain
# 构建所有内容 (Rust crates + C shims)
make build
# 运行测试
make test
# 安装到系统范围
sudo make install
```
### 验证安装
```
ain doctor
```
此步骤会检查：Wayland 显示、Vulkan ICD 加载器、Box64 二进制文件（如果需要 ARM 支持）、ART 库以及 Ain shim 的完整性。
## 🧪 测试
```
# 运行所有测试
make test
# 仅 Rust 单元测试
cargo test --workspace
# 仅 C shim 测试
make -C src/shims test
# 集成测试
make test-integration
```
当前测试覆盖率：
- `ain-loader`：**56 个测试** — APK 解析、AXML 分块类型、架构检测、环境构建、进程管理
- `ain-runtime`：**57 个测试** — JNI 包装器、DEX 解析器、ART 桥接、zygote 进程、库导出
- `ain-graphics`：**20 个测试** — 合成器状态机、Wayland 显示设置、EGL 上下文管理、缓冲区生命周期
**总计：133 个测试 —— 全部通过。**
## 📚 文档
完整的文档套件包含 **22 份详细文档**，涵盖了每一个子系统：
| 文档 | 描述 |
|----------|-------------|
| [架构](docs/02-architecture.md) | 系统架构和组件交互 |
| [Shim 设计指南](docs/09-shim-design-guide.md) | LD_PRELOAD 拦截的工作原理，RTLD_NEXT 模式 |
| [IPC 协议](docs/10-ipc-protocol.md) | 二进制传输格式、服务代码、错误处理 |
| [APK 格式](docs/11-apk-format.md) | 带有十六进制图表的二进制 AXML、DEX、ARSC 格式参考 |
| [图形流水线](docs/12-graphics-pipeline.md) | GLES→ANGLE→Vulkan→Wayland 流程，三缓冲 |
| [Rust/C FFI](docs/13-rust-c-ffi.md) | `extern "C"`, `#[repr(C)]`, opaque pointers, 内存所有权 |
| [测试指南](docs/14-testing.md) | 测试策略、测试套件设置、覆盖率目标 |
| [性能](docs/15-performance.md) | APK 缓存、符号缓存、脏矩形、Box64 调优 |
| [安全与隔离](docs/16-security-isolation.md) | 进程隔离、seccomp、RLIMIT、权限系统 |
| [故障排除](docs/17-troubleshooting.md) | 常见问题、GDB/strace/valgrind、常见问题解答 |
| [贡献指南](docs/18-contributing.md) | 代码风格、提交约定、PR 流程 |
| [术语表](docs/19-glossary.md) | 60 多个 A-Z 定义 |
| [依赖指南](docs/20-dependency-guide.md) | 为 Arch, Ubuntu, Fedora 安装所有依赖 |
| [Box64 集成](docs/21-box64-integration.md) | DynaRec，LD_PRELOAD + Box64 交互，应用专属配置 |
| [ART 运行时移植](docs/22-art-runtime-port.md) | 采用 ART 的 7 阶段路线图 |
| [SRS](
Ain — **And**roid **IN**ux：在 Linux 上运行 Android 应用
[](https://github.com/Kokuuuuuun/android-inux/actions/workflows/ci.yml)
[](https://www.rust-lang.org)
[](LICENSE)
[]()
**Ain** = **And**roid **IN**ux。它是一个开源兼容层，可直接在 Linux x86_64 上运行 Android APK —— **无需模拟器，无需容器，无需虚拟机**。你可以把它当作 Linux 中的 Android：就像 Wine 将 Windows API 调用转换为 POSIX 调用一样，Ain 通过结合 LD_PRELOAD shim 库、Box64 动态二进制转换以及重新实现的 Android 守护进程，将 Android 的 Bionic libc、Binder IPC、SurfaceFlinger 和系统服务转换为原生的 Linux 调用。
## ✨ 设计理念
Android 应用本质上只是带有特定 Android 运行环境的 Linux 进程。Ain 利用了这一点，直接将应用所期望的 Android API 映射到原生 Linux 的对应实现上：
| Android 组件 | Ain 转换 | 机制 |
|------------------|----------------|-----------|
| **Bionic libc** | glibc | LD_PRELOAD shim (`libbionic.so`) |
| **Binder IPC** | Unix domain sockets | `ain-binder` 守护进程 + `libbinder.so` |
| **ART / Dalvik** | 原生 ART 加载 | `ain-runtime` 桥接（通过 `dlopen` 加载 `libart.so`） |
| **SurfaceFlinger** | Wayland compositor | `ain-graphics` 守护进程 + ANGLE |
| **OpenGL ES** | Vulkan | ANGLE 转换层 |
| **系统服务** | 自定义守护进程 | `ain-services` (ActivityManager, PackageManager, WindowManager) |
| **ARM64 .so 文件** | x86_64 | Box64 动态重编译 |
## 🚀 项目状态
| 组件 | Crate | 状态 | 描述 |
|-----------|-------|--------|-------------|
| **APK 加载器** | `ain_loader` | ✅ **可用** | ZIP 解压、AXML 清单解析、`LD_PRELOAD` 环境设置 |
| **C Shim 库** | `ain-shims` | ⚠️ **已编译** | 9 个拦截 Android API 的共享库 (libbionic, liblog, libandroid, libbinder, libEGL, libGLESv2, libui, libgui, libcutils) |
| **ART 运行时桥接** | `ain-runtime` | 🔧 **开发中** | 通过 `dlopen` 加载 `libart.so`，`JNI_CreateJavaVM`，DEX 类加载，JNI 桥接 |
| **Binder IPC 守护进程** | `ain-binder` | 🔧 **开发中** | 基于 Unix socket 的服务注册表和带有 8 字节二进制头协议的事务路由器 |
| **图形合成器** | `ain-graphics` | 🔧 **开发中** | Wayland 显示服务器，ANGLE/Vulkan 渲染桥接，三缓冲模型 |
| **系统服务** | `ain-services` | 🔧 **开发中** | 基于 IPC 的 ActivityManager、PackageManager、WindowManager 守护进程 |
| **CLI** | `ain` | 🔧 **开发中** | `ain run`, `ain install`, `ain list`, `ain doctor`, `ain start`, `ain stop` |
### 当前进度里程碑：v0.1.0 — "能够加载"
- [x] APK 解压和 AndroidManifest.xml 二进制解析 (AXML)
- [x] 9 个 LD_PRELOAD shim 库编译并运行成功
- [x] 带有 `LD_PRELOAD` / `LD_LIBRARY_PATH` 配置的环境设置
- [x] 包含 6 个 crates + CLI 二进制文件的 Rust 工作区
- [x] 133 个单元测试 (ain-loader: 56, ain-runtime: 57, ain-graphics: 20)
- [x] CI pipeline (GitHub Actions: Rust 构建+测试，C shim 构建+测试，lint)
- [ ] 用于 ARM64→x86_64 转换的 Box64 集成
- [ ] ART 运行时桥接加载真实的 DEX 文件
- [ ] E2E：启动一个 "Hello World" APK
## 🏗️ 架构概述
Ain 作为一个 **4 层系统** 运行，逐步将 Android 接口转换为 Linux 的对应实现：
```
┌─────────────────────────────────────────────────────────┐
│ Android APK │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │classes.dex│ │ .so libs │ │ AndroidManifest.xml │ │
│ │ (DEX) │ │ (ARM/x86)│ │ (AXML binary) │ │
│ └────┬─────┘ └────┬─────┘ └──────────────────────┘ │
└───────┼──────────────┼──────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────┐
│ Layer 1: LD_PRELOAD C Shims (libbionic, liblog, ...) │
│ Translates Android libc/system APIs → glibc natively │
│ Box64 translates ARM64 .so → x86_64 (DynaRec) │
├─────────────────────────────────────────────────────────┤
│ Layer 2: Rust Daemons (binder, services, graphics) │
│ IPC via Unix sockets (8-byte binary header protocol) │
├─────────────────────────────────────────────────────────┤
│ Layer 3: ART Runtime Bridge (libart.so via dlopen) │
│ JNI_CreateJavaVM → DEX class loading → Java execution │
├─────────────────────────────────────────────────────────┤
│ Layer 4: Linux Native (glibc, Wayland, Vulkan, ALSA) │
└─────────────────────────────────────────────────────────┘
```
### 数据流：启动应用
```
ain run com.example.app
│
▼
┌────────────────┐
│ ain-loader │ 1. Extract APK to ~/.ain/apps/标签：Android, DSL, 二进制翻译, 兼容层, 可视化界面, 图形渲染, 系统级开发