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

docs/02.API-REFERENCE.md

@@ -9,6 +9,7 @@ Enum that contains the following elements:
  - JERRY_INIT_SHOW_REGEXP_OPCODES - dump regexp byte-code to log after compilation
  - JERRY_INIT_MEM_STATS - dump memory statistics
  - JERRY_INIT_MEM_STATS_SEPARATE - dump memory statistics and reset peak values after parse
+ - JERRY_INIT_DEBUGGER - enable all features required by debugging
 
 ## jerry_error_t
 
@@ -211,6 +212,7 @@ jerry_init (jerry_init_flag_t flags)
 - `JERRY_INIT_SHOW_REGEXP_OPCODES` - print compiled regexp byte-code.
 - `JERRY_INIT_MEM_STATS` - dump memory statistics.
 - `JERRY_INIT_MEM_STATS_SEPARATE` - dump memory statistics and reset peak values after parse.
+- `JERRY_INIT_DEBUGGER` - enable all features required by debugging.
 
 **Example**
 
@@ -451,6 +453,40 @@ jerry_parse (const jerry_char_t *source_p,
 
 - [jerry_run](#jerry_run)
 
+## jerry_parse_named_resource
+
+**Summary**
+
+Parse script and construct an ECMAScript function. The lexical
+environment is set to the global lexical environment. The name
+(usually a file name) is also passed to this function which is
+used by the debugger to find the source code.
+
+*Note*: The returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_parse_named_resource (const jerry_char_t *name_p, /**< name (usually a file name) */
+                            size_t name_length, /**< length of name */
+                            const jerry_char_t *source_p, /**< script source */
+                            size_t source_size, /**< script source size */
+                            bool is_strict) /**< strict mode */
+{
+```
+
+- `name_p` - name, usually a file name
+- `name_length` - size of the file name, in bytes
+- `source_p` - string, containing source code to parse. It must be a valid UTF8 string
+- `source_size` - size of the string, in bytes
+- `is_strict` - defines strict mode
+- return value
+  - function object value, if script was parsed successfully,
+  - thrown error, otherwise
+
+This function is identical to [jerry_parse](#jerry_parse), except that an additional filename parameter has been added.
 
 ## jerry_run
 

docs/07.DEBUGGER.md

@@ -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.