From: Po Lu Date: Wed, 16 Aug 2023 08:12:54 +0000 (+0800) Subject: Improve java/DEBUG X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=3e51847801bd2c1631837dd13994b2fa0ace5233;p=emacs.git Improve java/DEBUG * etc/DEBUG: Significantly reword and expand section. (bug#65268) --- 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-/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.