Initial version of JerryScript debugger

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 [email protected]
JerryScript-DCO-1.0-Signed-off-by: Levente Orban [email protected]

Author: Levente Orban

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*: 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, /**<  */
+                            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 the same as [jerry_parse](#jerry_parse), except a filename parameter is added.
 
 ## jerry_run
 

docs/07.DEBUGGER.md

@@ -0,0 +1,52 @@
+## 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 has not been
+supported by jerry-libc yet 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 to reduce
+memory consumption. The client is expected to be run on a system
+with much more resources and it should be capable of storing
+this information instead of JerryScript. Hence debug information
+is discarded after it is transmitted to the client.
+
+The following argument makes JerryScript to 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 the IP address of the server by
+the `connect IP-address` command. The IP address can be
+localhost if the server and client run on the same machine.
+
+After the connection is established breakpoints can be inserted
+and the execution can be controlled by the debugger. All available
+commands can be queried by `help`.

jerry-core/CMakeLists.txt

@@ -18,6 +18,7 @@ project (${JERRY_CORE_NAME} C)
 
 # Optional features
 set(FEATURE_CPOINTER_32_BIT  OFF     CACHE BOOL   "Enable 32 bit compressed pointers?")
+set(FEATURE_DEBUGGER         OFF     CACHE BOOL   "Enable debugger option for JerryScript?")
 set(FEATURE_ERROR_MESSAGES   OFF     CACHE BOOL   "Enable error messages?")
 set(FEATURE_JS_PARSER        ON      CACHE BOOL   "Enable js-parser?")
 set(FEATURE_MEM_STATS        OFF     CACHE BOOL   "Enable memory statistics?")
@@ -38,6 +39,7 @@ endif()
 
 # Status messages
 message(STATUS "FEATURE_CPOINTER_32_BIT   " ${FEATURE_CPOINTER_32_BIT})
+message(STATUS "FEATURE_DEBUGGER          " ${FEATURE_DEBUGGER})
 message(STATUS "FEATURE_ERROR_MESSAGES    " ${FEATURE_ERROR_MESSAGES})
 message(STATUS "FEATURE_JS_PARSER         " ${FEATURE_JS_PARSER})
 message(STATUS "FEATURE_MEM_STATS         " ${FEATURE_MEM_STATS})
@@ -55,6 +57,7 @@ message(STATUS "MEM_HEAP_SIZE_KB          " ${MEM_HEAP_SIZE_KB})
 # Include directories
 set(INCLUDE_CORE
     "${CMAKE_CURRENT_SOURCE_DIR}"
+    "${CMAKE_CURRENT_SOURCE_DIR}/debugger"
     "${CMAKE_CURRENT_SOURCE_DIR}/ecma/base"
     "${CMAKE_CURRENT_SOURCE_DIR}/ecma/builtin-objects"
     "${CMAKE_CURRENT_SOURCE_DIR}/ecma/builtin-objects/typedarray"
@@ -70,6 +73,7 @@ set(INCLUDE_CORE
 # Sources
 # Jerry core
 file(GLOB SOURCE_CORE_API                       *.c)
+file(GLOB SOURCE_CORE_DEBUGGER                  debugger/*.c)
 file(GLOB SOURCE_CORE_ECMA_BASE                 ecma/base/*.c)
 file(GLOB SOURCE_CORE_ECMA_BUILTINS             ecma/builtin-objects/*.c)
 file(GLOB SOURCE_CORE_ECMA_BUILTINS_TYPEDARRAY  ecma/builtin-objects/typedarray/*.c)
@@ -96,6 +100,10 @@ set(SOURCE_CORE_FILES
     ${SOURCE_CORE_PARSER_REGEXP}
     ${SOURCE_CORE_VM})
 
+if(FEATURE_DEBUGGER)
+  set(SOURCE_CORE_FILES ${SOURCE_CORE_FILES} ${SOURCE_CORE_DEBUGGER})
+endif()
+
 # Jerry port
 file(GLOB SOURCE_PORT_FILES "${PORT_DIR}/*.c")
 
@@ -162,6 +170,11 @@ if(FEATURE_MEM_STATS)
   set(DEFINES_JERRY ${DEFINES_JERRY} JMEM_STATS)
 endif()
 
+# Enable debugger
+if(FEATURE_DEBUGGER)
+  set(DEFINES_JERRY ${DEFINES_JERRY} JERRY_DEBUGGER)
+endif()
+
 # Memory management stress-test mode
 if(FEATURE_MEM_STRESS_TEST)
   set(DEFINES_JERRY ${DEFINES_JERRY} JMEM_GC_BEFORE_EACH_ALLOC)