NAME

Devel::Debug::DBGp - Perl DBGp debugger (derived from Komodo remote debugging helper)

SYNOPSIS

From the command line:

    DBGP_OPTS="RemotePort=localhost:9000" perl -I/path/to/lib/dbgp-helper -d myscript.pl

From an helper module:

    unshift @INC, Devel::Debug::DBGp->debugger_path;
    $ENV{DBGP_OPTS} = "RemotePort=localhost:9000";
    require 'perl5db.pl';

For Plack applications see Plack::Middleware::DBGp.

DESCRIPTION

A modified version of ActiveState's Komodo remote debugging helper. It aims to be a compliant implementation of the DBGp protocol by default, but with the option of emulating Xdebug-specific quirks, for compatibility with existing clients that assume Xdebug behaviour.

When debugging, the debugger running inside the application establishes a connection to an external DBGp client (typically a GUI program) that allows to inspect the program state from the outside.

This implementation has been tested with pugdebug, Sublime Text Xdebug plugin and Vim VDebug plugin.

Note that it might not work with Komodo itself (by accident, I don't own a copy to test compatibility, bug reports welcome).

ENVIRONMENT VARIABLES

PERLDB_OPTS

Space-separated list of debugger options:

RemotePort

    PERLDB_OPTS="... RemotePort=hostname:port ..."

Host/port to which the debugger connects, alternative to RemotePath.

RemotePath

    PERLDB_OPTS="... RemotePath=/path/to/unix/socket ..."

Unix-domain socket path to which the debugger connects, alternative to RemotePort.

LogFile

    PERLDB_OPTS="... LogFile=/path/to/file ..."

If set, debugging information for the debugger itself is appended to the specified path.

Alarm, Async

    PERLDB_OPTS="... Alarm=1 ..."
    PERLDB_OPTS="... Async=1 ..."

Periodically check for break commands sent by the debugger (this uses "alarm" in perlfunc internally).

RecursionCheckDepth

    PERLDB_OPTS="... RecursionCheckDepth=N ..."

Break into the debugger when recursion level reaches the specified value.

Xdebug

    PERLDB_OPTS="... Xdebug=[0,1] ..."
    PERLDB_OPTS="... Xdebug=opt1,opt2,... ..."

Set one or more Xdebug compatibility options:

send_position_after_stepping

Whether to include an <xdebug:message> tag in step command response specifying the current file name and line number.

property_without_value_tag

Emit the value of scalar properties directly inside the <property> tag, without a <value> wrapper.

nested_properties_in_context

Return up to max_depth levels for properties in the context_get response, rather than returning just the root value and letting the debugger drill down if needed.

temporary_breakpoint_state

Return temporary breakpoint state as temporary instead of returning it as enabled.

ConnectAtStart

    PERLDB_OPTS="... ConnectAtStart=[1|0] ..."

Defaults to 1; whether the debugger program should connect to the DBGp client early during startup.

When set to 0, use "connectOrReconnect" to initiate the connection.

KeepRunning

    PERLDB_OPTS="... KeepRunning=[0|1] ..."

Defaults to 0; whether the debugged program should keep running with debugging disabled if the DBGp client drops the connection.

RemotePort

Equivalent to adding RemotePort=... to PERLDB_OPTS.

DEBUGGER_APPID

If set, it is returned as the appid attribute of the init message (defaults to "$$" in perlvar otherwise.

DBGP_IDEKEY

If set, it is returned as the idekey attribute of the init message.

DBGP_COOKIE

If set, it is returned as the session attribute of the init message.

HOST_HTTP

If set, overrides the value of the hostname attribute in the init message.

DBGP_PERL_IGNORE_PADWALKER

If set to a true value, does not use PadWalker to get the list of local variables, but uses a combination of B and eval STRING.

DBGP_PURE_PERL, DBGP_XS_ONLY

The default is to try to load an XS helper for the debugger, and fall back to the pure-Perl implementation if loading the XS helper fails (or the helper has not been built). Setting DBGP_PURE_PERL or DBGP_XS_ONLY allows to explicitly choose one or the other.

FUNCTIONS

There is no need to use any of the functions below unless you are writing an higher-level interface to the debugger (for example Plack::Middleware::DBGp).

connectOrReconnect

    DB::connectOrReconnect();

Connects to the debugger client (closes the current connection if any).

If the debugger client is not listening at the specified endpoint, debugging is disabled (via "disable") and execution continues normally.

isConnected

    my $connected = DB::isConnected();

Whether the debugger is connected to a client.

disable

    DB::disable();

Disables debugging. The debugged program should run at nearly normal speec with debugging disabled..

enable

    DB::enable();

Re-enables debugging after a "disable" call.

disconnect

    DB::disconnect();

Disconnects from the debugger client.

SEE ALSO

perldebguts, http://code.activestate.com/komodo/remotedebugging/

AUTHORS

Mattia Barbon <mbarbon@cpan.org> - packaging and misc changes/fixes

derived from ActiveState Komodo Remote Debugging Helper

derived from the Perl 5 debugger (perl5db.pl)

LICENSE

This program is free software; you can redistribute it and/or modify it under the Artistic License.

cpanm Devel::Debug::DBGp

perl -MCPAN -e shell
install Devel::Debug::DBGp