Add native lib debug instructions document

2 files changed, 20 insertions, 0 deletions

diff --git a/android/docs/BuildInstructions.macos.md b/android/docs/BuildInstructions.macos.md
index a88db7f227..78bf345d1d 100644
--- a/android/docs/BuildInstructions.macos.md
+++ b/android/docs/BuildInstructions.macos.md
@@ -98,3 +98,7 @@ native code can be done in Android Studio or using gradle.
 # Build options and configuration
 
 For configuring signing or options to your build continue with the general [build instructions](../BuildInstructions.md).
+
+# Debugging the Rust native code
+
+For tips on how to debug the Rust library code from Android Studio, see the [debug instructions](DebugInstructions.md).
diff --git a/android/docs/DebugInstructions.md b/android/docs/DebugInstructions.md
new file mode 100644
index 0000000000..e4c9100e0e
--- /dev/null
+++ b/android/docs/DebugInstructions.md
@@ -0,0 +1,16 @@
+## Debugging the native libraries in Android Studio with LLDB
+
+1. Make sure the native libraries have been built with debug symbols. If using the `build-apk.sh`
+   script, run `SKIP_STRIPPING=yes ../build-apk.sh --dev-build`.
+2. In Android Studio, go to `Run -> Edit configurations...`
+3. Make sure the `app` configuration is selected.
+4. In the `Debugger` tab, select `Dual (Java + Native)`
+5. Start debugging the app as usual from Android Studio. The app should now stop on a SIGURG signal.
+6. Select the `LLDB` tab in the debugger. Now you can set breakpoints etc, e.g.
+   `breakpoint set -n open_tun`
+7. Before continuing run `pro hand -p true -s false SIGURG`
+8. Click `Resume Program` and the app will resume until the breakpoint is hit.
+
+NOTE: When running LLDB, Android Studio can sometimes get into a state where it will try to
+connect to the debugger when running the app normally, which blocks the app from starting.
+To fix this run `adb shell am clear-debug-app`.