Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/swojtasiak/jsrdbg

JavaScript Remote Debugger for SpiderMonkey.
https://github.com/swojtasiak/jsrdbg

debugger debugger-engine javascript shared-library spidermonkey-engine

Last synced: 3 months ago
JSON representation

JavaScript Remote Debugger for SpiderMonkey.

Awesome Lists containing this project

README 

          
JavaScript Remote Debugger

==========================



The following chapters describe some of the most important features of

the project.



What it is for?

---------------



This is an implementation of a high level debugging protocol for

SpiderMonkey engine which is available as a shared library. The library

can be used to integrate debugging facilities into an existing

application leveraging SpiderMonkey engine. There are several

integration possibilities including exposition of the high level

debugger API locally directly to the application and even exposing it to

remote clients using full duplex TCP/IP communication.



The project consists of two main parts. The debugger engine itself in a

form of shared library and the standalone console client application

used to connect to the debugger remotely. It's a simple console based

implementation whose idea is similar to GNU debugger.



Architecture, integration and remote client are described in the

following chapters.



Install

-------



### Linux



#### Dependencies



Besides a working C++ compiler you need a few additional dependencies to

compile jsrdbg.



On Fedora:



~~~~ {.sh}

sudo dnf install \

    autoconf \

    autoconf-archive \

    automake \

    gettext-devel \

    libtool \

    mozjs24-devel \

    readline-devel

~~~~



On Ubuntu:



~~~~ {.sh}

sudo apt-get install \

    autoconf \

    autoconf-archive \

    build-essential \

    gettext \

    libmozjs-24-dev \

    libreadline-dev \

    libtool \

    pkg-config

~~~~



Note: If you haven't installed mozjs-24 with your distribution's package

manager you probably have to tell pkg-config where to find the

`mozjs-24.pc` file. You can do this by setting the `PKG_CONFIG_PATH`

environment variable appropriately, e.g.



~~~~ {.sh}

$ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig

~~~~



On Linux, you can build jsrdbg with the usual

`./configure && make && make install` like so



~~~~ {.sh}

$ autoreconf -i

$ ./configure

$ make

$ sudo make install

~~~~



### Windows



On Windows, jsrdbg provides Visual Studio project files in the `win/`

directory to create a Windows DLL. We have tested building jsrdbg with

Visual Studio 2012 but it should work with any later version as well.



It is important that you checkout the win-iconv submodule that is

referenced by the jsrdbg Git repository when compiling on Windows. You

can do this by either cloning the repository as follows



    git clone --recursive https://github.com/swojtasiak/jsrdbg.git



or by checking out the submodule after the fact like this:



    git submodule init

    git submodule update



Additionally, you need to set two environment variables to let Visual

Studio know where to find the SpiderMonkey header files at compile-time

and the SpiderMonkey import library at link-time. Make sure to set both

environment variables to the appropriate paths before opening Visual

Studio.



    set MOZJS_INCLUDE_DIR=C:\mozjs-24\include\js

    set MOZJS_LIB_PATH=C:\mozjs-24\lib\mozjs-24.lib



Then build the solution with Visual Studio Solution as usual.



Note: On Windows, jsrdbg logs to a file by default. (On Linux, jsrdbg

logs via the syslog(3) facility, which is of course unavailable on

Windows.) You can specify the log file by setting the

`JSRDBG_LOG_FILE_PATH` environment variable before starting your

program, e.g.



    set JSRDBG_LOG_FILE_PATH=C:\Users\test\Desktop\jsrdbg.log



If the environment variable is not set, jsrdbg does not write any logs.



How to integrate

----------------



There are plenty of ways how an application can be integrated with a

debugger, but the easier one is probably to integrate it with a remote

debugger which is based on TCP/IP connections. It's probably the best

choice, due to the fact that integration is really simple and the

debugger is fully functional without any additional work, which is

needed in case of the local debugger implementation. In order to

integrate with the local debugger you have to inherit from an abstract

debugger implementation and provide some methods that are exposed by the

class.



As has been said, the integration process is really simple and can be

completed in a few lines of code. The working example is available in

the "example" directory in the project root directory. The example

itself is really simple, the character encoding is broken and there is

almost no error handling, but it shows how the process of integration

looks like.



Having working SpiderMonkey engine embedded in your code, everything you

have to do is to create a new instance of the JSRemoteDebugger class

which needs JSRemoteDebuggerCfg instance when initialized. Notice that

the debugger itself is not connected to any specific JSRuntime and

JSContext instance. It's designed to make integration of various

JSContexts as simple as possible. Everything you have to care about is

to make sure that you call debuggers methods using the same threads that

are to run JS runtimes. So it's entirely possible to use only one

debugger instance bounded to one specific TCP/IP port to handle all

JSContexts within a process.



Initializing a remote debugger instance you can provide dedicated

configuration for the remote debugger itself as well as directly for a

debugger engine. That is, two of the available implementations (local

and remote) use the same high level debugger engine under the hood, so

they share the same set of configuration options.



So being familiar with that, we can try to prepare fully configured

remote debugger instance for our own application. Let's say we need to

bind it only to the localhost and to the default TCP/IP port 8089. We

also would like the debugger to suspend as soon as a debuggee started in

order to debug the script from the beginning. Nothing easier than that:



~~~~ {.cpp}

JSRemoteDebuggerCfg cfg;

cfg.setTcpHost("localhost");

cfg.setTcpPort(JSR_DEFAULT_TCP_PORT);

cfg.setScriptLoader(&loader);



JSRemoteDebugger dbg( cfg );

~~~~



In the first line the new configuration object is created. It's the

mentioned dedicated configuration for the remote debugger

implementation. In the second and third line two configuration options

are set. The first one is the host we would like to listen on and the

next one is the TCP/IP port. That's basically all we have to do here.

There is one more important option around: 'scriptLoader', which can be

used to provide scripts source code for the debugging engine, but let's

leave it for now. The last one can be used to choose between available

protocols supported by the debugger, but currently only TCP/IP is

supported which is a default protocol, so for now this option is

useless.



In the last line an instance of remote debugger is being created for our

configuration options prepared earlier.



Having the debugger created you have to install it. In order to

understand the installation process you have to be aware of one

important fact. The core of the debugger engine is implemented in

JavaScript language and it runs in the same virtual machine which is

debugged by the debugger engine. Of course there is plenty of C++ code

which handles whole communication etc., but the debugger itself is a

pure JavaScript code which uses some provided native interfaces to

exchange communicates with the C++ part. Therefore the installation

procedure of the debugger engine is neither more nor less about creating

dedicated compartment inside existing SpiderMonkey engine and running a

bootstrapping code which registers the debugger. In order to do it you

have to call a dedicated method: 'install' exposed by debugger instance.

The method gets three arguments: JSContext which we would like to debug.

A name of the context which is just a kind of identifier used on the

client level just in order to communicate with concrete context

instance. The last one holds debugger engine configuration parameters

JSDbgEngineOptions.



When the installation is completed you have your debugger engine up and

running, but we need a way to do some interaction with it. Protocol

mentioned before is responsible for exposing communication interface. In

our case it's TCP/IP protocol, so the next thing we have to do is to

start the TCP/IP server handling the communication logic. Of course this

logic is also hidden under a layer of abstraction, therefore everything

that has to be done is to call another parameter-free method: 'start' on

debugger instance. Remember that the protocol exposed by the debugger is

fully asynchronous one and the whole communication is handled by a full

duplex TCP/IP server. It's why there is a new thread started in the

background after calling 'start' method.



OK, that's pretty much everything you have to do in order to connect to

the debugger remotely. So let's look at the source code:



~~~~ {.cpp}

JSDbgEngineOptions dbgOptions;

dbgOptions.suspended();



if( dbg.install( cx, 'example-js-context', dbgOptions ) != JSR_ERROR_NO_ERROR ) {

    cout << "Cannot install debugger." << endl;

    return false;

}



if( dbg.start() != JSR_ERROR_NO_ERROR ) {

    dbg.uninstall();

    cout << "Cannot start debugger." << endl;

    return false;

}

~~~~



The lines first and second are responsible for providing options for the

debugger engine. Currently only three options are available. The first

one called 'suspended' can be used to start debugger in the suspended

mode mentioned before, 'continueWhenNoConnections' which should be set

if we would like to make the debugging application continue when all

remote client have disconnected and the last one 'sourceDisplacement'

used to synchronize source code position if JS engine being debugged

messes up with line numbers.



The rest of the code explains itself. Only one thing that might be

really interesting here is the model of error handling. Every method

exposed by the debugging engine returns one of the unified error codes.

All the codes are available in the following header file:

jsrdbg/jsdbg\_common.h. Bear in mind that it's up to you to uninstall

every context correctly before deleting the debugger. Debugger cannot do

it automatically just because every 'uninstall' invocation has to be

done on dedicated thread, the same which runs the JS engine being

unregistered.



Debugger is up and running now, but you have to add every compartment

you would like to debug into the debugger, by providing its JS global

object. It can be done using 'addDebuggee' method like as in the

following code:



~~~~ {.cpp}

if( dbg.addDebuggee( cx, global ) != JSR_ERROR_NO_ERROR ) {

    dbg.uninstall( cx );

    cout << "Cannot add debuggee." << endl;

    return false;

}

~~~~



That's all. If you have done all the steps correctly there is much a

chance that everything works and you should be able to use jrdb client

in order to make a remote connection to the debugger.



Of curse it's a very young project, so there is always a risk of a nasty

bug or something, so do not hesitate to report everything or provide a

patch if you find something.



As was said before, there is also a local debugger available, but its

integration is quite complex. There is 'check' subproject which is used

to run all unit tests. Take a look at it in order to get a real example

of its usage.



Remote client

-------------



Inside 'jrdb' directory, there is a simple remote debugger client

available. It was designed and implemented having gdb in mind, so it's

quite similar to the gdb, but only a small subset of all gdb commands is

implemented for now.



Anyway the client is not the most convenient one as it doesn't use

ncurses, but it's definitely better than nothing :-). I will probably

prepare a client with a real GUI in the future, but I don't have time

for it now.



Ok, so let's start with a simple example.



First of all go to the example directory and build the provided example.

It's a very simple application which runs an embedded JS script and

exposing remote debugger instance. The application binds to all

interfaces and uses the default TCP/IP port 8089. In order to build

everything go to the example directory and run:



~~~~ {.sh}

$ autoreconf -i

$ ./configure

$ make

~~~~



Bear in mind that the project uses pkg-config to find libjsrdbg shared

library. So you have to install jsrdbg and make sure that

`PKG_CONFIG_PATH` is set correctly. For instance, if you are installing

the project in /usr/local, then there is always a risk that you will

have to set the following environment variable:



~~~~ {.sh}

$ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig

~~~~



It depends if your system handles this location by default.



Now after building the example, you have the following application in

the "src" directory: jsrdbg\_example.



Just run it.



It should print the following messages into the standard output:



    $ src/jsrdbg_example

    Use jrdb command in order to connect to the debugger.

    Application is suspended.



OK, it means that application has been started in the suspended mode

described before and is waiting for new connections. It uses the default

TCP/IP port, so everything that has to be done to connect it is to run

jrdb.



First of all type --help parameter in order to get all available

arguments:



~~~~ {.sh}

$ jrdb --help

~~~~



Then start the client:



    $ jrdb

    JavaScript Remote Debugger Client connected to a remote debugger.

    Waiting for a list of JavaScript contexts being debugged.

    Type "help context" for more information.

    Available JSContext instances:

    0) example-JS (PAUSED)

    There is only one JSContext managed by the debugger, so it has been chosen as

    the current one. You can change it using the "context" command.

    jrdb>



As you can see the client informed us that debugger we are connected to

provides one paused JSContext which can be debugged. As there is only

one context, it has been chosen as the current one by default. Type

'help context' in order to get more comprehensive explanation.



The jsrd\> prompt means that the client is waiting for commands. So try

to type the most important one:



    jrdb> help

    List of available commands.



    set - Sets environment variables

    env - Prints environment variables

    pc - Prints information about current frame

    step - Steps to a next instruction

    next - Steps to a next instructions going through subroutines

    continue - Continues execution of the program being debugged

    stop - Terminates a debuggee.

    break,pause - Pauses the program being debugged or sets breakpoints

    delete - Deletes breakpoints

    info - List information about program being debugged

    list - Prints source code of the script being debugged

    backtrace - Prints backtrace of stack frames

    print - Evaluates expressions

    version - Shows application version

    source - Loads script source code

    animation - Enables/disables stepping animation

    jrdb>



As you can see it's not the most sophisticated one. It just prints some

information about supported commands, so it's definitely one of the most

helpful ones :-). In order to get more comprehensive description of

every command you can type its name as an argument:



    jrdb> help list

    Lists number of source code lines starting from the

    location where debuggee is paused. When run first time

    it requests for the whole source code of the script being

    debugged and caches it. It's why first call for a particular

    script can be a bit slower.

    Usage:

    list [n]

    l [n]

    [n] - Number of source lines to print.

    jrdb>



OK, so instead of describing every command available, let's do some

exercises using the example application started a moment ago. First of

all type 'pc' and hit enter. You should see something like that:



    jrdb> pc

    Script: example.js

    Line: 0

    jrdb>



It means that we are paused inside the "example.js" script at line 0.

Ok, so it would be definitelly helpful if we have an opportunity to see

a piece of source code at this location. Nothing easier than that:



    jrdb> l

     0* debugger;

     1  print('Hello. ');

     2  (function(fn) {

     3      print('Yes, ');

     4      fn('this is dog.');

     5  })(function(msg) {

     6      print(msg);

     7  });

     8  print('Woof, woof.');

     9  debugger;

    jrdb>



The 'list' command can be used to show a number of source lines just

after the point where debugger is currently paused. The asterisk after

the line number tells us where we are paused. In this particular case we

are paused on 'debugger' statement which is quite interesting one,

because it can be used directly in the code as a breakpoint in order to

make the debugger pause the application. OK, so let's step through the

next few instructions.



    jrdb> s

    1 print('Hello. ');

    jrdb> s

    2 (function(fn) {

    jrdb> s

    5 })(function(msg) {

    jrdb> s

    2 (function(fn) {

    jrdb> s

    3     print('Yes, ');

    jrdb> l

     3*     print('Yes, ');

     4      fn('this is dog.');

     5  })(function(msg) {

     6      print(msg);

     7  });

     8  print('Woof, woof.');

     9  debugger;

    10

    jrdb>



As you can see we have gone through a few source code lines using 'step'

instruction and after doing it we are paused at the third line. There is

one argument to the function we are in. It's 'fn'. Let's see what it is.

It can be done using print function, which is used to evaluate code:



    jrdb> p fn

    {

      "___jsrdbg_function_desc___": {

        "parameterNames": [

          "msg"

        ]

      },

      "prototype": {

        "___jsrdbg_collapsed___": true

      },

      "length": 1,

      "name": "",

      "arguments": null,

      "caller": null

    }

    jrdb>



So it's an anonymous function with one argument 'msg'.



Hmm, 'print' evaluates code. So let's try to do something strange:



    jrdb> p fn = function() { debugger; };

    {

      "___jsrdbg_function_desc___": {

        "displayName": "fn",

        "parameterNames": []

      },

      "prototype": {

        "___jsrdbg_collapsed___": true

      },

      "length": 0,

      "name": "",

      "arguments": null,

      "caller": null

    }

    jrdb> c

    debugger eval code

    1

    jrdb>



What has just happened? It's a bit tricky but in fact very simple. The

mentioned print method is used to evaluate the code as it is. So by

evaluating the following instruction: 'fn = function() { debugger; };'

we replaced the original function passed to the method using the 'fn'

argument by a new one, which does only one thing pauses when executed.

It's why the debugger paused in the evaluated code after we continued

execution using 'continue' command. So as you can see you have really

pretty much control over the debugged code. But remember that with great

power comes great responsibility, it's not really hard to break the

whole debugged application using such evaluation. OK, let's go out from

the evaluated code. Remember that you can display all local variables

using 'info locals' command, but head over to the 'help' description,

because it can be a quite tricky instruction and you probably will be

interested how to control the depth of displayed variables.



That's should be enough for now. With such a knowledge you should be

able to play with the debugger on your own using 'help' command.



    jrdb> s

    1

    jrdb> s

    example.js

    4     fn('this is dog.');

    jrdb>



Some interesting commands:



*set debug=true* - Enables debug mode. All sent and received packets

will be displayed in the console as well as log messages from the

client.



*animation* - If enabled, every time when client receives information

that debugger has paused, it displays bigger source context and

highlights the line where debugger is paused. For instance:



    jrdb> s

     0  debugger;

     1> print('Hello. ');

     2  (function(fn) {

     3      print('Yes, ');

     4      fn('this is dog.');

     5  })(function(msg) {

     6      print(msg);

     7  });

     8  print('Woof, woof.');

     9  debugger;

    10

    jrdb> s

     0  debugger;

     1  print('Hello. ');

     2> (function(fn) {

     3      print('Yes, ');

     4      fn('this is dog.');

     5  })(function(msg) {

     6      print(msg);

     7  });

     8  print('Woof, woof.');

     9  debugger;

    10

    jrdb>



*source* - Returns list of available script files.



    jrdb> source

    /home/tas/workspace_gnome/gjs/examples/gtk.js

    resource:///org/gnome/gjs/modules/overrides/GLib.js

    resource:///org/gnome/gjs/modules/lang.js



Protocol

--------



The whole protocol is based on full duplex TCP/IP communication. Almost

every command and response is encoded using JSON. So after implementing

transport layer everything you have to do to communicate with a debugger

is to send and receive JSON encoded objects. For instance the following

packets show how a few step commands look like on the protocol level:



    Sending command: {"id":1,"type":"command","name":"step"}

    Got packet: {"type":"info","subtype":"paused","url":"test_script.js","line":5,

    "source":"Utils.sum = function(x, y) {"}

    Sending command: {"id":2,"type":"command","name":"step"}

    Got packet: {"type":"info","subtype":"paused","url":"test_script.js","line":12,

    "source":"Manager.prototype = {"}

    Sending command: {"id":3,"type":"command","name":"step"}

    Got packet: {"type":"info","subtype":"paused","url":"test_script.js","line":13,

    "source":"    calculate: function( x ) {"}

    Sending command: {"id":4,"type":"command","name":"step"}

    Got packet: {"type":"info","subtype":"paused","url":"test_script.js","line":20,

    "source":"    show: function(x) {"}



    "source":"manager.calculate(5);"}



This chapter describes all available commands and responses, so after

reading it you should be able to implement a client application for the

debugger.



There are also two special commands, which are not encoded using JSON.

These are: get\_available\_contexts and exit.



### Request



Request is normalized and consists of following parts:



\*[context id]/(JSON PACKET)\n*



-   *context id* - Numerical identifier of the JSContext we would like

    to send packet to. It's optional parameter in case of non-existence

    the packet is sent to all the contexts.

-   *JSON PACKET* - Command itself, mandatory.

-   \*\n* - Commands are separated by new-line characters.



JSON packet consists of the following properties:



-   *type* - Currently it has to be set to 'command'.

-   *name* - Command name. For instance 'step'.

-   *id* - Optional packet ID. It's just sent back with a response and

    can be used to pair them.



The rest of properties are optional.



Examples:



~~~~ {.js}

{"type":"command","name":"step"}

{"type":"command","name":"set_breakpoint","breakpoint":{"url":"test.js",

"line":22}}

~~~~



### Response



Response if normalized and consists of the following parts:



-   *type* - Response type: 'error, 'info'. Info for plain responses,

    error for errors.

-   *subtype* - Name of the response.



The rest of the properties are optional.



Examples:



~~~~ {.js}

{"type":"info","subtype":"pc","script":"example.js","line":2,"source":null,

"id":"95D892FEC352D9AF"}

~~~~



### Supported commands



Standard parameters described above have been omitted intentionally.



    ----



    Name: pc

    Description: Gets current program counter.

    Request:

        name             - 'pc'

        source (boolean) - True if current source line (code, not a number)

                           should be returned in response.

    Response:

        subtype  - 'pc'

        script   - Script's URL.

        line     - Line number.

        source   - A line of source code pointed by PC.



    Req: {"type":"command","name":"pc","source":false,"id":"CE2DA6CB1B6AFC7A"}

    Res: {"type":"info","subtype":"pc","script":"example.js","line":2,"source":null,

         "id":"CE2DA6CB1B6AFC7A"}



    ----



    Name: step

    Description: Steps program until it reaches a different source line.

    Request:

        name  - 'step'

    Response: None.



    Req: {"type":"command","name":"step"}



    ----



    Name: next

    Description: Steps program proceeding through subroutines.

    Request:

        name  - 'next'

    Response: None.



    Req: {"type":"command","name":"next"}



    ----



    Name: continue

    Description: Continues execution.

    Request:

        name - 'continue'

    Response: None.



    Req: {"type":"command","name":"continue"}



    ----



    Name: stop

    Description: Terminates a debuggee.

    Request:

        name - 'stop'

    Response: None.



    Req: {"type":"command","name":"stop"}



    ----



    Name: source_code

    Description: Gets source code for given URL.

    Request:

        name  - 'get_source'

        url   - Script's URL.



    Response:

        subtype       - 'source_code'

        script        - Script's URL.

        source        - Source code.

        displacement  - Source code displacement, see debugger engine options.



    Example:

    Req: {"type":"command","name":"get_source","url":"example.js","id":

         "CCE548813F631269"}

    Res: {"type":"info","subtype":"source_code","script":"example.js","source":

         ["debugger;","..."],"displacement":0,"id":"DFF3E74BE6BF7DD7"}



    ----



    Name: delete_all_breakpoints

    Description: Deletes all registered breakpoints.

    Request:

        name - 'delete_all_breakpoints'



    Response:

        subtype - 'all_breakpoints_deleted'



    Example:

    Req: {"type":"command","name":"delete_all_breakpoints",

         "id":"6DE62B9327DDEFEA"}

    Res: {"type":"info","subtype":"all_breakpoints_deleted","id":"6DE62B9327DDEFEA"

         }



    ----



    Name: pause

    Description: Pauses debuggee as soon as possible.

    Request:

        name - 'pause'



    Response: None



    Example:

    Req: {"type":"command","name":"pause","id":"F37C8BF4BCBCEAE4"}



    ----



    Name: set_breakpoint

    Description: Registers a new breakpoint.

    Request:

        name - 'set_breakpoint'



    Response:

        subtype - 'breakpoint_set'

        bid - Numeric breakpoint identifier.

        url - Script file where breakpoint has been set.

        line - Line at which breakpoint has been set.

        pending - False if breakpoint has been already registered, true if it's a

                  pending breakpoint which waits for the script for being loaded.



    Example:

    Req: {"type":"command","name":"set_breakpoint","breakpoint":{

         "url":"/home/tas/workspace_gnome/gjs/examples/gtk.js","line":2,

         "pending":true}

    Res: {"type":"info","subtype":"breakpoint_set","bid":0,

         "url":"/home/tas/workspace_gnome/gjs/examples/gtk.js","line":2,

         "pending":false,"id":"46287654F429A626"}



    ----



    Name: delete_breakpoint

    Description: Deletes given breakpoint.

    Request:

        name - 'delete_breakpoint'

        ids - Array of numeric breakpoints identifiers to be deleted.



    Response:

        subtype - 'breakpoint_deleted'

        ids - Array of numeric breakpoints identifiers to be deleted.



    Example:

    Req: {"type":"command","name":"delete_breakpoint","ids":[1],

         "id":"9C59281AB28B5678"}

    Res: {"type":"info","subtype":"breakpoint_deleted","ids":[],

         "id":"9C59281AB28B5678"}



    ----



    Name: get_stacktrace

    Description: Gets current JSContext stacktrace.

    Request:

        name - 'get_stacktrace'



    Response:

        subtype - 'stacktrace'

        stacktrace - Array of stacktrace elements.

            url - Script's URL.

            line - Line number.

            rDepth - Stacktrace depth.



    Example:

    Req: {"type":"command","name":"get_stacktrace","id":"857B3B96591A5163"}

    Res: {"type":"info","subtype":"stacktrace","stacktrace":

         [{"url":"/home/tas/workspace_gnome/gjs/examples/gtk.js","line":96,

         "rDepth":0}],"id":"857B3B96591A5163"}



    ----



    Name: get_variables

    Description: Get list of variables from given frame.

    Request:

        name - 'get_variables'

        query - Query.

            depth - Frame depth.

            options - Retrieving options.

                show-hierarchy - Evaluates hierarchy of variables.

                evaluation-depth - How depth to evaluate.



    Response:

        subtype - 'variables'

        variables - Array of stack elements.

            stackElement - Describes variables for given frame.

                url - Script's URL.

                line - Source line.

                rDepth - Frame depth.

                variables - Array of variables.

                    name - Name of a variable.

                    value - Value of the variable.



    Response:

        subtype - 'stacktrace'

        stacktrace - Array of stacktrace elements.

            url - Script's URL.

            line - Line number.

            rDepth - Stacktrace depth.



    Example:

    Req: {"type":"command","name":"get_variables","query":{"depth":0,"options":{

         "show-hierarchy":true,"evaluation-depth":1}},"id":"63DFE5D533FD5EB4"}

    Res: {"type":"info","subtype":"variables","variables":[{

        "stackElement":{"url":"/home/tas/workspace_gnome/gjs/examples/gtk.js",

        "line":96,"rDepth":0},"variables":[{"name":"name","value":1}}]}],

        "id":"63DFE5D533FD5EB4"}



    ----



    Name: evaluate

    Description: Evaluates variable.

    Request:

        name - 'evaluate'

        path - Code to evaluate.

        options - Retrieving options.

            show-hierarchy - Evaluates hierarchy of variables.

            evaluation-depth - How depth to evaluate.



    Response:

        subtype - 'evaluated'

        result - Evaluation result.



    Example:

    Req: {"type":"command","name":"evaluate","path":"toString","options":

         {"show-hierarchy":true,"evaluation-depth":1},"id":"5791287CABE43BF6"}

    Res: {"type":"info","subtype":"evaluated","result":{

         "___jsrdbg_function_desc___":{"displayName":"toString","name":"toString",

         "parameterNames":[]},"length":0,"name":"toString","arguments":null,

         "caller":null},"id":"5791287CABE43BF6"}



    ----



    Name: get_all_source_urls

    Description: Get list of source scripts handled by a debugger.

    Request:

        name - 'get_all_source_urls'



    Response:

        subtype - 'all_source_urls'

        urls - Array of script URLs.



    Example:

    Req: {"type":"command","name":"get_all_source_urls","id":"AD9CD9D1C76D8EC4"}

    Res: {"type":"info","subtype":"all_source_urls","urls":

         ["/home/tas/workspace_gnome/gjs/examples/gtk.js","debugger eval code",

         "resource:///org/gnome/gjs/modules/overrides/GLib.js",

         "resource:///org/gnome/gjs/modules/lang.js"],"id":"AD9CD9D1C76D8EC4"}



    ----



    Name: get_breakpoints

    Description: Gets list of all registered breakpoints.

    Request:

        name - 'get_breakpoints'



    Response:

        subtype - 'breakpoints_list'

        breakpoints - Array of available breakpoints.

            bid - Numeric breakpoint identifier.

            url - Script file where breakpoint has been set.

            line - Line at which breakpoint has been set.

            pending (boolean) - False if breakpoint has been already registered,

                      true if it's a pending breakpoint which waits for the script

                      for being loaded.



    Example:

    Req: {"type":"command","name":"get_breakpoints","id":"3E5D8A1A168E11F5"}

    Res: {"type":"info","subtype":"breakpoints_list","breakpoints":[{"bid":0,

         "url":"/home/tas/workspace_gnome/gjs/examples/gtk.js","line":2,

         "pending":false}],"id":"3E5D8A1A168E11F5"}



    ----



    Name: get_available_contexts

    Description: Gets list of all handled JSContexts.

    Request: Plain string: get_available_contexts\n

    Response:

        subtype  - 'contexts_list'

        contexts - Array of contexts.

            contextId - Numerical context ID.

            contextName - Context name, the same which has to be passed to the

                          install method.

            paused (boolean ) - True if context is already paused.



    Res: {"type":"info","subtype":"contexts_list","contexts":[{"contextId":0,

         "contextName":"example-JS","paused":true}]}



    ----



    Name: exit

    Description: Closes debugger.

    Request: Plain string: exit\n



    Common packets:



    Packed sent every time when debugger switches to PAUSED state.



    {"type":"info","subtype":"paused",

    "url":"/home/tas/workspace_gnome/gjs/examples/gtk.js",

    "line":2,"source":"const Gtk = imports.gi.Gtk;"}



    source - Source code line.

    line - Line number.

    url - Script's URL.



    Packed sent every time when error occurred.

    {"type":"error","message":"Error message.","code":1,"id":"65855F75466DA4A6"}



    message - Textual error message.

    code - One of the supported error codes:



    ERROR_CODE_UNKNOWN_COMMAND       = 1

    ERROR_CODE_NO_COMMAND_NAME       = 2

    ERROR_CODE_NOT_A_COMMAND_PACKAGE = 3

    ERROR_CODE_NOT_PAUSED            = 4

    ERROR_CODE_BAD_ARGS              = 5

    ERROR_CODE_SCRIPT_NOT_FOUND      = 6

    ERROR_CODE_CANNOT_SET_BREAKPOINT = 8

    ERROR_CODE_IS_PAUSED             = 9

    ERROR_CODE_UNEXPECTED_EXC        = 10

    ERROR_CODE_EVALUATION_FAILED     = 11

    ERROR_CODE_PC_NOT_AVAILABLE      = 12

    ERROR_CODE_NO_ACTIVE_FRAME       = 13