模块开发指南​

对于大部分内容，ShiroSU 与Magisk和KernelSU基本保持一致，此处仅介绍不同之处。

Systemless^[1]​

ShiroSU 的 Systemless 是一种类似于 Magisk 的挂载机制，其接口完全兼容 Magisk，例如.replace用法。但 ShiroSU 的挂载机制兼容性更强。是基于动态识别分区实现的。也就是说，模块可以直接通过 Systemless 挂载例如odm以及其他 root 实现无法挂载的分区，无需为此而付出额外的心血。

并且，为了保证更强的安全性，ShiroSU 的 Systemless 会无视模块挂载的文件/目录的 SELinux 上下文、目录的权限以及文件/目录的用户/组，如果文件挂载到了不存在的目录，那么其SELinux 上下文、权限、用户/组均会继承自父目录。通常来说，这些行为不会影响模块的运行，反而有助于提高稳定性。

Shell​

ShiroSU 在此处与其他 root 实现有较大差异，ShiroSU 运行的 Shell 脚本默认并不在BusyBox中以 “独立模式” 运行。

为了提升 Shell 脚本开发的便利性，ShiroSU 使用sush(用 Rust 编写的Bash) 运行 Shell 脚本，并且优先使用uutils(用 Rust 编写的coreutils) 的命令集，以 Magisk 的 BusyBox 作为替补。也就是说，命令优先从 uutils 获取，没有的命令才会从 BusyBox 获取。

由于并不在 BusyBox 中以 “独立模式” 运行，命令都是通过PATH环境变量注入的，请勿在模块的 Shell 脚本内硬编码修改PATH！

环境变量​

为了便于区分，ShiroSU 在模块运行时注入以下变量:

• SSU(布尔值): 在 ShiroSU 环境下运行时，此值将为true。但这并不能代表可以通过$SSU && # code ...来执行代码，应当始终使用[ "$SSU" = true ]或类似方法来检测 ShiroSU
• SSU_VER(字符串): ShiroSU 的版本号 (不包括补丁号)
• SSU_VER_CODE(整数值): ShiroSU 的纯数字版本号 (包括补丁号)

Recovery​

ShiroSU 不支持通过 Recovery 安装模块，并且在模块安装时META-INF/com/google/android/update-binary中的代码不会被执行。

SU 调用​

ShiroSU 的 SU 实现默认附带了一个仅能用于直接执行 Shell 命令的sudo，可以直接通过sudo来执行例如sudo ls /。

sudo仅作为一个简易的su -c替代品而存在，但是任何模块内都不应该通过sudo或su -c执行 Shell 命令！

同样的，任何模块也不应该通过硬编码来获取命令，例如/data/adb/ssu/bin/busybox crond，因为无论是在 BusyBox 的 “独立模式” 还是直接通过PATH注入命令，命令都已经可以直接调用，无需任何硬编码的手动获取行为。

ANSI 转义码^[2]​

ShiroSU 允许在module.prop或 Shell 脚本中使用ANSI 转义码来丰富文本的显示，例如可在module.prop使用如下代码:

id=ssu_cmd_ext
name=Command Set Extension
version=Auto-generated by SSU
versionAnsi=\e[1mAuto-generated\e[0m by SSU
versionCode=1
author=SSU Developers (O.O.M. W.G.)
description=Add coreutils, busybox, and bash to /system/bin.
descriptionAnsi=Add \e[1mcoreutils, busybox, and bash\e[0m to \e[1m/system/bin\e[0m.

使用如上module.prop后，模块在 ShiroSU 管理器中显示时Auto-generated、coreutils, busybox, and bash以及/system/bin均会被加粗。

在module.prop中，可使用nameAnsi、versionAnsi、authorAnsi、descriptionAnsi、actionAnsi来显示包含 ANSI 转义码的文本。

虽然不包含Ansi后缀同样可以使用，但是为了确保兼容性，请这么做。

ShiroSU 是通过顺序解析来读取module.prop中的内容的，所以请确保包含Ansi后缀的值是靠后的。

module.prop​

ShiroSU 管理器有一个机制用来检测module.prop是否损坏或符合规范，如果损坏或不符合规范，ShiroSU 管理器会在该模块的上方显示一个标签。

ShiroSU 管理器具体会检测如下内容:

• module.prop内是否包含不符合语法的内容
• id、name、version、author、description是否为空 (如有带有Ansi后缀的同样检测)
• id是否符合此正则表达式:^[a-zA-Z][a-zA-Z0-9._-]+$
• versionCode是否大于0
• module.prop内是否存在大小写不规范的情况 (ShiroSU 管理器会正常解析，但仍会显示标签)

如果只是module.prop损坏，重装模块通常可解决此问题，如果不符合规范，则需要开发者自行修复以解决此问题。

模块 ConfigUI​

ShiroSU 有一个专门的模块功能配置界面，详见模块 ConfigUI

模块 WebUI​

ShiroSU 与KernelSU同样允许模块使用 WebUI 提供功能，详见模块 WebUI。

其他内容​

除了ANSI 转义码相关内容之外，ShiroSU 管理器还会解析如下内容:

• action: 定义此内容，会在执行操作前显示弹窗，此内容用于描述操作有何作用
• runtimeInfo: 定义此内容，会在模块名称旁边显示可点击图标，此内容为文本文件的模块相对路径/绝对路径，用于描述模块运行时的信息

ShiroSU 管理器还会自动搜索模块目录内是否有符合正则表达式(?i)^(?:license|licence)(?:[-_][A-Za-z0-9]+)?(?:\.(?:txt|md|mkd))?$的文件。如有，则会在模块信息卡片中显示一个许可证标签，点击则会显示模块的许可证内容

内核接口​

ShiroSU 使用/data/adb/ssu/._settings作为内核设置目录，通常包含以下文件:

• ._su_list: 授权使用超级用户权限的列表
• ._bypass_list: 绕过 SELinux 限制的列表
• ._hide_list: 需要隐藏 root 使用痕迹的列表

以上文件均采用二进制 UID(32 位整数) +\0+软件包名格式存储，多个值之间以\n间隔

其他差异​

ShiroSU 会在后续更新中提供模块备份接口、模块更新接口 (在更新时执行原本模块的代码)、模块存储接口等功能，这些内容尚在规划中，会在后续更新中推出。

贡献者

白彩恋 YumeYuka 悠栾

页面历史