Initial version of JerryScript debugger (#1557)

The debugger supports setting breakpoints, execution control (step, next, continue) and getting backtrace. The communication is WebSocket-based, so a browser can communicate with JerryScript without any intermediate application. JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com JerryScript-DCO-1.0-Signed-off-by: Levente Orban orbanl@inf.u-szeged.hu
2017-02-14 15:03:01 +01:00
parent 453066fcf1
commit 025a99ccbb
39 changed files with 4166 additions and 5 deletions
@@ -0,0 +1,72 @@
+## 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 not supported
+because 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`
+
+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 passing the `JERRY_INIT_DEBUGGER` flag
+to the `jerry_init ()` function which then 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.