jerryscript/docs/07.DEBUGGER.md

JerryScript debugger interface

JerryScript provides a remote debugger which allows debugging JavaScript programs. The debugger has two main components: a server which is part of the JerryScript binary and a separate client application. Currently two debugger clients are available in the /jerry-debugger subdirectory: an HTML and a Python application. These simple applications demonstrate the communication protocol between the client and server and can be reused by integrated development environments.

Setting up the debugger server

The following arguments must be passed to tools/build.py:

--jerry-debugger=on --jerry-libc=off

At the moment only a Websocket-based implementation is provided by JerryScript which transmits messages over TCP/IP networks. This implementation requires a socket API which is not yet supported by jerry-libc so the standard libc is used instead. In the future any reliable stream or datagram based protocol can be used for transmitting debugger messages.

Debugging JavaScript applications

The debugger client must be connected to the server before the JavaScript application runs. On-the-fly attachment is supported for more than one file, right after the engine initialization (this feature is available with the python client). The debugging information (e.g. line index of each possible breakpoint location) is not preserved by JerryScript. The client is expected to be run on a system with much more resources and it should be capable of storing this information. JerryScript frees all debug information after it is transmitted to the client to save memory.

The following argument makes JerryScript wait for a client connection:

--start-debug-server

The following argument makes JerryScript wait for a client source code:

--debugger-wait-source

It is also recommended to increase the log level to see the Waiting for client connection message:

--log-level 2

The HTML client can connect to the IP address of the server with the connect command. The IP address can be localhost if the server and the client are running on the same machine.

After the connection is established the execution can be controlled by the debugger. The debugger always stops at the first possible breakpoint location. The effect is the same as using the stop command. This allows inserting breakpoints right before the meaningful part of the execution starts.

All available commands of the client can be queried by the help command.

Integrating debugger support into applications using JerryScript

The debugger can be enabled by calling the jerry_debugger_init (uint16_t port) function after the jerry_init () function. It initializes the debugger and blocks until a client connects.

When the debugger is enabled it is recommended to use jerry_parse_named_resource () instead of jerry_parse () because the resource name (usually a file name) is also passed to this function. This resource name is used by the client to identify the corresponding resource. In general it is always recommended to use jerry_parse_named_resource () when the resource name is available because it silently ignores the resource name if the debugger is disabled.

JerryScript debugger C-API interface

The following section describes the debugger functions available for the host application.

JerryScript debugger types

jerry_debugger_wait_for_source_callback_t

Summary

This callback function is called by jerry_debugger_wait_for_client_source when a source code is received successfully.

Prototype

typedef jerry_value_t
(*jerry_debugger_wait_for_source_callback_t) (const jerry_char_t *resource_name_p,
                                              size_t resource_name_size,
                                              const jerry_char_t *source_p,
                                              size_t source_size, void *user_p);

• resource_name_p - resource (usually a file) name of the source code
• resource_name_size - size of resource name
• source_p - source code character data
• source_size - size of source code
• user_p - custom pointer passed to jerry_debugger_wait_for_client_source

JerryScript debugger functions

jerry_debugger_init

Summary

Debugger server initialization. Must be called after jerry_init.

Prototype

void
jerry_debugger_init (uint16_t port);

• port - Server port number

Example

{
  jerry_init (JERRY_INIT_EMPTY);
  jerry_debugger_init (5001);

  // ...

  jerry_cleanup ();
}

jerry_debugger_is_connected

Summary

Returns true if a remote debugger client is connected.

Prototype

bool
jerry_debugger_is_connected (void);

Example

{
  jerry_init (JERRY_INIT_EMPTY);
  jerry_debugger_init (5001);

  if (jerry_debugger_is_connected ())
  {
    printf ("A remote debugger client is connected.");
  }

  jerry_cleanup ();
}

jerry_debugger_stop

Summary

Stops execution at the next available breakpoint if a remote debugger client is connected and the engine is not waiting at a breakpoint. The engine will stop regardless the breakpoint is enabled or not.

Prototype

void
jerry_debugger_stop (void)

Example

{
  jerry_init (JERRY_INIT_EMPTY);
  jerry_debugger_init (5001);

  jerry_debugger_stop ();

  jerry_cleanup ();
}

See also

• jerry_debugger_continue

jerry_debugger_continue

Summary

If the engine would stop at the next available breakpoint it cancels this effect. The engine will still stop at enabled breakpoints. This function effectively negates the effect of jerry_debugger_stop () calls or stop requests issued by the debugger client.

Prototype

void
jerry_debugger_continue (void)

Example

{
  jerry_init (JERRY_INIT_EMPTY);
  jerry_debugger_init (5001);

  jerry_debugger_continue ();

  jerry_cleanup ();
}

See also

• jerry_debugger_stop

jerry_debugger_disable_stop_at_breakpoint

Summary

Enables or disables stopping at breakpoints. When stopping is disabled all breakpoints are ignored including user enabled breakpoints. This allows hidden execution of ECMAScript code.

Prototype

void
jerry_debugger_stop_at_breakpoint (bool enable_stop_at_breakpoint)

• enable_stop_at_breakpoint - enable (=true) or disable (=false) stopping at breakpoints

Example

{
  jerry_init (JERRY_INIT_EMPTY);
  jerry_debugger_init (5001);

  jerry_debugger_stop_at_breakpoint (true);

  // Protected execution of JavaScript code.
  jerry_eval (...);

  jerry_debugger_stop_at_breakpoint (false);

  jerry_cleanup ();
}

jerry_debugger_wait_for_client_source

Summary

Asks the client to provide the next source code. The function waits until the whole source code is received. As a reply the the client may request a context reset or notify that no more source is available. These notifications are passed back as the return value of the function.

Prototype

jerry_debugger_wait_for_source_status_t
jerry_debugger_wait_for_client_source (jerry_debugger_wait_for_source_callback_t callback_p,
                                       void *user_p, jerry_value_t *return_value)

Example

/**
 * Runs the source code received by jerry_debugger_wait_for_client_source.
 */
static jerry_value_t
wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource name */
                          size_t resource_name_size, /**< size of resource name */
                          const jerry_char_t *source_p, /**< source code */
                          size_t source_size, /**< source code size */
                          void *user_p __attribute__((unused))) /**< user pointer */
{
  jerry_value_t ret_val = jerry_parse_named_resource (resource_name_p,
                                                      resource_name_size,
                                                      source_p,
                                                      source_size,
                                                      false);

  if (!jerry_value_has_error_flag (ret_val))
  {
    jerry_value_t func_val = ret_val;
    ret_val = jerry_run (func_val);
    jerry_release_value (func_val);
  }

  return ret_val;
} /* wait_for_source_callback */

int main ()
{
  do
  {
    /* Create a new JerryScript instance when a context reset is
     * received. Applications usually registers their core bindings
     * here as well (e.g. print, setTimeout). */
    jerry_init (JERRY_INIT_EMPTY);
    jerry_debugger_init (5001);

    do
    {
      jerry_value_t run_result;
      jerry_debugger_wait_for_source_status_t receive_status;

      receive_status = jerry_debugger_wait_for_client_source (wait_for_source_callback,
                                                              NULL,
                                                              &run_result);

      jerry_release_value (run_result);
    }
    while (receive_status == JERRY_DEBUGGER_SOURCE_RECEIVED);

    jerry_cleanup ();
  }
  while (receive_status == JERRY_DEBUGGER_CONTEXT_RESET_RECEIVED);

  if (receive_status == JERRY_DEBUGGER_SOURCE_RECEIVE_FAILED)
  {
    // Handle the failure (e.g. display an error).
  }
  return 0;
}

jerry_debugger_send_output

Summary

Sends the program's output to the debugger client.

Prototype

  void
  jerry_debugger_send_output (jerry_char_t buffer[], jerry_size_t string_size, uint8_t type)

Example

  jerry_init (JERRY_INIT_EMPTY);
  jerry_debugger_init (5001);

  jerry_char_t my_output = "Hey, this should be sent too!";
  jerry_size_t my_output_size = sizeof (my_output);

  jerry_debugger_send_output (my_output, my_output_size, JERRY_DEBUGGER_OUTPUT_OK);

  jerry_cleanup ();