From 0928be80ebe52211728f5d55e56f4561b3eacb1a Mon Sep 17 00:00:00 2001 From: JingMatrix Date: Mon, 9 Dec 2024 13:25:48 +0100 Subject: [PATCH 1/6] Add troubleshooting guide --- TROUBLESHOOT.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 TROUBLESHOOT.md diff --git a/TROUBLESHOOT.md b/TROUBLESHOOT.md new file mode 100644 index 000000000..6301c5192 --- /dev/null +++ b/TROUBLESHOOT.md @@ -0,0 +1,28 @@ +# Before we start the troubleshooting + +1. Please flash the debug version of the latest CI build in [GitHub Actions](https://github.com/JingMatrix/LSPosed/actions), which could have fixed the problem for you. Moreover, debug logs are necessary for maintainers to provide their helps. However, make sure that you pick up builds from the `master` branch instead of some working-in-progress pull-requests. +2. For non-Magisk users, please flash the latest Zygisk module (debug version if possible), such as [ReZygisk](https://github.com/PerformanC/ReZygisk) or [ZygiskNext](https://github.com/Dr-TSNG/ZygiskNext/releases). The author [JingMatrix](https://github.com/JingMatrix) also contributes to ReZygisk. + +# Status notification for LSPosed manger is not shown + +Update your root manager and use the `Action` button to open LSPosed manger + +# LSPosed manger cannot be opened + +1. Grant root permission to the system `Shell`(com.android.shell) application. +2. Install LSPosed manger as a user application using the following command: +``` +adb shell su -c cp /data/adb/modules/zygisk_lsposed/manager.apk /data/local/tmp && adb pull /data/local/tmp/manager.apk && adb install ./manager.apk +``` +3. Open manager as a normal application from your launcher. + +# How to provide useful logs before asking helps? + +1. Please go through the previous instructions to open LSPosed manager successfully, and upload the generated logs in your issue. +2. LSPosed manager will automatically save logs of the previous user session. Taking good advantage of the feature can help maintainers to find out a specific bug introduced in some single commit. +3. In case that the LSPosed manager still cannot be opened, we need to the following logs (file `lsposed.log`) from `adb logcat`: +``` +adb logcat -s Magisk lspd nativeloader AndroidRuntime LSPosed LSPosed-Bridge LSPlant LSPosedContext zygisk64 LSPlt Dobby LSPosedService '*:F' > lsposed.log +``` +4. The above `adb logcat` command is meant to capture the booting logs of LSPosed. Hence, one should connect the device with computer, authorize the `adb` connection, run `adb reboot`, and finally run the previous `adb logcat` command once the phone screen turns on. + From 7452e5ddbbdf63e867d6a151effc842da2ca21da Mon Sep 17 00:00:00 2001 From: JingMatrix Date: Mon, 9 Dec 2024 13:26:12 +0100 Subject: [PATCH 2/6] [skip ci] Add development guild --- DEVELOPMENT.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 DEVELOPMENT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 000000000..1fe294afd --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,5 @@ +# How does LSPosed work ? + +`LSPosed` utilise the `postAppSpecialize` [Zygisk API](https://github.com/topjohnwu/Magisk/blob/master/native/src/core/zygisk/api.hpp) to inject into target process, and provides [Xposed Framework API](https://api.xposed.info/reference/packages.html) for modules to hook Java methods. +We recommend the [Development tutorial](https://github.com/rovo89/XposedBridge/wiki/Development-tutorial) by [rovo89](rovo89) for a better understanding of the purpose of Xposed. +`LSPosed` also provides [Native Hook API](https://github.com/LSPosed/LSPosed/wiki/Native-Hook) to facilite the routine of hooking functions in loaded native libraries. From 6d31aa8b1a4b188a4acdd5d370ff6909b3d8b823 Mon Sep 17 00:00:00 2001 From: JingMatrix Date: Mon, 9 Dec 2024 22:54:10 +0100 Subject: [PATCH 3/6] Update README --- README.md | 35 +++++++++-------------------------- 1 file changed, 9 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 1127bf994..e5546ec2b 100644 --- a/README.md +++ b/README.md @@ -15,42 +15,26 @@ Android 8.1 ~ 15 ## Install 1. Install Magisk v26+ -2. [Download](#download) and install LSPosed in Magisk app +2. [Download](#download) and install LSPosed in Magisk 3. Reboot 4. Open LSPosed manager from notification 5. Have fun :) ## Download -- For stable releases, please go to [Github Releases page](https://github.com/JingMatrix/LSPosed/releases) -- For canary build, please check [Github Actions](https://github.com/JingMatrix/LSPosed/actions/workflows/core.yml?query=branch%3Amaster) +- For stable releases, please go to [GitHub Releases page](https://github.com/JingMatrix/LSPosed/releases) +- For canary build, please check [GitHub Actions](https://github.com/JingMatrix/LSPosed/actions/workflows/core.yml?query=branch%3Amaster) -Note: debug builds are only available in Github Actions. -## Get Help -**Only bug reports from **THE LATEST DEBUG BUILD** will be accepted.** -- GitHub issues: [Issues](https://github.com/JingMatrix/LSPosed/issues/) -- (For Chinese speakers) 本项目只接受英语**标题**的issue。如果您不懂英语，请使用[翻译工具](https://www.deepl.com/zh/translator) +Note: debug builds are only available in GitHub Actions. -## For Developers +## Documentations -Developers are welcome to write Xposed modules with hooks based on LSPosed Framework. A module based on LSPosed framework is fully compatible with the original Xposed Framework, and vice versa, a Xposed Framework-based module will work well with LSPosed framework too. +- If you encounter problems while using LSPosed, please follow the [TROUBLESHOOT guide](TROUBLESHOOT.md). +- To understand the mechanism of LSPosed, please read the [DEVELOPMENT introduction](DEVELOPMENT.md). +- Xposed modules submit to [LSPosed Module Repository](https://github.com/Xposed-Modules-Repo) will be shown in the LSPosed manager. +- UI translations are managed in [the Crowdin project](https://crowdin.com/project/lsposed_jingmatrix). -- [Xposed Framework API](https://api.xposed.info/) - -We use our own module repository. We welcome developers to submit modules to our repository, and then modules can be downloaded in LSPosed. - -- [LSPosed Module Repository](https://github.com/Xposed-Modules-Repo) - -## Community Discussion - -- Telegram: [@LSPosed](https://t.me/s/LSPosed) - -Notice: These community groups don't accept any bug report, please use [Get help](#get-help) to report. - -## Translation Contributing - -You can contribute translation [here](https://crowdin.com/project/lsposed_jingmatrix). ## Credits @@ -64,7 +48,6 @@ You can contribute translation [here](https://crowdin.com/project/lsposed_jingma - ~[SandHook](https://github.com/ganyao114/SandHook/): ART hooking framework for SandHook variant~ - ~[YAHFA](https://github.com/rk700/YAHFA): previous ART hooking framework~ - ~[dexmaker](https://github.com/linkedin/dexmaker) and [dalvikdx](https://github.com/JakeWharton/dalvik-dx): to dynamically generate YAHFA hooker classes~ -- ~[DexBuilder](https://github.com/LSPosed/DexBuilder): to dynamically generate YAHFA hooker classes~ ## License From e6985ecb71ec1b85936b6e8294efbd3a7070d697 Mon Sep 17 00:00:00 2001 From: JingMatrix Date: Mon, 9 Dec 2024 22:54:29 +0100 Subject: [PATCH 4/6] Adjust section titles --- TROUBLESHOOT.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/TROUBLESHOOT.md b/TROUBLESHOOT.md index 6301c5192..5e392335f 100644 --- a/TROUBLESHOOT.md +++ b/TROUBLESHOOT.md @@ -1,13 +1,18 @@ -# Before we start the troubleshooting +# How to troubleshoot LSPosed? + +When LSPosed doesn't work as expected on your device, don't panic. +The following guide should help you out for most cases. + +## Before we start the troubleshooting 1. Please flash the debug version of the latest CI build in [GitHub Actions](https://github.com/JingMatrix/LSPosed/actions), which could have fixed the problem for you. Moreover, debug logs are necessary for maintainers to provide their helps. However, make sure that you pick up builds from the `master` branch instead of some working-in-progress pull-requests. 2. For non-Magisk users, please flash the latest Zygisk module (debug version if possible), such as [ReZygisk](https://github.com/PerformanC/ReZygisk) or [ZygiskNext](https://github.com/Dr-TSNG/ZygiskNext/releases). The author [JingMatrix](https://github.com/JingMatrix) also contributes to ReZygisk. -# Status notification for LSPosed manger is not shown +## Status notification for LSPosed manger is not shown Update your root manager and use the `Action` button to open LSPosed manger -# LSPosed manger cannot be opened +## LSPosed manger cannot be opened 1. Grant root permission to the system `Shell`(com.android.shell) application. 2. Install LSPosed manger as a user application using the following command: @@ -16,7 +21,7 @@ adb shell su -c cp /data/adb/modules/zygisk_lsposed/manager.apk /data/local/tmp ``` 3. Open manager as a normal application from your launcher. -# How to provide useful logs before asking helps? +## How to provide useful logs before asking helps? 1. Please go through the previous instructions to open LSPosed manager successfully, and upload the generated logs in your issue. 2. LSPosed manager will automatically save logs of the previous user session. Taking good advantage of the feature can help maintainers to find out a specific bug introduced in some single commit. @@ -26,3 +31,5 @@ adb logcat -s Magisk lspd nativeloader AndroidRuntime LSPosed LSPosed-Bridge LS ``` 4. The above `adb logcat` command is meant to capture the booting logs of LSPosed. Hence, one should connect the device with computer, authorize the `adb` connection, run `adb reboot`, and finally run the previous `adb logcat` command once the phone screen turns on. + +Notes for Chinese speakers: 本项目只接受英语**标题**的issue。如果您不懂英语，请使用[翻译工具](https://www.deepl.com/zh/translator). From 430429132c2183feeceac1b5da3e9900fabb3a68 Mon Sep 17 00:00:00 2001 From: JingMatrix Date: Mon, 9 Dec 2024 23:05:49 +0100 Subject: [PATCH 5/6] [skip ci] Update development docs --- DEVELOPMENT.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 1fe294afd..14441ec24 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,5 +1,13 @@ -# How does LSPosed work ? +# Development introduction to LSPosed -`LSPosed` utilise the `postAppSpecialize` [Zygisk API](https://github.com/topjohnwu/Magisk/blob/master/native/src/core/zygisk/api.hpp) to inject into target process, and provides [Xposed Framework API](https://api.xposed.info/reference/packages.html) for modules to hook Java methods. -We recommend the [Development tutorial](https://github.com/rovo89/XposedBridge/wiki/Development-tutorial) by [rovo89](rovo89) for a better understanding of the purpose of Xposed. -`LSPosed` also provides [Native Hook API](https://github.com/LSPosed/LSPosed/wiki/Native-Hook) to facilite the routine of hooking functions in loaded native libraries. +As a Zygisk module, LSPosed utilizes the `postAppSpecialize` [API](https://github.com/topjohnwu/Magisk/blob/master/native/src/core/zygisk/api.hpp) to inject into target processes (Android applications), and provides [Xposed Framework API](https://api.xposed.info/reference/packages.html) for modules to hook their Java methods. +We strongly advise developers to follow the [Development tutorial](https://github.com/rovo89/XposedBridge/wiki/Development-tutorial) by [rovo89](https://github.com/rovo89) to understand the purpose of Xposed. +Moreover, LSPosed also provides [Native Hook API](https://github.com/LSPosed/LSPosed/wiki/Native-Hook) to facilite the routine of hooking functions in loaded native libraries of target processes. + + +## Introduction to Zygisk + +The name Zygisk comes from Zygote and Magisk, referring to [a set of APIs](https://github.com/topjohnwu/Magisk/blob/f56ea52932a8d927b1d96fd2d7c7e634c8b6c710/native/jni/zygisk/api.hpp) exposed to module developers and thus allowing them to inject custom codes into any Android processes. +Zygisk was first introduced in [Magisk v24.1](https://github.com/topjohnwu/Magisk/releases/tag/v24.1), and it is currently the most widely used interface of Zygote injection. +[Riru](https://github.com/RikkaApps/Riru) provides an alternative interface of Zygote injection, which is achieved now though it was the inspiration for Zygisk. +JingMatrix/LSPosed dropped its support of Riru in [v1.10.1](https://github.com/JingMatrix/LSPosed/releases/tag/v1.10.1), so we will focus on understanding Zygisk only. From 933199ca54a15d223ce80695320b80d2a1276b7e Mon Sep 17 00:00:00 2001 From: JingMatrix Date: Sat, 28 Dec 2024 07:27:44 +0100 Subject: [PATCH 6/6] [skip ci] Update log tags --- TROUBLESHOOT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TROUBLESHOOT.md b/TROUBLESHOOT.md index 5e392335f..7ba81cda8 100644 --- a/TROUBLESHOOT.md +++ b/TROUBLESHOOT.md @@ -27,7 +27,7 @@ adb shell su -c cp /data/adb/modules/zygisk_lsposed/manager.apk /data/local/tmp 2. LSPosed manager will automatically save logs of the previous user session. Taking good advantage of the feature can help maintainers to find out a specific bug introduced in some single commit. 3. In case that the LSPosed manager still cannot be opened, we need to the following logs (file `lsposed.log`) from `adb logcat`: ``` -adb logcat -s Magisk lspd nativeloader AndroidRuntime LSPosed LSPosed-Bridge LSPlant LSPosedContext zygisk64 LSPlt Dobby LSPosedService '*:F' > lsposed.log +adb logcat -s Magisk lspd nativeloader AndroidRuntime LSPosed LSPosed-Bridge LSPlant LSPosedContext LSPlt LSPosedService Dobby '*:F' zygiskd64 zygisk-core64 zygisk-ptrace64 zygiskd32 zygisk-core32 zygisk-ptrace32 > lsposed.log ``` 4. The above `adb logcat` command is meant to capture the booting logs of LSPosed. Hence, one should connect the device with computer, authorize the `adb` connection, run `adb reboot`, and finally run the previous `adb logcat` command once the phone screen turns on.