diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 00000000000..14441ec24c1 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,13 @@ +# Development introduction to LSPosed + +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. diff --git a/README.md b/README.md index 1127bf994d8..e5546ec2b73 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 diff --git a/TROUBLESHOOT.md b/TROUBLESHOOT.md new file mode 100644 index 00000000000..7ba81cda85b --- /dev/null +++ b/TROUBLESHOOT.md @@ -0,0 +1,35 @@ +# 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 + +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 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. + + +Notes for Chinese speakers: 本项目只接受英语**标题**的issue。如果您不懂英语，请使用[翻译工具](https://www.deepl.com/zh/translator).