Suggested updates to JS debugger protocol

[vlidholt]

These are suggested updates to the JS debugger protocol for a first stable version that could be used with a visual client (e.g. CocosBuilder).

Commands sent to the debugger are in similar format as of now, supported commands include:

• break filename:number - set a breakpoint
• break - break where we are currently executing (if possible to implement)
• clear filename:number - clear a breakpoint
• clear - clear all breakpoints
• continue
• step
• backtrace
• eval
• deval

The responses from the debugger is in json format similar to this:

{
    "cmd" : "<the command>",
    "data" : <a data structure associated with the specific command>
}

The following responses are supported:

• break - sent whenever the debugger breaks, data includes file name and line number
• eval - sent as a response to the eval command, data includes a string with the evaluation
• backtrace - send as a response to the eval command, data includes the backtrace at the current break point
• invalidbreak - sent if an invalid breakpoint is being set, data includes file name and line number

[folecr]

Also we should have an error response

• error

[folecr]

FYI : here is the documentation for Firefox's remote debugging protocol. https://wiki.mozilla.org/Remote_Debugging_Protocol

It is not suited for use directly because

1. the scope is very large
2. it seems to be closely integrated with the browser itself.

It is a good reference.

[folecr]

https://github.com/zynga/jsbindings/pull/74

[folecr]

https://github.com/zynga/jsbindings/pull/75

[folecr]

With the above commits I think we should be have a good set of commands and responses to start with for integrating the debugger into CocosBuilder.

Let's leave this issue open to discuss any changes to the protocol for the first release.

[vlidholt]

Could you post example responses and how the commands you have implemented works here?

[folecr]

Below is an example session with commands and responses

telnet 127.0.0.1 1337
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
break ActionsTest.js:56
{"from":"server","why":"commandresponse","data":{"commandname":"break","success":true,"jsfilename":"ActionsTest.js","breakpointlinenumber":56}}
{"from":"server","why":"onBreakpoint","data":{"jsfilename":"/Users/folecr/Library/Developer/Xcode/DerivedData/cocos2d-tests-osx-adcmcrlxtnomuwazntgvsmwqtpaa/Build/Products/Debug/JS Tests.app/Contents/Resources/ActionsTest/ActionsTest.js","linenumber":56}}
step
{"from":"server","why":"commandresponse","data":{"commandname":"step","success":true,"stringResult":""}}
{"from":"server","why":"onStep","data":{"jsfilename":"/Users/folecr/Library/Developer/Xcode/DerivedData/cocos2d-tests-osx-adcmcrlxtnomuwazntgvsmwqtpaa/Build/Products/Debug/JS Tests.app/Contents/Resources/ActionsTest/ActionsTest.js","linenumber":57}}
continue
{"from":"server","why":"commandresponse","data":{"commandname":"continue","success":true,"stringResult":""}}
clear
{"from":"server","why":"commandresponse","data":{"commandname":"clear","success":true,"stringResult":"clearing all breakpoints"}}

[ricardoquesada]

Could we disable the json answers by default ? it is going to be more user friendly for the command-line users.

The idea is that the JSON responses should be disabled by default. And the first thing that CCB does is to enable the JSON responses.

eg:

telnet 127.0.0.1 1337
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
enable json-responses
{"from":"server","why":"commandresponse","data":{"commandname":"enable","success":true}}

disable json-responses
OK

[folecr]

These changes have been committed and released. Closing this ticket now. Please open new tickets for any future features/bugs for the JS Debugger.