master 3e51847801b: Improve java/DEBUG

[Po Lu]

branch: master
commit 3e51847801bd2c1631837dd13994b2fa0ace5233
Author: Po Lu <luangruo@yahoo.com>
Commit: Po Lu <luangruo@yahoo.com>

    Improve java/DEBUG
    
    * etc/DEBUG: Significantly reword and expand section.
    (bug#65268)
---
 etc/DEBUG | 72 ++++++++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 50 insertions(+), 22 deletions(-)

diff --git a/etc/DEBUG b/etc/DEBUG
index 005117dcb82..7c54b488cad 100644
--- a/etc/DEBUG
+++ b/etc/DEBUG
@@ -1101,42 +1101,58 @@ from GDB commands to corresponding LLDB commands there.
 
 ** 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
 
@@ -1246,11 +1262,23 @@ In such situations, the first line explains what 
infraction Emacs
 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.
+
 
 This file is part of GNU Emacs.