Debugger Protocol
Edit

Debugger Protocol

Overview

A reference to the Studio Debugger Protocol used in Aptana Studio, Titanium Studio and Appcelerator Studio.

Request packet format:

length*request_id*command*arg0*arg1*arg2*...argN

Reply packet format:

length*request_id*arg0*arg1*arg2*...argN

Unsolicited message format:

length*message*arg0*arg1*arg2*...argN

where:

  • length : integer value of the remaining part of a packet

  • request_id : any string identifying request/response

  • command : request command name

  • message : unsolicited message name

  • arg0..N : command/response specific arguments

An argument could be split into sub-arguments:

arg=subarg0|subarg1|subarg2|...subargN

Requests with empty request_id should not be replied.

Arguments encoding

All the arguments (args and subargs) should have the following set of characters encoded:

  • # => #0

  • | => #1

  • * => #2

Commands

Get debugger extension version

Command: version
Request arguments: none
Reply arguments:

  • arg0 : debugger protocol version (currently are 1 or 2)

  • arg1 : debugger extension/addon version

Example:

=> 1176979825719*version
<= 1176979825719*1*0.2.8.14083

Force debugger extension update

Command: update
Request arguments: none
Reply arguments:

  • arg0 : (optional) version of updated debugger extension/addon (if available)

Example:

=> 1176979825720*update
<= 1176979825720*0.2.8.15000

Set debugger options

Command: option
Request arguments:

  • arg0 : name of an option

  • arg1 : new value of an option

Reply arguments: none
Example:

=> 1176979825721*option*suspendOnFirstLine*false
<= 1176979825721

Turn on debug mode

Command: enable
Request arguments: none
Reply arguments: none
Example:

=> 1176979825726*enable
<= 1176979825726

Turn off debug mode

Command: disable
Request arguments: none
Reply arguments: none
Example:

=> 1176979825727*disable
<= 1176979825727

Terminate session

Command: terminate
Request arguments: none
Reply arguments: none
Example:

=> 1176979825820*terminate
<= 1176979825820

Create/modify/remove breakpoint

Command: breakpoint
Request arguments:

  • arg0 : name of an action (allowed actions: create, change, remove)

  • arg1 : URI of a file

  • arg2 : line number

  • arg3 : breakpoint state (1 - enabled, 0 - disabled)

  • arg4 : hit count (no hit count if value is less or equal to 0)

  • arg5 : condition expression string (no condition if empty)

  • arg6 : condition meaning (1 - on true, 0 - on expression value change)

Reply arguments:

  • arg0 : action result status (created, changed, removed)

Example:

=> 1176979825728*breakpoint*create*http://127.0.0.1:8000/debug_tests.html*116*1*0**1
<= 1176979825728*created
=> 1176979825729*breakpoint*remove*http://127.0.0.1:8000/debug_tests.html*116
<= 1176979825729*removed

Create/modify/remove exception breakpoints

Command: exception
Request arguments:

  • arg0 : name of an action (allowed actions: create, change, remove)

  • arg1 : exception type name

Reply arguments:

  • arg0 : action result status (created, changed, removed)

Example:

=> 1176979825729*exception*create*TypeError
<= 1176979825729*created

Set detail formatters

Command: detailFormatters
Request arguments:

  • arg0..argN : detail formatters 0-N

  • subarg0 : type name

  • subarg1 : formatter expression text

Reply arguments: none
Example:

=> 1176979825730*detailFormatters*Date|this.toGMTString();
<= 1176979825730

Open page URL

Command: openURL
Request arguments:

  • arg0 : page URI to open

Reply arguments: none
Example:

=> 1176979825729*openUrl*http://127.0.0.1:8000/debug_tests.html
<= 1176979825729

Get file sources

Command: getSource
Request arguments:

  • arg0 : file URI to retrieve sources

Reply arguments:

  • arg0 : command status (success, failure)

  • arg1 : file contents

Example:

=> 1176979825730*getSource*http://127.0.0.1:8000/debug_tests.html
<= 1176979825730*success*<html><body></body></html>

Suspend script execution

Command: suspend
Request arguments (version 1): none
Request arguments (version 2):

  • arg0 : thread id

Reply arguments: none
Example:

=> 1176979825731*suspend
<= 1176979825731
=> 1176979825731*suspend*2
<= 1176979825731

Resume script execution

Command: resume
Request arguments (version 1): none
Request arguments (version 2):

  • arg0 : thread id

Reply arguments: none
Example:

=> 1176979825732*resume
<= 1176979825732
=> 1176979825732*resume*2
<= 1176979825732

Step into

Command: stepInto
Request arguments (version 1): none
Request arguments (version 2):

  • arg0 : thread id

Reply arguments: none
Example:

=> 1176979825733*stepInto
<= 1176979825733
=> 1176979825733*stepInto*2
<= 1176979825733

Step over

Command: stepOver
Request arguments (version 1): none
Request arguments (version 2):

  • arg0 : thread id

Reply arguments: none
Example:

=> 1176979825734*stepOver
<= 1176979825734
=> 1176979825734*stepOver*2
<= 1176979825734

Step return

Command: stepReturn
Request arguments (version 1): none
Request arguments (version 2):

  • arg0 : thread id

Reply arguments: none
Example:

=> 1176979825735*stepReturn
<= 1176979825735
=> 1176979825735*stepReturn*2
<= 1176979825735

Step to frame

Command: stepToFrame
Request arguments (version 1):

  • arg0 : frame id to step to

Request arguments (version 2):

  • arg0 : thread id

  • arg1 : frame id to step to

Reply arguments: none
Example:

=> 1176979825736*stepToFrame*2
<= 1176979825736
=> 1176979825736*stepToFrame*2*2
<= 1176979825736

Get stack frames

Command: frames
Request arguments (version 1): none
Request arguments (version 2):

  • arg0 : thread id

Reply arguments:

  • arg0..argN : frames 0-N

  • subarg0 : frame id

  • subarg1 : frame/function name

  • subarg2 : function arguments separated by ", "

  • subarg3 : file URI

  • subarg4 : line number

  • subarg5 : function native flag (temporary unused)

  • subarg6 : engine's internal frame PC (if available)

  • subarg7 : function's script id

Example:

=> 1176979825740*frames
<= 1176979825740*0|testVariables||http://127.0.0.1:8000/debug_tests.html|166|false|226|238*1|onclick|MouseEvent|http://127.0.0.1:8000/debug_tests.html|1|false|4|261
=> 1176979825740*frames*2
<= 1176979825740*0|testVariables||http://127.0.0.1:8000/debug_tests.html|166|false|226|238*1|onclick|MouseEvent|http://127.0.0.1:8000/debug_tests.html|1|false|4|261

Get variables

Command: variables
Request arguments (version 1):

  • arg0 : variable name

Request arguments (version 2):

  • arg0 : thread id

  • arg1 : variable name

Reply arguments:

  • arg0..argN : variable properties 0-N

  • subarg0 : property name

  • subarg1 : property type

  • subarg2 : property flags (see #Variable property flags)

  • subarg3 : property value

See #Special variables.

Example:

=> 1176979825731*variables*frame[0]
<= 1176979825731*this|Window|o|[object Window]*vArray|Array|lowpv|item0,,,itemN*vBool|Boolean|lwpv|false*vDate|Date|lwpv|Thu Apr 19 2007 17:50:33 GMT+0700*vError|Error|lowpv|Error*vMyObj|MyObject|lowpv|[object Object]*vNum|Number|lwpv|7*vObj|Object|lowpv|[object Object]*vObj2|Object|lowpv|Object toString() method is used here*vRect|Shape|lowpv|[object Object]*vStr|String|lwpv|"Hello, World!"
=> 1176979825733*variables*eval[0]
<= 1176979825733*height|integer|wn|1*type|String|wn|"rect"*width|integer|wn|1*x|integer|wn|0*y|integer|wn|0
=> 1176979825733*variables*2*eval[0]
<= 1176979825733*height|integer|wn|1*type|String|wn|"rect"*width|integer|wn|1*x|integer|wn|0*y|integer|wn|0

Get variable details

Command: details
Request arguments (version 1):

  • arg0 : variable name

Request arguments (version 2):

  • arg0 : thread id

  • arg1 : variable name

Reply arguments:

  • arg0 : command status (result)

  • arg1 : detailed value (toString representation)

Example:

=> 1176979825734*details*frame[0].vRect
<= 1176979825734*result*{x: 0, y: 0, w: 10, h: 10}
=> 1176979825734*details*2*frame[0].vRect
<= 1176979825734*result*{x: 0, y: 0, w: 10, h: 10}

Evaluate expression

Command: eval
Request arguments (version 1):

  • arg0 : evaluation context (variable name)

  • arg1 : expression

Request arguments (version 2):

  • arg0 : thread id

  • arg1 : evaluation context (variable name)

  • arg2 : expression

Reply arguments:

  • arg0 : command status (result, exception)

  • arg1 : evaluation id or exception text

  • arg2 : evaluation result

  • subarg0 : property type

  • subarg1 : property flags (see #Variable property flags)

  • subarg2 : property value

Example:

=> 1176979825732*eval*frame[0]*vRect
<= 1176979825732*result*0*Shape|ow|[object Object]
or
<= 1176979825732*exception*Undefined variable
=> 1176979825732*eval*2*frame[0]*vRect
<= 1176979825732*result*0*Shape|ow|[object Object]

Change variable value

Command: setValue
Request arguments (version 1):

  • arg0 : variable name

  • arg1 : value reference name

Request arguments (version 2):

  • arg0 : thread id

  • arg1 : variable name

  • arg2 : value reference name

Reply arguments:

  • arg0 : command status (result, exception)

  • arg1 : value property or exception text

  • subarg0 : property type

  • subarg1 : property flags (see [aptanastudiodev:#Variable property flags])

  • subarg2 : property value

Example:

=> 1176979825735*setValue*frame[0].vRect2*eval[1]
<= 1176979825735*result*String|w|Hello!
=> 1176979825735*setValue*2*frame[0].vRect2*eval[1]
<= 1176979825735*result*String|w|Hello!

Unsolicited messages

Suspend notification

Message: suspended
Message arguments (version 1):

  • arg0 : suspend reason (breakpoint, keyword, requested, exception, firstLine or any of stepping command names)

  • arg1 : top frame's file URI

  • arg2 : top frame's line number

Message arguments (version 2):

  • arg0 : thread id

  • arg1 : suspend reason (breakpoint, keyword, requested, exception, firstLine or any of stepping command names)

  • arg2 : top frame's file URI

  • arg3 : top frame's line number

Example:

<= suspended*keyword*http://127.0.0.1:8000/debug_tests.html*166
<= suspended*stepInto*http://127.0.0.1:8000/debug_tests.html*167
<= suspended*2*keyword*http://127.0.0.1:8000/debug_tests.html*166
<= suspended*2*stepInto*http://127.0.0.1:8000/debug_tests.html*167

Resume notification

Message: resumed
Message arguments (version 1):

  • arg0 : resume reason (started, abort or any of stepping command names)

Message arguments (version 2):

  • arg0 : thread id

  • arg1 : resume reason (started, abort or any of stepping command names)

Example:

<= resumed*start
<= resumed*stepInto
<= resumed*resume
<= resumed*2*start
<= resumed*2*stepInto
<= resumed*2*resume

Client action notifications

Message: client
Message arguments:

  • arg0 : action (suspend, terminate, open)

  • arg1..argN : optional action arguments

suspend : request to suspend debugger (all threads)
terminate : request to terminate debugger session
open : request to open file/URI in IDE editor

  • arg1 : file URI

Example:

<= threads*created*1*main
<= threads*created*2*worker
<= threads*destroyed*2

Log console message

Message: log
Message arguments:

  • arg0 : log type (out, warn, err)

  • arg1 : message text

  • arg2 : (optional) source context (src, trace)

src:

  • arg3 : file URI

  • arg4 : line number

trace:

  • arg3..argN : trace frame descriptions 3-N

  • subarg0 : frame/function name

  • subarg1 : function arguments separated by ", "

  • subarg2 : file URI

  • subarg3 : line number

Example:

<= log*out*Start message
<= log*out*src*http://127.0.0.1:8000/debug_tests.html*170
<= log*out*trace*testVariables||http://127.0.0.1:8000/debug_tests.html|166*onclick|MouseEvent|http://127.0.0.1:8000/debug_tests.html|1

Scripts notification

Message: scripts
Message arguments:

  • arg0 : action (created, resolved, destroyed)

  • arg1..argN : scripts definitions 1-N

created:

  • subarg0 : script id

  • subarg1 : file URI

  • subarg2 : function name

  • subarg3 : base script line number

  • subarg4 : script line count

resolved:

  • subarg0 : script id

  • subarg1 : function name

destroyed:

  • subarg0 : script id

Example:

<= scripts*created*225|http://127.0.0.1:8000/debug_tests.html|testStepping|26|8
<= scripts*created*234|http://127.0.0.1:8000/debug_tests.html|anonymous|137|1
<= scripts*resolved*234|toString*240|myFunc0*241|myFunc1*242|myFunc2*252|onreadystatechange
<= scripts*destroyed*234*235*236

Threads notification (Version 2)

Message: threads
Message arguments:

  • arg0 : action (created, destroyed)

  • arg1 : thread id

  • arg2 : thread name (optional)

Example:

<= threads*created*1*main
<= threads*created*2*worker
<= threads*destroyed*2

Appendix

Variable property flags

  • w : writable (assignment will lead to an error)

  • c : constant (the property is a real constant, may not be supported on all platforms)

  • n : enumeratable (visible to for/in loop)

  • p : permanent (property cannot be deleted)

  • a : argument to function

  • v : local variable in function

  • l : local/scope variable (top-level in scope)

  • e : exception (exception occurred, value is exception)

  • r : error (error occurred, value is error)

  • o : object/composite value (expandable, has properties)

Special variables

When the debugger suspend was caused by an exception and the exception details are available, the exception variable (with the 'e' property flag) should be returned on the top scope. If the debugger allows to change/reject the exception, the variable should also have 'w' writable property.