在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

topjohnwu/Magisk

菜单

开发者指南

相关源文件

本指南面向想要使用 Magisk 的开发者，无论是为 Magisk 本身做贡献，开发模块，还是构建自定义 Magisk 发行版。它从开发者的角度概述了 Magisk 的架构，解释了构建系统，并详细说明了如何开始开发。

有关创建 Magisk 模块的详细信息，请参阅 模块开发。有关完整的构建说明，请参阅 从源码构建。

开发环境设置

在开发 Magisk 之前，您需要设置好您的环境。

支持的平台

Magisk 可以在以下平台上构建：

  • Linux x64
  • macOS x64 (Intel)
  • macOS arm64 (Apple Silicon)
  • Windows x64 (需启用开发者模式以支持符号链接)

先决条件

  • Python 3.8+：用于构建脚本
  • Git：用于源代码控制和仓库管理
  • Android Studio：用于 Android 应用开发
  • 环境变量:
    • ANDROID_HOME：设置为您的 Android SDK 文件夹
    • ANDROID_STUDIO：可选，用于使用捆绑的 JDK
  • JDK 17：可通过 Android Studio 或单独设置

仓库设置

来源：docs/build.md4-26 build.gradle.kts1-8 buildSrc/build.gradle.kts1-35

Magisk 构建系统

Magisk 使用 Python 构建脚本和 Gradle 的组合作为其构建系统。理解这个架构对于开发者至关重要。

构建系统架构

关键构建文件

  • build.py：主 Python 脚本，负责协调构建过程
  • buildSrc/src/main/java/Setup.kt：包含 Kotlin 构建配置
  • app/build.gradle.kts：主应用程序的 Gradle 配置
  • native/build.gradle.kts：原生组件的配置
  • gradle.properties：全局 Gradle 配置，包括版本信息
    magisk.versionCode=28103
magisk.stubVersion=40
magisk.ondkVersion=r29.1

构建命令

来源：buildSrc/src/main/java/Setup.kt1-497 gradle.properties1-35 docs/build.md28-40

模块开发概述

Magisk 模块使开发者能够自定义 Android 系统。理解它们的结构和生命周期至关重要。

模块结构与集成

模块结构详情

Magisk 模块是 /data/adb/modules 下的一个文件夹，具有以下结构：

/data/adb/modules/$MODID/
├── module.prop         # Module metadata
├── system/             # Files to be mounted
├── zygisk/             # Zygisk native libraries (optional)
├── post-fs-data.sh     # Post-fs-data stage script (optional)
├── service.sh          # Late start service script (optional)
├── system.prop         # System properties (optional)
├── sepolicy.rule       # Custom SEPolicy rules (optional)
├── uninstall.sh        # Uninstallation script (optional)
└── skip_mount          # Flag to disable mounting (optional)

模块安装流程

来源：docs/guides.md16-117 docs/guides.md141-242

原生组件架构

理解 Magisk 的原生组件对于开发核心功能至关重要。

原生组件功能

  1. magisk：主二进制文件，具有多种功能

    • root 访问管理
    • 模块管理
    • 属性操作
    • 包含 su 和 resetprop 应用程序

  2. magiskinit：启动初始化

    • 替换 init，作为第一个运行的程序
    • 修补 SELinux 策略
    • 设置 Magisk 环境
    • 启动 Magisk 守护进程

  3. magiskboot：启动镜像操作

    • 解压/重新打包启动镜像
    • 修补内核和 ramdisk
    • 处理各种压缩格式
    • 修改 DTB 文件

  4. magiskpolicy：SELinux 策略修改

    • 修改二进制策略文件
    • 为 Magisk 组件添加规则
    • 为 Magisk 创建特殊域

来源：docs/tools.md1-234 native/build.gradle.kts1-33

Magisk 启动流程

理解 Magisk 的启动流程对于开发模块和集成至关重要。

启动脚本执行

Magisk 以两种不同的模式执行脚本：

  1. post-fs-data 模式 (阻塞式)

    • 在完成（或超时）之前暂停启动进程
    • 在模块挂载前运行
    • 位于 /data/adb/post-fs-data.d/ 或模块的 post-fs-data.sh
    • 仅在必要时使用

  2. late_start service 模式 (非阻塞式)

    • 与启动进程的其余部分并行运行
    • 推荐用于大多数脚本
    • 位于 /data/adb/service.d/ 或模块的 service.sh

所有脚本都在 Magisk 的 BusyBox ash shell 中运行，并启用“独立模式”。

来源：docs/guides.md243-269 docs/details.md76-95

高级开发主题

SELinux 策略管理

Magisk 修补 SELinux 策略以启用 root 功能

  1. Magisk SELinux 域:

    • magisk 域 (permissive)
    • magisk_file 类型 (所有域可访问)
    • magisk_client 用于使用 root 的进程

  2. 模块中的 SEPolicy:

    • 在 sepolicy.rule 文件中添加自定义规则
    • 每行是一个策略语句
    • 格式遵循 magiskpolicy 语法

系统属性操作

resetprop 工具允许进行高级属性操作

  1. 特性:

    • 修改只读 (ro.*) 属性
    • 删除属性
    • 处理持久属性

  2. 在模块中使用:

    • 使用 system.prop 文件进行简单修改
    • 在脚本中使用 resetprop 命令处理高级情况

来源：docs/details.md96-113 docs/tools.md306-317

调试和测试

日志与诊断

  1. 调试模式:

    • 使用调试选项构建：./build.py debug
    • 在 Magisk 应用设置中启用调试日志记录

  2. 日志位置:

    • /cache/magisk.log 或 /data/cache/magisk.log
    • 直接查看或从 Magisk 应用查看

  3. 模拟器测试:

    • 使用 ./build.py emulator <APK路径> 在模拟器中进行测试
    • 请注意，修改在重启后不会持久化

常见问题

  1. 模块开发:

    • 检查脚本是否以代码 0 退出
    • 验证文件权限
    • 分别测试每个组件

  2. 构建问题:

    • 确保所有先决条件都已安装
    • 检查构建日志以获取具体错误
    • 验证 NDK 和 SDK 版本是否符合要求

来源：docs/faq.md1-30 docs/build.md75-81

贡献指南

为 Magisk 做贡献时

  1. 代码质量:

    • 遵循现有的代码风格
    • 在提交前进行充分测试
    • 记录任何新功能或更改

  2. Pull requests:

    • 创建集中式的更改
    • 包含清晰的描述
    • 确保代码成功构建

  3. 翻译贡献:

    • 编辑相应的字符串资源文件
      • app/core/src/main/res/values/strings.xml
      • app/stub/src/main/res/values/strings.xml

来源：README.MD32-50

开发者资源