procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve java/DEBUG

Browse source 
* etc/DEBUG: Significantly reword and expand section.
(bug#65268)
This commit is contained in:
Po Lu 2023-08-16 16:12:54 +08:00
parent 5e12f4c89c
commit 3e51847801
1 changed files with 52 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

76
etc/DEBUG
View file

@ -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:
break art::JavaVMExt::JniAbort
will let you find the source of the crash.
If there is no `gdbserver' binary present on the device, then you can
specify one to upload, like so:
If there is no Gdbserver binary present on the device, then specify
one to upload, like so:
../java/debug.sh --gdbserver /path/to/gdbserver
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.
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
prebuilt/android-<arch>/gdbserver/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.
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.