pyspresso¶
A Python-based framework for debugging Java.
Modules¶
Basic Usage¶
The DebugInterface
is the primary interface for interacting with the
debugged Java process.
To begin, create a DebugInterface
object. The constructor for this class
allows you to specify a "memory"
- or "socket"
-based transport and a file
mapping name or network address, respectively.
The next step is to run your target Java program with the created
DebugInterface
object’s xdebug_arg
field value as the value for
Java’s -Xdebug
command line argument:
di = pyspresso.debug_interface.DebugInterface()
args = ["java.exe", "-Xdebug", di.xdebug_arg, "-jar", "example.jar"]
subprocess.Popen(args)
Launching Java with the -Xdebug
command line argument causes the target
program to begin in a suspended state.
The next step is to attach the DebugInterface
object to the created
process. The call below to DebugInterface.Utilities.attach
identifies the
correct target process based on the unique address in xdebug_arg
:
di.utils.attach()
Now that pyspresso’s DebugInterface
is attached to the suspended process,
you may issue any DebugInterface
commands you like, such as setting
breakpoints, querying the JVM, etc.
Once you’ve finished your initialization steps, you can write your debug loop.
The debug loop consists of receiving a packet from the debuggee, parsing the
packet’s pyspresso.Event
values, handling each
pyspresso.Event
as you see fit, and then resuming the JVM:
while True:
# Get the next event from the event queue.
event_packet = di.utils.wait_for_event()
# Extract the suspend policy and all events from the packet.
(events, suspend_policy) = di.utils.parse_events(event_packet.data)
# Iterate over each event.
for event in events:
...
# Resume the VM as necessary.
if suspend_policy == pyspresso.constants.SuspendPolicy.EVENT_THREAD:
di.thread_reference.resume(event.thread)
elif suspend_policy == pyspresso.constants.SuspendPolicy.ALL:
di.virtual_machine.resume()
See the included JavaJournal sample for more details.