pyspresso

A Python-based framework for debugging Java.

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.

Index