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

.travis.yml

@@ -6,6 +6,7 @@ sudo: required
 
 env:
   - OPTS="--check-signed-off-travis --check-cppcheck --check-doxygen --check-vera --check-license"
+  - OPTS="--jerry-debugger"
   - OPTS="--jerry-tests --jerry-test-suite"
   - OPTS="--jerry-tests --jerry-test-suite --toolchain=cmake/toolchain_linux_armv7l.cmake" TIMEOUT=300 INSTALL_QEMU_ARM=yes
   - OPTS="--buildoption-test"

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.

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 JerryScript debugger?")
 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)
@@ -185,6 +198,10 @@ else()
   MESSAGE(FATAL_ERROR "Profile file: '${FEATURE_PROFILE}' doesn't exist!")
 endif()
 
+if(JERRY_LIBC AND FEATURE_DEBUGGER)
+  MESSAGE(FATAL_ERROR "This configuration is not supported. Please build against your system libc to enable the JerryScript debugger.")
+endif()
+
 # RegExp byte-code dumps
 if(FEATURE_REGEXP_DUMP)
   set(DEFINES_JERRY ${DEFINES_JERRY} REGEXP_DUMP_BYTE_CODE)