** Debugging Emacs on Android.
-Attaching GDB to Emacs running inside the Android application setup
-requires a special script found in the java/ directory, and a suitable
-GDB server binary to be present on the Android device, which is
-present on the free versions of Android. Connecting to the device
-also requires the `adb' (Android Debug Bridge) utility, and telling
-the Android system to resume the Emacs process after startup requires
-the Java debugger (jdb).
+A script located in the java/ directory automates the procedures
+necessary run Emacs under a Gdb session on an Android device connected
+to a computer using USB.
+
+Its requirements are the `adb' (Android Debug Bridge) utility and the
+Java debugger (jdb), utilized to cue the Android system to resume the
+Emacs process after the debugger attaches.
If all three of those tools are present, simply run (from the Emacs
source directory):
../java/debug.sh -- [any extra arguments you wish to pass to gdb]
-After which, upon waiting a while, the GDB prompt will show up.
+Several lines of debug information will be printed, after which the
+Gdb prompt should be displayed.
-If Emacs crashes and "JNI ERROR" shows up in the Android system log,
-then placing a breakpoint on:
+If there is no Gdbserver binary present on the device, then specify
+one to upload, like so:
- break art::JavaVMExt::JniAbort
+ ../java/debug.sh --gdbserver /path/to/gdbserver
-will let you find the source of the crash.
+This Gdbserver should be statically linked or compiled using the
+Android NDK, and must target the same architecture as the debugee
+Emacs binary. Older versions of the Android NDK (such as r24)
+distribute suitable Gdbserver binaries, usually located within
-If there is no `gdbserver' binary present on the device, then you can
-specify one to upload, like so:
+ prebuilt/android-<arch>/gdbserver/gdbserver
- ../java/debug.sh --gdbserver /path/to/gdbserver
+relative to the root of the NDK distribution.
+
+To attach Emacs to an existing process on a target device, use the
+`--attach-existing' argument to debug.sh:
+
+ ../java/debug.sh --attach-existing [other arguments]
+
+If multiple Emacs processes are running, debug.sh will display the
+names and PIDs of each running process, and prompt for the process
+that it should attach to.
-In addition, when Emacs runs as a 64-bit process on a system
-supporting both 64 and 32-bit binaries, you must specify the path to a
-64-bit gdbserver binary.
+After Emacs starts, type:
+
+ (gdb) handle SIGUSR1 noprint pass
+
+to ignore the SIGUSR1 signal that is sent by the Android port's
+`select' emulation. If this is overlooked, Emacs will stop each time
+a windowing event is received, which is probably unwanted.
On top of the debugging procedure described above, Android also
-maintains a "logcat" buffer, where it prints backtraces after each
-crash. Its contents are of interest when performing post-mortem
-debugging after a crash, and can also be retrieved through the `adb'
-tool, like so:
+maintains a "logcat" buffer, where it prints backtraces during or
+after each crash. Its contents are of interest when performing
+post-mortem debugging after a crash, and can also be retrieved through
+the `adb' tool, like so:
$ adb logcat
committed, while the ensuing ones print backtraces for each running
Java thread at the time of the error.
+If Emacs is executing on Android 5.0 and later, placing a breakpoint
+on
+
+ (gdb) break art::JavaVMExt::JniAbort
+
+will set a breakpoint that is hit each time such an error is detected.
+
Since the logcat output is always rapidly being amended, it is worth
piping it to a file or shell command buffer, and then searching for
keywords such as "AndroidRuntime", "Fatal signal", or "JNI DETECTED
ERROR IN APPLICATION".
+Once in a blue moon, it proves necessary to debug Java rather than C
+code. To this end, the `--jdb' option will attach the Java debugger
+instead of gdbserver. Lametably, it seems impossible to debug both C
+and Java code in concert.
+
\f
This file is part of GNU Emacs.