/html/docs-dbgp.php
PHP | 2872 lines | 2867 code | 5 blank | 0 comment | 124 complexity | ce24263add14c081cf51441a69d630ea MD5 | raw file
Large files files are truncated, but you can click here to view the full file
- <?php $title = "Xdebug: Documentation - Protocol - DBGp"; include "include/header.php"; hits ('xdebug-docs-protocol'); ?>
- <tr>
- <td> </td>
- <td>
-
- <!-- MAIN FEATURE START -->
- <span class="sans">XDEBUG EXTENSION FOR PHP | DOCUMENTATION - PROTOCOL - DBGP</span><br />
- <?php include "include/menu-docs.php"; ?>
- <h1 class="title">DBGP - A common debugger protocol for languages and debugger UI communication</h1>
- <table class="docinfo" frame="void" rules="none">
- <col class="docinfo-name" />
- <col class="docinfo-content" />
- <tbody valign="top">
- <tr><th class="docinfo-name">Version:</th>
- <td>1.0</td></tr>
- <tr><th class="docinfo-name">Status:</th>
- <td>draft 17</td></tr>
- <tr><th class="docinfo-name">Authors:</th>
- <td>Shane Caraveo, ActiveState <<a class="reference external" href="mailto:shanec@ActiveState.com">shanec@ActiveState.com</a>>
- <br />Derick Rethans <<a class="reference external" href="mailto:derick@derickrethans.nl">derick@derickrethans.nl</a>></td></tr>
- </tbody>
- </table>
- <div class="contents topic" id="contents">
- <p class="topic-title first">Contents</p>
- <ul class="simple">
- <li><a class="reference internal" href="#description" id="id11">1. Description</a></li>
- <li><a class="reference internal" href="#issues" id="id12">1.1 Issues</a></li>
- <li><a class="reference internal" href="#requirements" id="id13">2. Requirements</a></li>
- <li><a class="reference internal" href="#terminology" id="id14">3. Terminology</a></li>
- <li><a class="reference internal" href="#security" id="id15">4. Security</a></li>
- <li><a class="reference internal" href="#initiating-a-debugging-session" id="id16">5. Initiating a debugging session</a><ul>
- <li><a class="reference internal" href="#standard-dbgp-port" id="id17">5.1 Standard DBGP port</a></li>
- <li><a class="reference internal" href="#connection-initialization" id="id18">5.2 Connection Initialization</a></li>
- <li><a class="reference internal" href="#just-in-time-debugging-and-debugger-proxies" id="id19">5.3 Just in time debugging and debugger proxies</a><ul>
- <li><a class="reference internal" href="#init-packet-handling" id="id20">5.3.1 Init Packet Handling</a></li>
- <li><a class="reference internal" href="#proxy-errors" id="id21">5.3.2 Proxy Errors</a></li>
- <li><a class="reference internal" href="#proxy-ports" id="id22">5.3.3 Proxy Ports</a></li>
- </ul>
- </li>
- <li><a class="reference internal" href="#multiple-processes-or-threads" id="id23">5.4 Multiple Processes or Threads</a></li>
- <li><a class="reference internal" href="#feature-negotiation" id="id24">5.5 Feature Negotiation</a><ul>
- <li><a class="reference internal" href="#data-packet-negotiation" id="id25">Data packet negotiation</a></li>
- <li><a class="reference internal" href="#asynchronous-communications" id="id26">Asynchronous Communications</a></li>
- </ul>
- </li>
- </ul>
- </li>
- <li><a class="reference internal" href="#message-packets" id="id27">6. Message Packets</a><ul>
- <li><a class="reference internal" href="#why-not-xml-both-ways" id="id28">6.1 Why not XML both ways?</a></li>
- <li><a class="reference internal" href="#packet-communications" id="id29">6.2 Packet Communications</a></li>
- <li><a class="reference internal" href="#ide-to-debugger-engine-communications" id="id30">6.3 IDE to debugger engine communications</a></li>
- <li><a class="reference internal" href="#debugger-engine-to-ide-communications" id="id31">6.4 debugger engine to IDE communications</a></li>
- <li><a class="reference internal" href="#debugger-engine-errors" id="id32">6.5 debugger engine errors</a></li>
- <li><a class="reference internal" href="#error-codes" id="id33">6.5.1 Error Codes</a></li>
- <li><a class="reference internal" href="#file-paths" id="id34">6.6 file paths</a></li>
- <li><a class="reference internal" href="#dynamic-code-and-virtual-files" id="id35">6.7 Dynamic code and virtual files</a></li>
- </ul>
- </li>
- <li><a class="reference internal" href="#core-commands" id="id36">7. Core Commands</a><ul>
- <li><a class="reference internal" href="#status" id="id37">7.1 status</a></li>
- <li><a class="reference internal" href="#options-and-configuration" id="id38">7.2 Options and Configuration</a><ul>
- <li><a class="reference internal" href="#feature-names" id="id39">7.2.1 Feature Names</a></li>
- <li><a class="reference internal" href="#feature-get" id="id40">7.2.2 feature_get</a></li>
- <li><a class="reference internal" href="#feature-set" id="id41">7.2.3 feature_set</a></li>
- </ul>
- </li>
- <li><a class="reference internal" href="#continuation-commands" id="id42">7.5 continuation commands</a></li>
- <li><a class="reference internal" href="#breakpoints" id="id43">7.6 breakpoints</a><ul>
- <li><a class="reference internal" href="#id1" id="id44">7.6.1 breakpoint_set</a></li>
- <li><a class="reference internal" href="#id2" id="id45">7.6.2 breakpoint_get</a></li>
- <li><a class="reference internal" href="#id3" id="id46">7.6.3 breakpoint_update</a></li>
- <li><a class="reference internal" href="#id4" id="id47">7.6.4 breakpoint_remove</a></li>
- <li><a class="reference internal" href="#id5" id="id48">7.6.5 breakpoint_list</a></li>
- </ul>
- </li>
- <li><a class="reference internal" href="#stack-depth" id="id49">7.7 stack_depth</a></li>
- <li><a class="reference internal" href="#stack-get" id="id50">7.8 stack_get</a></li>
- <li><a class="reference internal" href="#context-names" id="id51">7.9 context_names</a></li>
- <li><a class="reference internal" href="#context-get" id="id52">7.10 context_get</a></li>
- <li><a class="reference internal" href="#properties-variables-and-values" id="id53">7.11 Properties, variables and values</a></li>
- <li><a class="reference internal" href="#data-types" id="id54">7.12 Data Types</a><ul>
- <li><a class="reference internal" href="#common-data-types" id="id55">7.12.1 Common Data Types</a></li>
- <li><a class="reference internal" href="#typemap-get" id="id56">7.12.2 typemap_get</a></li>
- </ul>
- </li>
- <li><a class="reference internal" href="#property-get-property-set-property-value" id="id57">7.13 property_get, property_set, property_value</a></li>
- <li><a class="reference internal" href="#source" id="id58">7.14 source</a></li>
- <li><a class="reference internal" href="#stdout-stderr" id="id59">7.15 stdout, stderr</a></li>
- </ul>
- </li>
- <li><a class="reference internal" href="#extended-commands" id="id60">8. Extended Commands</a><ul>
- <li><a class="reference internal" href="#stdin" id="id61">8.1 stdin</a></li>
- <li><a class="reference internal" href="#break" id="id62">8.2 break</a></li>
- <li><a class="reference internal" href="#eval" id="id63">8.3 eval</a><ul>
- <li><a class="reference internal" href="#expr" id="id64">8.3.1 expr</a></li>
- <li><a class="reference internal" href="#exec" id="id65">8.3.2 exec</a></li>
- </ul>
- </li>
- <li><a class="reference internal" href="#spawnpoints" id="id66">8.4 spawnpoints</a><ul>
- <li><a class="reference internal" href="#id6" id="id67">8.4.1 spawnpoint_set</a></li>
- <li><a class="reference internal" href="#id7" id="id68">8.4.2 spawnpoint_get</a></li>
- <li><a class="reference internal" href="#id8" id="id69">8.4.3 spawnpoint_update</a></li>
- <li><a class="reference internal" href="#id9" id="id70">8.4.4 spawnpoint_remove</a></li>
- <li><a class="reference internal" href="#id10" id="id71">8.4.5 spawnpoint_list</a></li>
- </ul>
- </li>
- <li><a class="reference internal" href="#notifications" id="id72">8.5 Notifications</a><ul>
- <li><a class="reference internal" href="#standard-notifications" id="id73">8.5.1 Standard Notifications</a></li>
- </ul>
- </li>
- <li><a class="reference internal" href="#interact-interactive-shell" id="id74">8.6 interact - Interactive Shell</a></li>
- </ul>
- </li>
- <li><a class="reference internal" href="#a-changelog" id="id75">A. ChangeLog</a></li>
- </ul>
- </div>
- <div class="section" id="description">
- <h1><a class="toc-backref" href="#id11">1. Description</a></h1>
- <p>This document describes a simple protocol for use with language tools
- and engines for the purpose of debugging applications. It does not
- describe user interfaces or interactions with the debugger. The
- protocol provides a means of communication between a debugger
- engine (scripting engine, vm, etc.) and a debugger IDE (IDE, etc.).
- Any references to the debugger IDE UI are recommendations only, and are
- provided for additional explanation or as reasoning for specific
- design decisions.</p>
- </div>
- <div class="section" id="issues">
- <h1><a class="toc-backref" href="#id12">1.1 Issues</a></h1>
- <p>1. The handling of proxy errors needs to be clarified. Without both
- IDE and debugger engine supporting commands to be received at
- arbitrary times, the proxy may have problems sending error or status
- information to either one. See section 5.3.2. We should think a bit
- more about what a proxy might need to do.</p>
- </div>
- <div class="section" id="requirements">
- <h1><a class="toc-backref" href="#id13">2. Requirements</a></h1>
- <ul class="simple">
- <li>extensibility, allow for vendor or language specific features</li>
- <li>backwards and forwards compatibility</li>
- <li>firewall and tunneling support</li>
- <li>support for multiple languages</li>
- <li>support for multiple processes or threads</li>
- <li>support for dynamic and possibly for compiled languages</li>
- </ul>
- </div>
- <div class="section" id="terminology">
- <h1><a class="toc-backref" href="#id14">3. Terminology</a></h1>
- <dl class="docutils">
- <dt>IDE</dt>
- <dd>An IDE, or other debugger UI IDE or tool.</dd>
- <dt>debugger engine</dt>
- <dd>The language engine being debugged.</dd>
- <dt>proxy</dt>
- <dd>An intermediary demon that acts as a proxy, and may also
- implement support for other features such as just in time
- debugging, ip security, etc.</dd>
- <dt>session</dt>
- <dd>a single thread in an application. multiple threads in an
- application will attach separately.</dd>
- <dt>TRUE</dt>
- <dd>a value defined as TRUE should be a numeric one.</dd>
- <dt>FALSE</dt>
- <dd>a value defined as FALSE should be a numeric zero.</dd>
- <dt>NUM</dt>
- <dd>a base 10 numeric value that is stringified.</dd>
- </dl>
- </div>
- <div class="section" id="security">
- <h1><a class="toc-backref" href="#id15">4. Security</a></h1>
- <p>It is expected that implementations will provide security, such as ip
- filtering, ssh tunneling, etc. This protocol itself does not provide
- a means of securing the debugging session.</p>
- </div>
- <div class="section" id="initiating-a-debugging-session">
- <h1><a class="toc-backref" href="#id16">5. Initiating a debugging session</a></h1>
- <p>The debugger engine initiates a debugging session. The debugger engine
- will make a connection to a listening IDE, then wait for the IDE to
- initiate commands. The debugger engine does not step into the first line of
- execution until the IDE issues one of the continuation commands.
- The first thing that should happen in a debug session is that the IDE
- negotiates features using the feature_get and feature_set commands, and sets
- any additional data, such as breakpoints. Debugger engine implementations
- should store and data it receives if it is unable to process them prior to
- compiling and/or executing code. Commands such as stack_get should not be
- expected to work during this phase, otherwise known as the 'starting' state (see
- section 7.1 for status levels).</p>
- <p>Likewise, at the end of a debug session, there is a 'stopping' state. This state
- is entered after all execution is complete. For most debugger engine implementations,
- only a 'stop' command can be accepted at this point, however some implementations
- may provide additional commands for retrieving various data from the engine for
- post debug session processing.</p>
- <div class="section" id="standard-dbgp-port">
- <h2><a class="toc-backref" href="#id17">5.1 Standard DBGP port</a></h2>
- <p>The IDE listens on port 9000 for debugger connections, unless the
- IDE is using a proxy, in which case it may listen on any port. In
- that case, the IDE will tell the proxy which port it is listening on, and the
- proxy should listen on port 9000. While this document defines port 9000
- as the standard DBGP port, an implementation may support the use of any
- port. Current implementations accept various forms of configuration that
- allow this port to be defined.</p>
- </div>
- <div class="section" id="connection-initialization">
- <h2><a class="toc-backref" href="#id18">5.2 Connection Initialization</a></h2>
- <p>When a debugger engine connects to either a IDE or proxy, it must send an
- init packet:</p>
- <pre class="literal-block">
- <init appid="APPID"
- idekey="IDE_KEY"
- session="DBGP_COOKIE"
- thread="THREAD_ID"
- parent="PARENT_APPID"
- language="LANGUAGE_NAME"
- protocol_version="1.0"
- fileuri="file://path/to/file">
- </pre>
- <p>Attributes in the init element can include:</p>
- <blockquote>
- <table border="1" class="docutils">
- <colgroup>
- <col width="22%" />
- <col width="78%" />
- </colgroup>
- <thead valign="bottom">
- <tr><th class="head">Attribute</th>
- <th class="head">Description</th>
- </tr>
- </thead>
- <tbody valign="top">
- <tr><td>appid</td>
- <td>defined by the debugger engine</td>
- </tr>
- <tr><td>idekey</td>
- <td>defined by the user. The DBGP_IDEKEY environment
- variable SHOULD be used if it is available,
- otherwise setting this value is debugger engine
- implementation specific. This value may be empty.</td>
- </tr>
- <tr><td>session</td>
- <td>If the environment variable DBGP_COOKIE exists,
- then the init packet MUST contain a session
- attribute with the value of the variable. This
- allows an IDE to execute a debugger engine, and
- maintain some state information between the
- execution and the protocol connection. This value
- should not be expected to be set in 'remote'
- debugging situations where the IDE is not in
- control of the process.</td>
- </tr>
- <tr><td>thread</td>
- <td>the systems thread id</td>
- </tr>
- <tr><td>parent</td>
- <td>the appid of the application that spawned the
- process. When an application is executed, it
- should set it's APPID into the environment.
- If an APPID already exists, it should first
- read that value and use it as the PARENT_APPID.</td>
- </tr>
- <tr><td>language</td>
- <td>debugger engine specific, must not contain
- additional information, such as version, etc.</td>
- </tr>
- <tr><td>protocol_version</td>
- <td>The highest version of this protocol supported</td>
- </tr>
- <tr><td>fileuri</td>
- <td>URI of the script file being debugged</td>
- </tr>
- </tbody>
- </table>
- </blockquote>
- <p>The IDE responds by dropping socket connection, or starting with
- debugger commands.</p>
- <p>The init packet may have child elements for additional vendor specific
- data. These are entirely optional and must not effect behavior
- of the debugger interaction. Suggested child elements include:</p>
- <pre class="literal-block">
- <engine version="1.abcd">product title</engine>
- <author>author</author>
- <company>company</company>
- <license>licensing info</license>
- <url>url</url>
- <copyright>xxx</copyright>
- </pre>
- </div>
- <div class="section" id="just-in-time-debugging-and-debugger-proxies">
- <h2><a class="toc-backref" href="#id19">5.3 Just in time debugging and debugger proxies</a></h2>
- <p>Proxies are supported to allow multiuser systems work with a defined
- port for debugging. Each IDE would listen on a unique port and notify the
- proxy what port it is listening on, along with a key value that is used by
- the debugger engine to specify which IDE it should be connected with.</p>
- <p>With the exception of the init packet, all communications
- will be passed through without modifications. A proxy could also implement
- support for just in time debugging. In this case, a debugger engine would
- break (perhaps on an error or exception) and connect to the proxy. The proxy
- would then start the IDE (if it is not already running) and initiate a
- debugging session with it.</p>
- <p>The method for handling just in time debugging is not defined by the protocol
- and is implementation specific. One example of how this may work is that the
- proxy has a configuration file that defines key's for each user, along with
- the path to the executable that will provide the UI for that user. The debugger
- engine would have to know this key value in advance and provide it to the proxy
- in the init packet (see IDE_KEY in section 5.2). The proxy would know if the
- IDE is running, since the IDE should have communicated with the proxy already,
- if it has not, the proxy could execute the IDE directly.</p>
- <p>To support proxies and jit deamons, the IDE should be configured with
- and ip:port pointing to the proxy/jit. The IDE then makes a
- connection to the proxy when it starts and sends the following command:</p>
- <blockquote>
- <p>IDE command</p>
- <pre class="literal-block">
- proxyinit -a ip:port -k ide_key -m [0|1]
- </pre>
- <table border="1" class="docutils">
- <colgroup>
- <col width="3%" />
- <col width="97%" />
- </colgroup>
- <tbody valign="top">
- <tr><td>-p</td>
- <td>the port that the IDE listens for debugging on. The address
- is retrieved from the connection information.</td>
- </tr>
- <tr><td>-k</td>
- <td>a IDE key, which the debugger engine will also use in it's
- debugging init command. this allows the proxy to match
- request to IDE. Typically the user will provide the
- session key as a configuration item.</td>
- </tr>
- <tr><td>-m</td>
- <td>this tells the demon that the IDE supports (or doesn't)
- multiple debugger sessions. if -m is missing, zero or no
- support is default.</td>
- </tr>
- </tbody>
- </table>
- <p>IDE command</p>
- <pre class="literal-block">
- proxystop -k ide_key
- </pre>
- <p>The IDE sends a proxystop command when it wants the proxy
- server to stop listening for it.</p>
- </blockquote>
- <p>The proxy should respond with a simple XML statement alerting the
- IDE to an error, or the success of the initialization (see section
- 6.5 for more details on the error element).</p>
- <pre class="literal-block">
- <proxyinit success="[0|1]"
- idekey="{ID}"
- address="{IP_ADDRESS}"
- port="{NUM}>
- <error id="app_specific_error_code">
- <message>UI Usable Message</message>
- </error>
- </proxyinit>
- </pre>
- <p>Once the IDE has sent this command, and received a confirmation, it
- disconnects from the proxy. The IDE will only connect to the proxy
- when it initially wants to start accepting connections from the proxy,
- or when it wants to stop accepting connections from the proxy.</p>
- <p>The address and port attributes of the returned proxyinit element are the
- address and port that the proxy is configured to listen for DBGP connections on.
- This information is returned to the IDE so that it may pass this information on
- to build systems or the user via some UI.</p>
- <div class="section" id="init-packet-handling">
- <h3><a class="toc-backref" href="#id20">5.3.1 Init Packet Handling</a></h3>
- <p>If a proxy receives the init packet (see section 5.2), it will use the
- idekey attribute to pass the request to the correct IDE, or to do some
- other operation such as which may be required to implement security or
- initiate just in time debugging. The proxy will add the idekey as a attribute
- to the init packet when it passes it through to the IDE. The proxy may
- also add child elements with further information, and must add an
- attribute to the init element called 'proxied' with the attribute
- value being the ip address of the debugger engine. This is the only
- time the proxy should modify data being passed to the IDE.</p>
- </div>
- <div class="section" id="proxy-errors">
- <h3><a class="toc-backref" href="#id21">5.3.2 Proxy Errors</a></h3>
- <p>If the proxy must send error data to the IDE, it may send an XML
- message with the root element named 'proxyerror'. This message will
- be in the format of the error packets defined in 6.3 below.</p>
- <p>If the proxy must send error data to the debugger engine, it may
- send the proxyerror command defined in section 7 below.</p>
- </div>
- <div class="section" id="proxy-ports">
- <h3><a class="toc-backref" href="#id22">5.3.3 Proxy Ports</a></h3>
- <p>The proxy listens for IDE connections on port 9001, and for debugger
- engine connections on port 9000. As with section 5.1, these ports may
- be configurable in the implementation.</p>
- </div>
- </div>
- <div class="section" id="multiple-processes-or-threads">
- <h2><a class="toc-backref" href="#id23">5.4 Multiple Processes or Threads</a></h2>
- <p>The debugger protocol is designed to use a separate socket connection
- for each process or thread. The IDE may or may not support
- multiple debugger sessions. If it does not, the debugger engine must
- not attempt to start debug sessions for threads, and the IDE should
- not accept more than one socket connection for debugging. The
- IDE should tell the debugger engine whether it supports multiple
- debugger sessions, the debugger engine should assume that the IDE does
- not. The IDE can use the feature_set command with the feature name of
- 'multiple_sessions' to notify the debugger engine that it supports multiple
- session debugging. The IDE may also query the the debugger engine specifically
- for multithreaded debugging support by using the feature_get command with
- a feature name of 'language_supports_threads'.</p>
- </div>
- <div class="section" id="feature-negotiation">
- <h2><a class="toc-backref" href="#id24">5.5 Feature Negotiation</a></h2>
- <p>Although the IDE may at any time during the debugging session send
- feature_get or feature_set commands, the IDE should be designed to
- negotiate the base set of features up front. Differing languages and
- debugger engines may operate in many ways, and the IDE should be
- prepared to handle these differences. Likewise, the IDE may dictate
- certain features or capabilities be supported by the debugger engine.
- In any case, the IDE should strive to work with all debugger engines
- that support this protocol. Therefore, this section describes a
- minimal set of features the debugger engine must support. These
- required features are outlined here in the form of discussion,
- actual implementation of feature arguments are detailed in section 7
- under the feature_get and feature_set commands.</p>
- <div class="section" id="data-packet-negotiation">
- <h3><a class="toc-backref" href="#id25">Data packet negotiation</a></h3>
- <p>IDE's may want to limit the size of data that is retrieved from
- debugger engines. While the debugger engines will define their own
- base default values, the IDE should negotiate these terms if it
- needs to. The debugger engine must support these requests from the
- IDE. This includes limits to the data size of a property or
- variable, and the depth limit to arrays, hashes, objects, or other
- tree like structures. The data size excludes any the protocol
- overhead.</p>
- </div>
- <div class="section" id="asynchronous-communications">
- <h3><a class="toc-backref" href="#id26">Asynchronous Communications</a></h3>
- <p>While the protocol does not depend on asynchronous socket support,
- certain design considerations may require that the IDE and/or debugger
- engine treat incoming and outgoing data in an asynchronous fashion.</p>
- <p>For ease of design, some implementations may choose to utilize this
- protocol in a completely synchronous fashion, and not implement
- optional commands that require the debugger engine to behave in an
- asynchronous fashion. One example of this is the break command.</p>
- <p>The break command is sent from the IDE while the debugger engine is
- in a run state. To support this, the debugger engine must periodically
- peek at the socket to see if there are any incoming commands. For
- this reason the break command is optional. If a command requires
- this type of asynchronous behavior on the part of the debugger
- engine it must be optional for the debugger engine to support it.</p>
- <p>On the other hand, IDE's MUST at times behave in an asynchronous
- fashion. When an IDE tells the debugger engine to enter a 'run' state,
- it must watch the socket for incoming packets for stdout or stderr,
- if it has requested the data be sent to it from the debugger engine.</p>
- <p>The form of asynchronous communications that may occur in this
- protocol are defined further in section 6.2 below.</p>
- </div>
- </div>
- </div>
- <div class="section" id="message-packets">
- <h1><a class="toc-backref" href="#id27">6. Message Packets</a></h1>
- <p>The IDE sends simple ASCII commands to the debugger engine. The
- debugger engine responds with XML data. The XML data is prepended
- with a stringified integer representing the number of bytes in the XML data
- packet. The length and XML data are separated by a NULL byte. The
- XML data is ended with a NULL byte. Neither the IDE or debugger engine
- packets may contain NULL bytes within the packet since it is used as
- a separator. Data must be encoded using base64.</p>
- <pre class="literal-block">
- IDE: command [SPACE] [args] -- data [NULL]
- DEBUGGER: [NUMBER] [NULL] XML(data) [NULL]
- </pre>
- <p>Arguments to the IDE commands are in the same format as common command
- line arguments, and should be parseable by common code such as getopt,
- or Pythons Cmd module:</p>
- <pre class="literal-block">
- command -a value -b value ...
- </pre>
- <p>If a value for an option includes a space, the value needs to be
- encoded. You can encode values by encasing them in double quotes:</p>
- <pre class="literal-block">
- property_get -i 5 -n "$x['a b']" -d 0 -c 0 -p 0
- </pre>
- <p>It is also possible to use escape characters in quoted strings:</p>
- <pre class="literal-block">
- property_get -i 6 -n "$x[\"a b\"]" -d 0 -c 0 -p 0
- </pre>
- <p>All numbers in the protocol are base 10 string representations, unless
- the number is noted to be debugger engine specific (eg. the address
- attribute on property elements).</p>
- <div class="section" id="why-not-xml-both-ways">
- <h2><a class="toc-backref" href="#id28">6.1 Why not XML both ways?</a></h2>
- <p>The primary reason is to avoid the requirement that a debugger
- engine has an XML parser available. XML is easy to generate, but
- requires additional libraries for parsing.</p>
- </div>
- <div class="section" id="packet-communications">
- <h2><a class="toc-backref" href="#id29">6.2 Packet Communications</a></h2>
- <p>The IDE sends a command, then waits for a response from the
- debugger engine. If the command is not received in a reasonable
- time (implementation dependent) it may assume the debugger engine
- has entered a non-responsive state. The exception to this is when
- the IDE sends a 'continuation' command which may not have an immediate response.</p>
- <p>'continuation' commands include, but may not be limited to: run, step_into,
- step_over, step_out and eval. When the debugger engine
- receives such a command, it is considered to have entered a
- 'run state'.</p>
- <p>During a 'continuation' command, the IDE should expect to possibly receive
- stdin and/or stderr packets from the debugger engine prior to
- receiving a response to the command itself. It may also possibly
- receive error packets from either the debugger engine, or a proxy
- if one is in use, either prior to the 'continuation' response, or in response
- to any other command.</p>
- <p>Stdout and stderr, if requested by the IDE, may only be sent during
- commands that have put the debugger engine into a 'run' state.</p>
- <p>If the debugger engine supports asynchronous commands, the IDE may also
- send commands while the debugger engine is in a 'run' state. These
- commands should be limited to commands such as the 'break' or 'status'
- commands for performance reasons, but this protocol does not impose
- such limitations. The debugger engine MUST respond to these commands
- prior to responding to the original 'run' command.</p>
- <p>An example of communication between IDE and debugger engines. (this
- is not an example of the actual protocol.)</p>
- <pre class="literal-block">
- IDE: feature_get supports_async
- DBG: yes
- IDE: stdin redirect
- DBG: ok
- IDE: stderr redirect
- DBG: ok
- IDE: run
- DBG: stdin data...
- DBG: stdin data...
- DBG: reached breakpoint, done running
- IDE: give me some variables
- DBG: ok, here they are
- IDE: evaluate this expression
- DBG: stderr data...
- DBG: ok, done
- IDE: run
- IDE: break
- DBG: ok, breaking
- DBG: at breakpoint, done running
- IDE: stop
- DBG: good bye
- </pre>
- </div>
- <div class="section" id="ide-to-debugger-engine-communications">
- <h2><a class="toc-backref" href="#id30">6.3 IDE to debugger engine communications</a></h2>
- <p>A debugging IDE (IDE) sends commands to the debugger engine in
- the form of command line arguments. One argument that is included in
- all commands is the data length. The data itself is the last part of
- the command line, after the -- separator. The data must be base64 encoded.</p>
- <pre class="literal-block">
- command [SPACE] [arguments] [SPACE] -- base64(data) [NULL]
- </pre>
- <p>Standard arguments for all commands</p>
- <pre class="literal-block">
- -i Transaction ID
- unique numerical ID for each command generated by the IDE
- </pre>
- </div>
- <div class="section" id="debugger-engine-to-ide-communications">
- <h2><a class="toc-backref" href="#id31">6.4 debugger engine to IDE communications</a></h2>
- <p>The debugger engine always replies or sends XML data. The standard
- namespace for the root elements returned from the debugger
- engine MUST be "<a class="reference external" href="urn:debugger_protocol_v1">urn:debugger_protocol_v1</a>". Namespaces have been left
- out in the examples in this document. The messages sent by the
- debugger engine must always be NULL terminated. The XML document tag
- must always be present to provide XML version and encoding information.</p>
- <p>Two base tags are used for the root tags:</p>
- <pre class="literal-block">
- data_length
- [NULL]
- <?xml version="1.0" encoding="UTF-8"?>
- <response command="command_name"
- transaction_id="transaction_id"/>
- [NULL]
- data_length
- [NULL]
- <?xml version="1.0" encoding="UTF-8"?>
- <stream type="stdout|stderr">...Base64 Data...</stream>
- [NULL]
- </pre>
- <p>For simplification, data length and NULL bytes will be left out of the
- rest of the examples in this document.</p>
- </div>
- <div class="section" id="debugger-engine-errors">
- <h2><a class="toc-backref" href="#id32">6.5 debugger engine errors</a></h2>
- <p>A debugger engine may need to relay error information back to the IDE in
- response to any command. The debugger engine may add an error element
- as a child of the response element. Note that this is not the same
- as getting language error messages, such as exception data. This is
- specifically a debugger engine error in response to a IDE
- command. IDEs and debugger engines may elect to support additional
- child elements in the error element, but should namespace the elements
- to avoid conflicts with other implementations.</p>
- <pre class="literal-block">
- <response command="command_name"
- transaction_id="transaction_id">
- <error code="error_code" apperr="app_specific_error_code">
- <message>UI Usable Message</message>
- </error>
- </response>
- </pre>
- </div>
- <div class="section" id="error-codes">
- <h2><a class="toc-backref" href="#id33">6.5.1 Error Codes</a></h2>
- <p>The following are predefined error codes for the response to commands:</p>
- <p>000 Command parsing errors</p>
- <pre class="literal-block">
- 0 - no error
- 1 - parse error in command
- 2 - duplicate arguments in command
- 3 - invalid options (ie, missing a required option, invalid value for a
- passed option)
- 4 - Unimplemented command
- 5 - Command not available (Is used for async commands. For instance
- if the engine is in state "run" then only "break" and "status"
- are available).
- </pre>
- <p>100 File related errors</p>
- <pre class="literal-block">
- 100 - can not open file (as a reply to a "source" command if the
- requested source file can't be opened)
- 101 - stream redirect failed
- </pre>
- <p>200 Breakpoint, or code flow errors</p>
- <pre class="literal-block">
- 200 - breakpoint could not be set (for some reason the breakpoint
- could not be set due to problems registering it)
- 201 - breakpoint type not supported (for example I don't support
- 'watch' yet and thus return this error)
- 202 - invalid breakpoint (the IDE tried to set a breakpoint on a
- line that does not exist in the file (ie "line 0" or lines
- past the end of the file)
- 203 - no code on breakpoint line (the IDE tried to set a breakpoint
- on a line which does not have any executable code. The
- debugger engine is NOT required to return this type if it
- is impossible to determine if there is code on a given
- location. (For example, in the PHP debugger backend this
- will only be returned in some special cases where the current
- scope falls into the scope of the breakpoint to be set)).
- 204 - Invalid breakpoint state (using an unsupported breakpoint state
- was attempted)
- 205 - No such breakpoint (used in breakpoint_get etc. to show that
- there is no breakpoint with the given ID)
- 206 - Error evaluating code (use from eval() (or perhaps
- property_get for a full name get))
- 207 - Invalid expression (the expression used for a non-eval()
- was invalid)
- </pre>
- <p>300 Data errors</p>
- <pre class="literal-block">
- 300 - Can not get property (when the requested property to get did
- not exist, this is NOT used for an existing but uninitialized
- property, which just gets the type "uninitialised" (See:
- PreferredTypeNames)).
- 301 - Stack depth invalid (the -d stack depth parameter did not
- exist (ie, there were less stack elements than the number
- requested) or the parameter was < 0)
- 302 - Context invalid (an non existing context was requested)
- </pre>
- <p>900 Protocol errors</p>
- <pre class="literal-block">
- 900 - Encoding not supported
- 998 - An internal exception in the debugger occurred
- 999 - Unknown error
- </pre>
- </div>
- <div class="section" id="file-paths">
- <h2><a class="toc-backref" href="#id34">6.6 file paths</a></h2>
- <p>All file paths passed between the IDE and debugger engine must be in
- the URI format specified by IETF RFC 1738 and 2396, and must be
- absolute paths.</p>
- </div>
- <div class="section" id="dynamic-code-and-virtual-files">
- <h2><a class="toc-backref" href="#id35">6.7 Dynamic code and virtual files</a></h2>
- <p>The protocol reserves the URI scheme 'dbgp' for all virtual
- files generated and maintained by language engines. Such
- virtual files are usually managed by a language engine for
- dynamic code blocks, i.e. code created at runtime, without
- an association with a regular file. Any IDE seeing an URI
- with the 'dbgp' scheme has to use the 'source' command (See
- section 7.14) to obtain the contents of the file from the
- engine responsible for that URI.</p>
- <p>All URIs in that scheme have the form:</p>
- <blockquote>
- dbgp:engine-specific-identifier</blockquote>
- <p>The engine-specific-identifier is some string which the debugger engine
- uses to keep track of the specific virtual file. The IDE must return
- the URI to the debugger engine unchanged through the source command to
- retrieve the virtual file.</p>
- </div>
- </div>
- <div class="section" id="core-commands">
- <h1><a class="toc-backref" href="#id36">7. Core Commands</a></h1>
- <p>Both IDE and debugger engine must support all core commands.</p>
- <div class="section" id="status">
- <h2><a class="toc-backref" href="#id37">7.1 status</a></h2>
- <p>The status command is a simple way for the IDE to find out from
- the debugger engine whether execution may be continued or not.
- no body is required on request. If async support has been
- negotiated using feature_get/set the status command may be sent
- while the debugger engine is in a 'run state'.</p>
- <p>The status attribute values of the response may be:</p>
- <blockquote>
- <dl class="docutils">
- <dt>starting:</dt>
- <dd>State prior to execution of any code</dd>
- <dt>stopping:</dt>
- <dd>State after completion of code execution. This typically
- happens at the end of code execution, allowing the IDE to
- further interact with the debugger engine (for example, to
- collect performance data, or use other extended commands).</dd>
- <dt>stopped:</dt>
- <dd>IDE is detached from process, no further interaction is
- possible.</dd>
- <dt>running:</dt>
- <dd>code is currently executing. Note that this
- state would only be seen with async support
- turned on, otherwise the typical state during
- IDE/debugger interaction would be 'break'</dd>
- <dt>break:</dt>
- <dd>code execution is paused, for whatever reason
- (see below), and the IDE/debugger can pass
- information back and forth.</dd>
- </dl>
- </blockquote>
- <p>The reason attribute value may be:</p>
- <blockquote>
- <ul class="simple">
- <li>ok</li>
- <li>error</li>
- <li>aborted</li>
- <li>exception</li>
- </ul>
- </blockquote>
- <p>IDE</p>
- <pre class="literal-block">
- status -i transaction_id
- </pre>
- <p>debugger engine</p>
- <pre class="literal-block">
- <response command="status"
- status="starting"
- reason="ok"
- transaction_id="transaction_id">
- message data
- </response>
- </pre>
- </div>
- <div class="section" id="options-and-configuration">
- <h2><a class="toc-backref" href="#id38">7.2 Options and Configuration</a></h2>
- <p>The feature commands are used to request feature support from the debugger
- engine. This includes configuration options, some of which may be changed via
- feature_set, the ability to discover support for implemented commands, and to
- discover values for various features, such as the language version or name.</p>
- <p>An example of usage would be to send a feature request with the string 'stdin'
- to find out if the engine supports redirection of the stdin stream through the
- debugger socket. The debugger engine must consider all commands as keys for this
- command, but may also have keys that are for features that do not map directly
- to commands.</p>
- <div class="section" id="feature-names">
- <h3><a class="toc-backref" href="#id39">7.2.1 Feature Names</a></h3>
- <p>The following features strings MUST be available:</p>
- <blockquote>
- <table border="1" class="docutils">
- <colgroup>
- <col width="34%" />
- <col width="9%" />
- <col width="57%" />
- </colgroup>
- <tbody valign="top">
- <tr><td>language_supports_threads</td>
- <td>get</td>
- <td>[0|1]</td>
- </tr>
- <tr><td>language_name</td>
- <td>get</td>
- <td>{eg. PHP, Python, Perl}</td>
- </tr>
- <tr><td>language_version</td>
- <td>get</td>
- <td>{version string}</td>
- </tr>
- <tr><td>encoding</td>
- <td>get</td>
- <td>current encoding in use by the debugger
- session. The encoding can either be
- (7-bit) ASCII, or a code set which
- contains ASCII (Ex: ISO-8859-X, UTF-8)</td>
- </tr>
- <tr><td>protocol_version</td>
- <td>get</td>
- <td>{for now, always 1}</td>
- </tr>
- <tr><td>supports_async</td>
- <td>get</td>
- <td>{for commands such as break}</td>
- </tr>
- <tr><td>data_encoding</td>
- <td>get</td>
- <td>optional, allows to turn off
- the default base64 encoding of data. This
- should only be used for development and
- debugging of the debugger engines
- themselves, and not for general use. If
- implemented the value 'base64' must be
- supported to turn back on regular
- encoding. the value 'none' means no
- encoding is in use. all elements that use
- encoding must include an encoding
- attribute.</td>
- </tr>
- <tr><td>breakpoint_languages</td>
- <td>get</td>
- <td>some engines may support more than one
- language. This feature returns a string
- which is a comma separated list of
- supported languages. <strong>If the engine does
- not provide this feature, then it is
- assumed that the engine only supports the
- language defined in the feature
- language_name.</strong> One example of this is an
- XSLT debugger engine which supports XSLT,
- XML, HTML and XHTML. An IDE may need this
- information to to know what types of
- breakpoints an engine will accept.</td>
- </tr>
- <tr><td>breakpoint_types</td>
- <td>get</td>
- <td>returns a space separated list with all
- the breakpoint types that are supported.
- See <a class="reference internal" href="#breakpoints">7.6 breakpoints</a> for a list of the
- 6 defined breakpoint types.</td>
- </tr>
- <tr><td>multiple_sessions</td>
- <td>get|set</td>
- <td>{0|1}</td>
- </tr>
- <tr><td>encoding</td>
- <td>get|set</td>
- <td>{ISO8859-15, UTF-8, etc.}</td>
- </tr>
- <tr><td>max_children</td>
- <td>get|set</td>
- <td>max number of array or object
- children to initially retrieve</td>
- </tr>
- <tr><td>max_data</td>
- <td>get|set
- get|set</td>
- <td>max amount of variable data to
- initially retrieve.</td>
- </tr>
- <tr><td>max_depth</td>
- <td>get|set</td>
- <td>maximum depth that the debugger
- engine may return when sending arrays,
- hashs or object structures to the IDE.</td>
- </tr>
- </tbody>
- </table>
- </blockquote>
- <p>The following features strings MAY be available, if they are not, the IDE should
- assume that the feature is not available:</p>
- <blockquote>
- <table border="1" class="docutils">
- <colgroup>
- <col width="34%" />
- <col width="9%" />
- <col width="57%" />
- </colgroup>
- <tbody valign="top">
- <tr><td>supports_postmortem</td>
- <td>get</td>
- <td>[0|1] This feature lets an IDE know that
- there is benefit to continuing interaction
- during the STOPPING state (sect. 7.1).</td>
- </tr>
- <tr><td>show_hidden</td>
- <td>get|set</td>
- <td>[0|1] This feature can get set by the IDE
- if it wants to have more detailed internal
- information on properties (eg. private
- members of classes, etc.) Zero means that
- hidden members are not shown to the IDE.</td>
- </tr>
- <tr><td>notify_ok</td>
- <td>get|set</td>
- <td>[0|1] See section 8.5</td>
- </tr>
- </tbody>
- </table>
- </blockquote>
- <p>Additionally, all protocol commands supported must have a string,
- such as the following examples:</p>
- <pre class="literal-block">
- breakpoint_set
- break
- eval
- </pre>
- </div>
- <div class="section" id="feature-get">
- <h3><a class="toc-backref" href="#id40">7.2.2 feature_get</a></h3>
- <p>arguments for feature_get include:</p>
- <blockquote>
- <table border="1" class="docutils">
- <colgroup>
- <col width="5%" />
- <col width="95%" />
- </colgroup>
- <tbody valign="top">
- <tr><td>-n</td>
- <td>feature_name</td>
- </tr>
- </tbody>
- </table>
- </blockquote>
- <p>IDE</p>
- <pre class="literal-block">
- feature-get -i transaction_id -n feature_name
- </pre>
- <p>debugger engine</p>
- <pre class="literal-block">
- <response command="feature_get"
- feature_name="feature_name"
- supported="0|1"
- transaction_id="transaction_id">
- feature setting or available options, such as a list of
- supported encodings
- </response>
- </pre>
- <p>The 'supported' attribute does NOT mean that the feature is supported, this
- is encoded in the text child of the response tag. The 'supported' attribute
- informs whether the feature with 'feature_name' is supported by feature_get
- in the engine, or when the command with name 'feature_get' is supported by the
- engine.</p>
- <p>Example: Xdebug does not understand the 'breakpoint_languages' feature
- and will therefore set the supported attribute to '0'. It does however
- understand the feature 'language_supports_threads' and the 'supported'
- attribute is therefore set to '1', but as PHP does not support threads,
- the returned value is in this case "0".</p>
- </div>
- <div class="section" id="feature-set">
- <h3><a class="toc-backref" href="#id41">7.2.3 feature_set</a></h3>
- <p>The feature set command allows a IDE to tell the debugger engine what additional
- capabilities it has. One example of this would be telling the debugger engine
- whether the IDE supports multiple debugger sessions (for threads, etc.). The
- debugger engine responds with telling the IDE whether it has enabled the feature
- or not.</p>
- <p>Note: The IDE does not have to listen for additional debugger connections if it
- does not support debugging multiple sessions. debugger engines must handle
- connection failures gracefully.</p>
- <p>arguments for feature_set include:</p>
- <blockquote>
- <table border="1" class="docutils">
- <colgroup>
- <col width="5%" />
- <col width="95%" />
- </colgroup>
- <tbody valign="top">
- <tr><td>-n</td>
- <td>feature_name</td>
- </tr>
- <tr><td>-v</td>
- <td>value to be set</td>
- </tr>
- </tbody>
- </table>
- </blockquote>
- <p>feature_set can be called at any time during a debug session to
- change values previously set. This allows a IDE to change
- encodings.</p>
- <p>IDE</p>
- <pre class="literal-block">
- feature_set -i transaction_id -n feature-name -v value
- </pre>
- <p>debugger engine</p>
- <pre class="literal-block">
- <response command="feature_set"
- feature="feature_name"
- success="0|1"
- transaction_id="transaction_id"/>
- </pre>
- </div>
- </div>
- <div class="section" id="continuation-commands">
- <h2><a class="toc-backref" href="#id42">7.5 continuation commands</a></h2>
- <p>resume the execution of the application.</p>
- <dl class="docutils">
- <dt>run:</dt>
- <dd>starts or resumes the script until a new breakpoint is reached,
- or the end of the script is reached.</dd>
- <dt>step_into:</dt>
- <dd>steps to the next statement, if there is a function call
- involved it will break on the first statement in that function</dd>
- <dt>step_over:</dt>
- <dd>steps to the next statement, if there is a function call on the
- line from which the step_over is issued then the debugger engine
- will stop at the statement after the function call in the same
- scope as from where the command was issued</dd>
- <dt>step_out:</dt>
- <dd>steps out of the current scope and breaks on the statement after
- returning from the current function. (Also called 'finish' in
- GDB)</dd>
- <dt>stop:</dt>
- <dd>ends execution of the script immediately, the debugger engine may
- not respond, though if possible should be designed to do so.
- The script will be terminated right away and be followed by a
- disconnection of the network connection from the IDE (and debugger
- engine if required in multi request apache processes).</dd>
- <dt>detach (optional):</dt>
- <dd>stops interaction with the debugger engine. Once this command
- is executed, the IDE will no longer be able to communicate with
- the debugger engine. This does not end execution of the script
- as does the stop command above, but rather detaches from debugging.
- Support of this continuation command is optional, and the IDE should
- verify support for it via the feature_get command. If the IDE has
- created stdin/stdout/stderr pipes for execution of the script
- (eg. an interactive shell or other console to catch script output),
- it should keep those open and usable by the process until the process
- has terminated normally.</dd>
- </dl>
- <p>The response to a continue command is a status response (see
- status above). The debugger engine does not send this response
- immediately, but rather when it reaches a breakpoint, or ends
- execution for any other reason.</p>
- <p>IDE</p>
- <pre class="literal-block">
- run -i transaction_id
- </pre>
- <p>debugger engine</p>
- <pre class="literal-block">
- <response command="run"
- status="starting"
- reason="ok"
- transaction_id="transaction_id"/>
- </pre>
- </div>
- <div class="section" id="breakpoints">
- <h2><a class="toc-backref" href="#id43">7.6 breakpoints</a></h2>
- <p>Breakpoints are locations or conditions at which a debugger engine
- pauses execution, responds to the IDE, and waits for further commands
- from the IDE. A failure in any breakpoint commands results in an
- error defined in <a class="reference internal" href="#debugger-engine-errors">section 6.5</a>.</p>
- <p>The following DBGP commands relate to breakpoints:</p>
- <blockquote>
- <table border="1" class="docutils">
- <colgroup>
- <col width="27%" />
- <col width="73%" />
- </colgroup>
- <tbody valign="top">
- <tr><td><a class="reference internal" href="#id1">breakpoint_set</a></td>
- <td>Set a new breakpoint on the session.</td>
- </tr>
- <tr><td><a class="reference internal" href="#id2">breakpoint_get</a></td>
- <td>Get breakpoint info for the given breakpoint id.</td>
- </tr>
- <tr><td><a class="reference internal" href="#id3">breakpoint_update</a></td>
- <td>Update one or more attributes of a breakpoint.</td>
- </tr>
- <tr><td><a class="reference internal" href="#id4">breakpoint_remove</a></td>
- <td>Remove the given breakpoint on the session.</td>
- </tr>
- <tr><td><a class="reference internal" href="#id5">breakpoint_list</a></td>
- <td>Get a list of all of the session's breakpoints.</td>
- </tr>
- </tbody>
- </table>
- </blockquote>
- <p>There are six different breakpoints <em>types</em>:</p>
- <blockquote>
- <table border="1" class="docutils">
- <colgroup>
- <col width="21%" />
- <col width="17%" />
- <col width="62%" />
- </colgroup>
- <thead valign="bottom">
- <tr><th class="head">Type</th>
- <th class="head">Req'd Attrs</th>
- <th class="head">Description</th>
- </tr>
- </thead>
- <tbody valign="top">
- <tr><td>line</td>
- <td>filename,
- lineno</td>
- <td>break on the given lineno in the given
- file</td>
- </tr>
- <tr><td>call</td>
- <td>function</td>
- <td>break on entry into new stack for
- function name</td>
- </tr>
- <tr><td>return</td>
- <td>function</td>
- <td>break on exit from stack for function
- name</td>
- </tr>
- <tr><td>exception</td>
- <td>exception</td>
- <td>break on exception of the given name</td>
- </tr>
- <tr><td>conditional</td>
- <td>expression,
- filename</td>
- <td>break when the given expression is true
- at the given filename and line number or
- just in given filename</td>
- </tr>
- <tr><td>watch</td>
- <td>expression</td>
- <td>break on write of the variable or address
- defined by the expression argument</td>
- </tr>
- </tbody>
- </table>
- </blockquote>
- <p>A breakpoint has the following attributes. Note that some attributes are only
- applicable for some breakpoint types.</p>
- <blockquote>
- <table border="1" class="docutils">
- <colgroup>
- <col width="24%" />
- <col width="76%" />
- </colgroup>
- <tbody valign="top">
- <tr><td>type</td>
- <td>breakpoint type (see table above for valid types)</td>
- </tr>
- <tr><td>filename</td>
- <td>The file the breakpoint is effective in. This must be
- a "<a class="reference external" href="file://">file://</a>" or "dbgp:" (See <a class="reference internal" href="#dynamic-code-and-virtual-files">6.7 Dynamic code and
- virtual files</a>) URI.</td>
- </tr>
- <tr><td>lineno</td>
- <td>Line number on which breakpoint is effective…
Large files files are truncated, but you can click here to view the full file