diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index d8e0e8d09..bfdd98bd0 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -19,7 +19,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_INIT_DEBUGGER - deprecated, an unused placeholder now ## jerry_error_t @@ -329,7 +329,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. +- `JERRY_INIT_DEBUGGER` - deprecated, an unused placeholder now **Example** diff --git a/05.PORT-API.md b/05.PORT-API.md index 566cf3495..3164ddabd 100644 --- a/05.PORT-API.md +++ b/05.PORT-API.md @@ -58,10 +58,10 @@ typedef enum } jerry_log_level_t; /** - * Display or log a debug/error message. The function should implement a printf-like - * interface, where the first argument specifies the log level - * and the second argument specifies a format string on how to stringify the rest - * of the parameter list. + * Display or log a debug/error message, and sends it to the debugger client as well. + * The function should implement a printf-like interface, where the first argument + * specifies the log level and the second argument specifies a format string on how + * to stringify the rest of the parameter list. * * This function is only called with messages coming from the jerry engine as * the result of some abnormal operation or describing its internal operations diff --git a/07.DEBUGGER.md b/07.DEBUGGER.md index 4583e3140..9351b4f6e 100644 --- a/07.DEBUGGER.md +++ b/07.DEBUGGER.md @@ -36,9 +36,9 @@ can be used for transmitting debugger messages. 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 of engine initialization -(this feature available with the python client). The debugging -information (e.g. line index of each possible -breakpoint location) +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 @@ -75,8 +75,8 @@ All available commands of the client can be queried by the ## 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 +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 @@ -93,6 +93,36 @@ debugger is disabled. The following section describes the debugger functions available for the host application. +### jerry_debugger_init + +**Summary** + +Debugger server initialization. Must be called after `jerry_init`. + +**Prototype** + +```c +void +jerry_debugger_init (uint16_t port); +``` + +- `port` - Server port number + + +**Example** + +```c +{ + jerry_init (JERRY_INIT_EMPTY); + jerry_debugger_init (5001); + + // ... + + jerry_cleanup (); +} +``` + + ### jerry_debugger_is_connected **Summary** @@ -110,12 +140,15 @@ jerry_debugger_is_connected (void); ```c { - jerry_init (JERRY_INIT_DEBUGGER); + jerry_init (JERRY_INIT_EMPTY); + jerry_debugger_init (5001); if (jerry_debugger_is_connected ()) { printf ("A remote debugger client is connected."); } + + jerry_cleanup (); } ``` @@ -139,9 +172,12 @@ jerry_debugger_stop (void) ```c { - jerry_init (JERRY_INIT_DEBUGGER); + jerry_init (JERRY_INIT_EMPTY); + jerry_debugger_init (5001); jerry_debugger_stop (); + + jerry_cleanup (); } ``` @@ -170,9 +206,12 @@ jerry_debugger_continue (void) ```c { - jerry_init (JERRY_INIT_DEBUGGER); + jerry_init (JERRY_INIT_EMPTY); + jerry_debugger_init (5001); jerry_debugger_continue (); + + jerry_cleanup (); } ``` @@ -201,7 +240,8 @@ jerry_debugger_stop_at_breakpoint (bool enable_stop_at_breakpoint) ```c { - jerry_init (JERRY_INIT_DEBUGGER); + jerry_init (JERRY_INIT_EMPTY); + jerry_debugger_init (5001); jerry_debugger_stop_at_breakpoint (true); @@ -209,6 +249,8 @@ jerry_debugger_stop_at_breakpoint (bool enable_stop_at_breakpoint) jerry_eval (...); jerry_debugger_stop_at_breakpoint (false); + + jerry_cleanup (); } ``` @@ -216,8 +258,8 @@ jerry_debugger_stop_at_breakpoint (bool enable_stop_at_breakpoint) **Summary** -Stops the engine and puts that into a waiting loop. If the client send -a source code and the JerryScript receive that, then the function will +Stops the engine and puts it into a waiting loop. If the client sends +a source code and JerryScript receives that, then the function will run the source with the initialized options, after that the engine will wait for a new source until the client send a close signal. @@ -231,7 +273,8 @@ jerry_debugger_wait_and_run_client_source (jerry_value_t *return_value) **Example** ```c - jerry_init (JERRY_INIT_DEBUGGER); + jerry_init (JERRY_INIT_EMPTY); + jerry_debugger_init (5001); jerry_value_t run_result; jerry_debugger_wait_and_run_type_t receive_status; @@ -242,10 +285,40 @@ jerry_debugger_wait_and_run_client_source (jerry_value_t *return_value) if (receive_status == JERRY_DEBUGGER_SOURCE_RECEIVE_FAILED) { - // Handle the fail (e.g. create an error). + // Handle the failure (e.g. create an error). } + } jerry_release_value (run_result); } while (receive_status == JERRY_DEBUGGER_SOURCE_RECEIVED); + + jerry_cleanup (); +``` + +### jerry_debugger_send_output + +**Summary** + +Sends the program's output to the debugger client. + +**Prototype** + +```c + void + jerry_debugger_send_output (jerry_char_t buffer[], jerry_size_t string_size, uint8_t type) +``` + +**Example** + +```c + 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 (); ```