diff --git a/docs/details.md b/docs/details.md index 8d8af7db5..662e1c206 100644 --- a/docs/details.md +++ b/docs/details.md @@ -54,7 +54,7 @@ Some binaries and files should be stored on non-volatile storages in `/data`. In - It is an existing folder on modern Android, so it cannot be used as an indication of the existence of Magisk. - The permission of the folder is by default `700`, owner as `root`, so non-root processes are unable to enter, read, write the folder in any possible way. - The folder is labeled with secontext `u:object_r:adb_data_file:s0`, and very few processes have the permission to do any interaction with that secontext. -- The folder is located in *Device encrypted storage*, so it is accessible as soon as data is properly mounted in FBE (File-Based Encryption) devices. +- The folder is located in _Device encrypted storage_, so it is accessible as soon as data is properly mounted in FBE (File-Based Encryption) devices. ``` SECURE_DIR=/data/adb @@ -114,16 +114,6 @@ Usually, system properties are designed to only be updated by `init` and read-on - `on property:foo=bar` actions registered in `*.rc` scripts will not be triggered if property changes does not go through `property_service`. The default set property behavior of `resetprop` matches `setprop`, which **WILL** trigger events (implemented by first deleting the property then set it via `property_service`). There is a flag `-n` to disable it if you need this special behavior. - persist properties (props that starts with `persist.`, like `persist.sys.usb.config`) are stored in both `prop_area` and `/data/property`. By default, deleting props will **NOT** remove it from persistent storage, meaning the property will be restored after the next reboot; reading props will **NOT** read from persistent storage, as this is the behavior of `getprop`. With the flag `-p`, deleting props will remove the prop in **BOTH** `prop_area` and `/data/property`, and reading props will be read from **BOTH** `prop_area` and persistent storage. -## Magic Mount - -The details of the actual implementation and algorithm of Magic Mount is omitted here, please directly dive into the source code if interested (`core/module.cpp`). - -Even though the mounting logic is very complicated, the final result of Magic Mount is actually pretty simple. For each module, the folder `$MODPATH/system` will be recursively merged into the real `/system`; that is: existing files in the real system will be replaced by the one in modules' system, and new files in modules' system will be added to the real system. - -There is one additional trick you can use: if you place an empty file named `.replace` in any of the folders in a module's system, instead of merging the contents, that folder will directly replace the one in the real system. This will be very handy in some cases, for example swapping out a system app. - -If you want to replace files in `/vendor` or `/product`, please place them under `$MODPATH/system/vendor` or `$MODPATH/system/product`. Magisk will transparently handle both cases, whether vendor or product is a separate partition or not. - ## SELinux Policies Magisk will patch the stock `sepolicy` to make sure root and Magisk operations can be done in a safe and secure way. The new domain `magisk` is effectively permissive, which is what `magiskd` and all root shell will run in. `magisk_file` is a new file type that is setup to be allowed to be accessed by every domain (unrestricted file context). diff --git a/docs/guides.md b/docs/guides.md index 41d78f864..9562efa6b 100644 --- a/docs/guides.md +++ b/docs/guides.md @@ -35,7 +35,7 @@ A Magisk module is a folder placed in `/data/adb/modules` with the structure bel │ │ ├── ... │ │ └── ... │ │ -│ ├── zygisk <--- This folder contains the native libraries to load in zygote +│ ├── zygisk <--- This folder contains the module's Zygisk native libraries │ │ ├── arm64-v8a.so │ │ ├── armeabi-v7a.so │ │ ├── x86.so @@ -114,6 +114,18 @@ Please read the [Boot Scripts](#boot-scripts) section to understand the differen In all scripts of your module, please use `MODDIR=${0%/*}` to get your module's base directory path; do **NOT** hardcode your module path in scripts. If Zygisk is enabled, the environment variable `ZYGISK_ENABLED` will be set to `1`. +#### The `system` folder + +All files you want Magisk to replace/inject for you should be placed in this folder. This folder will be recursively merged into the real `/system`; that is: existing files in the real `/system` will be replaced by the one in modules' `system`, and new files in modules' `system` will be added to the real `/system`. + +There is one trick you can use: if you place an empty file named `.replace` in any of the folders, instead of merging its contents, that folder will directly replace the one in the real system. This can be very handy in some cases, for example swapping out an entire system app. + +If you want to replace files in `/vendor`, `/product`, or `/system_ext`, please place them under `system/vendor`, `system/product`, and `system/system_ext` respectively. Magisk will transparently handle whether these partitions are in a separate partition or not. + +#### Zygisk + +Zygisk is a feature in Magisk that allows advanced module developers to run code directly in every Android applications' processes before they are specialized and start running. For more details about the Zygisk API and building a Zygisk module, please checkout the [Zygisk Module Sample](https://github.com/topjohnwu/zygisk-module-sample) project. + #### system.prop This file follows the same format as `build.prop`. Each line comprises of `[key]=[value]`. @@ -124,10 +136,6 @@ If your module requires some additional sepolicy patches, please add those rules Each line in this file will be treated as a policy statement. For more details about how a policy statement is formatted, please check [magiskpolicy](tools.md#magiskpolicy)'s documentation. -#### The `system` folder - -All files you want Magisk to replace/inject for you should be placed in this folder. Please read through the [Magic Mount](details.md#magic-mount) section to understand how Magisk mount your files. - ## Magisk Module Installer A Magisk Module Installer is a Magisk Module packaged in a zip file that can be flashed in the Magisk app or custom recoveries such as TWRP. An installer has the same file structure as a Magisk module (please check the previous section for more info). The simplest Magisk Module Installer is just a Magisk Module packed in a zip file, with addition to the following files: @@ -221,16 +229,6 @@ The list above will result in the following files being created: `$MODPATH/syste - Due to historical reasons, **DO NOT** add a file named `install.sh` in your module installer. That specific file was previously used and will be treated differently. - **DO NOT** call `exit` at the end of `customize.sh`. The module installer would want to do finalizations. -## Module Tricks - -#### Remove Files - -How to remove a file systemless-ly? To actually make the file _disappear_ is complicated (possible, not worth the effort). Replacing it with a dummy file should be good enough! Create an empty file with the same name and place it in the same path within a module, it shall replace your target file with a dummy file. - -#### Remove Folders - -Same as mentioned above, actually making the folder _disappear_ is not worth the effort. Replacing it with an empty folder should be good enough! A handy trick for module developers is to add the folder you want to remove into the `REPLACE` list within `customize.sh`. If your module doesn't provide a corresponding folder, it will create an empty folder, and automatically add `.replace` into the empty folder so the dummy folder will properly replace the one in `/system`. - ## Boot Scripts In Magisk, you can run boot scripts in 2 different modes: **post-fs-data** and **late_start service** mode. diff --git a/docs/procedures.html b/docs/procedures.html deleted file mode 100644 index 78828b8ff..000000000 --- a/docs/procedures.html +++ /dev/null @@ -1,11 +0,0 @@ - - - - -Magisk Procedures - - -
- - -