android/SukiSU-Ultra
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: update documentation for the website (#1750)

Browse Source 
Description:

I was originally browsing through project's FAQ on the
[website](https://kernelsu.org/) and noticed a few discrepancies across
the text.<br>I edited them out, and once having finished with the FAQ, I
looked through other website pages as well.

Changes:

- updated documentation for the project's website (English version).

--
P.S. I actually appreciate the partial documentation on GKI and in-depth
Android mechanisms present in it. While there is of course documentation
from Google, it is nice to have guidelines from a more practical
standpoint.
This commit is contained in:
Joseph P
2024-05-21 01:35:51 +00:00
committed by GitHub
parent 9c2e48bb3e
commit 82d965f44c
10 changed files with 144 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
website/docs/guide/module.md
View File

@@ -6,20 +6,20 @@ The module mechanism of KernelSU is almost the same as that of Magisk. If you ar
## WebUI
KernelSU's modules support displaying interfaces and interacting with users, please refer to the [WebUI documentation](module-webui.md).
KernelSU's modules support displaying interfaces and interacting with users. For more, please refer to [WebUI documentation](module-webui.md).
## Busybox
KernelSU ships with a feature complete BusyBox binary (including full SELinux support). The executable is located at `/data/adb/ksu/bin/busybox`. KernelSU's BusyBox supports runtime toggle-able "ASH Standalone Shell Mode". What this standalone mode means is that when running in the `ash` shell of BusyBox, every single command will directly use the applet within BusyBox, regardless of what is set as `PATH`. For example, commands like `ls`, `rm`, `chmod` will **NOT** use what is in `PATH` (in the case of Android by default it will be `/system/bin/ls`, `/system/bin/rm`, and `/system/bin/chmod` respectively), but will instead directly call internal BusyBox applets. This makes sure that scripts always run in a predictable environment and always have the full suite of commands no matter which Android version it is running on. To force a command _not_ to use BusyBox, you have to call the executable with full paths.
KernelSU ships with a feature-complete BusyBox binary (including full SELinux support). The executable is located at `/data/adb/ksu/bin/busybox`. KernelSU's BusyBox supports runtime toggle-able "ASH Standalone Shell Mode". What this standalone mode means is that when running in the `ash` shell of BusyBox, every single command will directly use the applet within BusyBox, regardless of what is set as `PATH`. For example, commands like `ls`, `rm`, `chmod` will **NOT** use what is in `PATH` (in the case of Android by default it will be `/system/bin/ls`, `/system/bin/rm`, and `/system/bin/chmod` respectively), but will instead directly call internal BusyBox applets. This makes sure that scripts always run in a predictable environment and always have the full suite of commands no matter which Android version it is running on. To force a command _not_ to use BusyBox, you have to call the executable with full paths.
Every single shell script running in the context of KernelSU will be executed in BusyBox's `ash` shell with standalone mode enabled. For what is relevant to 3rd party developers, this includes all boot scripts and module installation scripts.
For those who want to use this "Standalone Mode" feature outside of KernelSU, there are 2 ways to enable it:
1. Set environment variable `ASH_STANDALONE` to `1`<br>Example: `ASH_STANDALONE=1 /data/adb/ksu/bin/busybox sh <script>`
1. Set environment variable `ASH_STANDALONE` to `1` .<br>Example: `ASH_STANDALONE=1 /data/adb/ksu/bin/busybox sh <script>`
2. Toggle with command-line options:<br>`/data/adb/ksu/bin/busybox sh -o standalone <script>`
To make sure all subsequent `sh` shell executed also runs in standalone mode, option 1 is the preferred method (and this is what KernelSU and the KernelSU manager internally use) as environment variables are inherited down to child processes.
To make sure all subsequent `sh` shell executed also runs in standalone mode, option 1 is the preferred method (and this is what KernelSU and the KernelSU manager use internally) as environment variables are inherited down to child processes.
::: tip difference with Magisk
@@ -99,10 +99,10 @@ author=<string>
description=<string>
```
- `id` has to match this regular expression: `^[a-zA-Z][a-zA-Z0-9._-]+$`<br>
ex: ✓ `a_module`, ✓ `a.module`, ✓ `module-101`, ✗ `a module`, ✗ `1_module`, ✗ `-a-module`<br>
- `id` has to match this regular expression: `^[a-zA-Z][a-zA-Z0-9._-]+$` .<br>
Example: ✓ `a_module`, ✓ `a.module`, ✓ `module-101`, ✗ `a module`, ✗ `1_module`, ✗ `-a-module`<br>
This is the **unique identifier** of your module. You should not change it once published.
- `versionCode` has to be an **integer**. This is used to compare versions
- `versionCode` has to be an **integer**. This is used to compare versions.
- Others that weren't mentioned above can be any **single line** string.
- Make sure to use the `UNIX (LF)` line break type and not the `Windows (CR+LF)` or `Macintosh (CR)`.
@@ -177,12 +177,12 @@ module.zip
```
:::warning
KernelSU module is NOT supported to be installed in custom recovery!!
KernelSU module is NOT supported to be installed via a custom recovery!!
:::
### Customization
If you need to customize the module installation process, optionally you can create a script in the installer named `customize.sh`. This script will be _sourced_ (not executed!) by the module installer script after all files are extracted and default permissions and secontext are applied. This is very useful if your module require additional setup based on the device ABI, or you need to set special permissions/secontext for some of your module files.
If you need to customize the module installation process, optionally you can create a script in the installer named `customize.sh`. This script will be _sourced_ (not executed!) by the module installer script after all files are extracted and default permissions and secontext are applied. This is very useful if your module requires additional setup based on the device ABI, or you need to set special permissions/secontext for some of your module files.
If you would like to fully control and customize the installation process, declare `SKIPUNZIP=1` in `customize.sh` to skip all default installation steps. By doing so, your `customize.sh` will be responsible to install everything by itself.
@@ -191,16 +191,16 @@ The `customize.sh` script runs in KernelSU's BusyBox `ash` shell with "Standalon
#### Variables
- `KSU` (bool): a variable to mark that the script is running in the KernelSU environment, and the value of this variable will always be true. You can use it to distinguish between KernelSU and Magisk.
- `KSU_VER` (string): the version string of current installed KernelSU (e.g. `v0.4.0`)
- `KSU_VER_CODE` (int): the version code of current installed KernelSU in userspace (e.g. `10672`)
- `KSU_KERNEL_VER_CODE` (int): the version code of current installed KernelSU in kernel space (e.g. `10672`)
- `BOOTMODE` (bool): always be `true` in KernelSU
- `MODPATH` (path): the path where your module files should be installed
- `TMPDIR` (path): a place where you can temporarily store files
- `ZIPFILE` (path): your module's installation zip
- `ARCH` (string): the CPU architecture of the device. Value is either `arm`, `arm64`, `x86`, or `x64`
- `IS64BIT` (bool): `true` if `$ARCH` is either `arm64` or `x64`
- `API` (int): the API level (Android version) of the device (e.g. `23` for Android 6.0)
- `KSU_VER` (string): the version string of currently installed KernelSU (e.g. `v0.4.0`).
- `KSU_VER_CODE` (int): the version code of currently installed KernelSU in userspace (e.g. `10672`).
- `KSU_KERNEL_VER_CODE` (int): the version code of currently installed KernelSU in kernel space (e.g. `10672`).
- `BOOTMODE` (bool): always be `true` in KernelSU.
- `MODPATH` (path): the path where your module files should be installed.
- `TMPDIR` (path): a place where you can temporarily store files.
- `ZIPFILE` (path): your module's installation zip.
- `ARCH` (string): the CPU architecture of the device. Value is either `arm`, `arm64`, `x86`, or `x64`.
- `IS64BIT` (bool): `true` if `$ARCH` is either `arm64` or `x64`.
- `API` (int): the API level (Android version) of the device (e.g., `23` for Android 6.0).
::: warning
In KernelSU, MAGISK_VER_CODE is always 25200 and MAGISK_VER is always v25.2. Please do not use these two variables to determine whether it is running on KernelSU or not.
@@ -234,28 +234,28 @@ set_perm_recursive <directory> <owner> <group> <dirpermission> <filepermission>
## Boot scripts
In KernelSU, scripts are divided into two types based on their running mode: post-fs-data mode and late_start service mode:
In KernelSU, scripts are divided into two types based on their running mode: post-fs-data mode and late_start service mode.
- post-fs-data mode
- This stage is BLOCKING. The boot process is paused before execution is done, or 10 seconds have passed.
- Scripts run before any modules are mounted. This allows a module developer to dynamically adjust their modules before it gets mounted.
- This stage happens before Zygote is started, which pretty much means everything in Android
- This stage happens before Zygote is started, which pretty much means everything in Android.
- **WARNING:** using `setprop` will deadlock the boot process! Please use `resetprop -n <prop_name> <prop_value>` instead.
- **Only run scripts in this mode if necessary.**
- late_start service mode
- This stage is NON-BLOCKING. Your script runs in parallel with the rest of the booting process.
- **This is the recommended stage to run most scripts.**
In KernelSU, startup scripts are divided into two types based on their storage location: general scripts and module scripts:
In KernelSU, startup scripts are divided into two types based on their storage location: general scripts and module scripts.
- General Scripts
- Placed in `/data/adb/post-fs-data.d`, `/data/adb/service.d`, `/data/adb/post-mount.d` or `/data/adb/boot-completed.d`
- Placed in `/data/adb/post-fs-data.d`, `/data/adb/service.d`, `/data/adb/post-mount.d` or `/data/adb/boot-completed.d.`
- Only executed if the script is set as executable (`chmod +x script.sh`)
- Scripts in `post-fs-data.d` runs in post-fs-data mode, and scripts in `service.d` runs in late_start service mode.
- Modules should **NOT** add general scripts during installation
- Modules should **NOT** add general scripts during installation.
- Module Scripts
- Placed in the module's own folder
- Only executed if the module is enabled
- Placed in the module's own folder.
- Only executed if the module is enabled.
- `post-fs-data.sh` runs in post-fs-data mode, `service.sh` runs in late_start service mode, `boot-completed.sh` runs on boot completed, `post-mount.sh` runs on overlayfs mounted.
All boot scripts will run in KernelSU's BusyBox `ash` shell with "Standalone Mode" enabled.