archive-gh-me/jerryscript
1
0
Fork 0
mirror of https://github.com/jerryscript-project/jerryscript.git synced 2025-12-15 16:29:21 +00:00
Code Issues Projects Releases Wiki Activity

Update the webpage (#2499)

Browse Source 
JerryScript-DCO-1.0-Signed-off-by: László Langó llango.u-szeged@partner.samsung.com
This commit is contained in:
László Langó 2018-08-31 12:02:17 +02:00 committed by Akos Kiss
parent 2ce27a189a
commit cf87970ef6
8 changed files with 722 additions and 314 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
01.GETTING-STARTED.md
View File

@ -63,20 +63,20 @@ python tools/build.py --profile=es5.1|es2015-subset|minimal
See also the related [README.md](https://github.com/jerryscript-project/jerryscript/blob/master/jerry-core/profiles/README.md).
**Use (jerry, compiler-default, external) libc**
**Use (compiler-default, external) libc**
The default libc is jerry-libc, but you can use compiler-default libc or an external libc:
The default libc is the compiler-default libc but you can use an external libc as well:
- compiler-default libc:
```bash
python tools/build.py --jerry-libc=off
python tools/build.py
```
- external libc:
```bash
python tools/build.py --jerry-libc=off --compile-flag="-nostdlib -I/path/to/ext-libc/include" --link-lib="ext-c"
python tools/build.py --compile-flag="-nostdlib -I/path/to/ext-libc/include" --link-lib="ext-c"
```
**Add toolchain file**
@ -96,7 +96,7 @@ python tools/build.py --toolchain=cmake/toolchain_linux_armv7l.cmake
**Use system memory allocator**
```bash
python tools/build.py --system-allocator=on --jerry-libc=off
python tools/build.py --system-allocator=on
```
*Note*: System allocator is only supported on 32 bit systems.

551
02.API-REFERENCE.md
View File

@ -23,16 +23,17 @@ Enum that contains the following elements:
## jerry_type_t
Enum that contains a set of elements to represent JavaScript type:
Enum that contains JerryScript API value types:
- JERRY_TYPE_NONE - no type information
- JERRY_TYPE_UNDEFINED - undefined value
- JERRY_TYPE_NULL - null value
- JERRY_TYPE_BOOLEAN - boolean value
- JERRY_TYPE_NUMBER - number value
- JERRY_TYPE_STRING - string value
- JERRY_TYPE_OBJECT - object value
- JERRY_TYPE_FUNCTION - function value
- JERRY_TYPE_UNDEFINED - undefined type
- JERRY_TYPE_NULL - null type
- JERRY_TYPE_BOOLEAN - boolean type
- JERRY_TYPE_NUMBER - number type
- JERRY_TYPE_STRING - string type
- JERRY_TYPE_OBJECT - object type
- JERRY_TYPE_FUNCTION - function type
- JERRY_TYPE_ERROR - error/abort type
## jerry_error_t
@ -69,6 +70,7 @@ Possible compile time enabled feature types:
- JERRY_FEATURE_DATE - Date support
- JERRY_FEATURE_REGEXP - RegExp support
- JERRY_FEATURE_LINE_INFO - line info available
- JERRY_FEATURE_LOGGING - logging
## jerry_parse_opts_t
@ -78,6 +80,18 @@ Option bits for [jerry_parse](#jerry_parse) and
- JERRY_PARSE_NO_OPTS - no options passed
- JERRY_PARSE_STRICT_MODE - enable strict mode
## jerry_gc_mode_t
Set garbage collection operational mode
- JERRY_GC_SEVERITY_LOW - free unused objects
- JERRY_GC_SEVERITY_HIGH - free as much memory as possible
The difference between `JERRY_GC_SEVERITY_LOW` and `JERRY_GC_SEVERITY_HIGH`
is that the former keeps memory allocated for performance improvements such
as property hash tables for large objects. The latter frees all possible
memory blocks but the performance may drop after the garbage collection.
## jerry_generate_snapshot_opts_t
Flags for [jerry_generate_snapshot](#jerry_generate_snapshot) and
@ -139,18 +153,6 @@ Jerry's char value
typedef uint8_t jerry_char_t;
```
## jerry_char_ptr_t
**Summary**
Pointer to an array of character values
**Prototype**
```c
typedef jerry_char_t *jerry_char_ptr_t;
```
## jerry_size_t
**Summary**
@ -246,6 +248,34 @@ typedef struct
} jerry_context_data_manager_t;
```
## jerry_instance_alloc_t
**Summary**
Function type for allocating buffer for JerryScript instance.
**Prototype**
```c
typedef void *(*jerry_instance_alloc_t) (size_t size, void *cb_data_p);
```
- `size` - allocation size
- `cb_data_p` - pointer to user data
## jerry_instance_t
**Summary**
An opaque declaration of the JerryScript instance structure which is the header of the context space.
**Prototype**
```c
typedef struct jerry_instance_t jerry_instance_t;
```
## jerry_property_descriptor_t
**Summary**
@ -330,20 +360,6 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_
const jerry_length_t args_count);
```
## jerry_object_free_callback_t
**Summary**
**Deprecated: Please use jerry_object_native_free_callback_t instead.**
Native free callback of an object.
**Prototype**
```c
typedef void (*jerry_object_free_callback_t) (const uintptr_t native_p);
```
## jerry_object_native_free_callback_t
**Summary**
@ -360,7 +376,7 @@ typedef void (*jerry_object_native_free_callback_t) (void *native_p);
**Summary**
The type infomation of the native pointer.
The type information of the native pointer.
It includes the free callback that will be called when associated JavaScript object is garbage collected. It can be left NULL in case it is not needed.
Typically, one would create a `static const jerry_object_native_info_t` for
@ -628,7 +644,7 @@ Registers an external magic string array.
```c
void
jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p,
jerry_register_magic_strings (const jerry_char_t **ex_str_items_p,
uint32_t count,
const jerry_length_t *str_lengths_p);
```
@ -651,12 +667,12 @@ main (void)
// must be static, because 'jerry_register_magic_strings' does not copy
// the items must be sorted by size at first, then lexicographically
static const jerry_char_ptr_t magic_string_items[] = {
(const jerry_char_ptr_t) "magicstring1",
(const jerry_char_ptr_t) "magicstring2",
(const jerry_char_ptr_t) "magicstring3"
};
uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t));
static const jerry_char_t *magic_string_items[] = {
(const jerry_char_t *) "magicstring1",
(const jerry_char_t *) "magicstring2",
(const jerry_char_t *) "magicstring3"
};
uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_t *));
// must be static, because 'jerry_register_magic_strings' does not copy
static const jerry_length_t magic_string_lengths[] = {
@ -715,13 +731,30 @@ Performs garbage collection.
```c
void
jerry_gc (void);
jerry_gc (jerry_gc_mode_t mode);
```
- `mode` - operational mode, see [jerry_gc_mode_t](#jerry_gc_mode_t)
**Example**
[doctest]: # ()
```c
jerry_gc ();
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t object_value = jerry_create_object ();
jerry_release_value (object_value);
jerry_gc (JERRY_GC_SEVERITY_LOW);
jerry_cleanup ();
}
```
**See also**
@ -950,12 +983,12 @@ Perform JavaScript `eval`.
jerry_value_t
jerry_eval (const jerry_char_t *source_p,
size_t source_size,
bool is_strict);
uint32_t parse_opts);
```
- `source_p` - source code to evaluate, it must be a valid utf8 string.
- `source_size` - length of the source code
- `is_strict` - perform `eval` as it is called from "strict mode" code.
- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags.
- return value - result of eval, may be error value.
**Example**
@ -964,7 +997,7 @@ jerry_eval (const jerry_char_t *source_p,
{
jerry_value_t ret_val = jerry_eval (str_to_eval,
strlen (str_to_eval),
false);
JERRY_PARSE_NO_OPTS);
}
```
@ -1611,7 +1644,7 @@ jerry_value_is_undefined (const jerry_value_t value)
Returns the JavaScript type
for a given value as a [jerry_type_t](#jerry_type_t) enum value.
This is a similar operation as the 'typeof' operator
This is a similar operation to the 'typeof' operator
in the standard with an exception that the 'null'
value has its own enum value.
@ -1677,6 +1710,125 @@ jerry_is_feature_enabled (const jerry_feature_t feature);
# Error manipulation functions
## jerry_create_abort_from_value
**Summary**
Create (api) abort from a value.
This function creates an API abort value from an API value. The second argument defines
whether the input value must be released or not. If it is set to `true`,
then a [`jerry_release_value`](#jerry_release_value) function will be called
for the first argument, so the api value won't be available after the call of
`jerry_create_abort_from_value`. The second argument should be false if both value
and created abort value are needed.
**Prototype**
```c
jerry_value_t
jerry_create_abort_from_value (jerry_value_t value, bool release);
```
- `value` - api value
- `release` - raw boolean, defines whether input value must be released
- return value - abort (api) value
**Example 1**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t abort = jerry_create_abort_from_value (value, true);
// using the 'value' variable after release is invalid.
jerry_release_value (abort);
}
```
**Example 2**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t abort = jerry_create_abort_from_value (value, false);
// both 'abort' and 'value' can be used and must be released when they are no longer needed
jerry_release_value (abort);
jerry_release_value (value);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_create_error_from_value](#jerry_create_error_from_value)
## jerry_create_error_from_value
**Summary**
Create (api) error from a value.
This function creates an API error value from an API value. The second argument defines
whether the input value must be released or not. If it is set to `true`,
then a [`jerry_release_value`](#jerry_release_value) function will be called
for the first argument, so the api value won't be available after the call of
`jerry_create_error_from_value`. The second argument should be false if both value
and created error value are needed.
**Prototype**
```c
jerry_value_t
jerry_create_error_from_value (jerry_value_t value, bool release);
```
- `value` - api value
- `release` - raw boolean, defines whether input value must be released
- return value - error (api) value
**Example 1**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t error = jerry_create_error_from_value (value, true);
// using the 'value' variable after release is invalid.
jerry_release_value (error);
}
```
**Example 2**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t error = jerry_create_error_from_value (value, false);
// both 'error' and 'value' can be used and must be released when they are no longer needed
jerry_release_value (error);
jerry_release_value (value);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_create_abort_from_value](#jerry_create_abort_from_value
## jerry_get_error_type
**Summary**
@ -1732,7 +1884,7 @@ whether the input error value must be released or not. If it is set to `true`,
then a [`jerry_release_value`](#jerry_release_value) function will be called
for the first argument, so the error value won't be available after the call of
`jerry_get_value_from_error`. The second argument should be false if both error
and its represented value are needed. The first argument is returned unchanged if it is not an error.
and its represented value are needed.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
@ -1752,14 +1904,14 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
```c
{
jerry_value_t error;
jerry_value_t value;
... // create or acquire value
jerry_value_set_error_flag (&error);
jerry_value_t value = jerry_get_value_from_error (error, true);
jerry_value_t error = jerry_create_error_from_value (value, true);
jerry_value_t value_from_error = jerry_get_value_from_error (error, true);
// using the 'error' variable after release is invalid.
jerry_release_value (value);
jerry_release_value (value_from_error);
}
```
@ -1767,14 +1919,14 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
```c
{
jerry_value_t error;
jerry_value_t value;
... // create or acquire value
jerry_value_set_error_flag (&error);
jerry_value_t value = jerry_get_value_from_error (error, false);
// both 'error' and 'value' can be used and must be released when they are no longer needed
jerry_value_t error = jerry_create_error_from_value (value, true);
jerry_value_t value_from_error = jerry_get_value_from_error (error, false);
// both 'error' and 'value_from_error' can be used and must be released when they are no longer needed
jerry_release_value (value);
jerry_release_value (value_from_error);
jerry_release_value (error);
}
```
@ -1782,78 +1934,8 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_value_set_error_flag](#jerry_value_set_error_flag)
- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
## jerry_value_set_error_flag
**Summary**
Set the error flag.
**Prototype**
```c
void
jerry_value_set_error_flag (jerry_value_t *value_p);
```
- `value_p` - pointer to an api value
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_set_error_flag (&value);
jerry_release_value (value);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
## jerry_value_set_abort_flag
**Summary**
Set both the error and abort flags.
**Prototype**
```c
void
jerry_value_set_abort_flag (jerry_value_t *value_p);
```
- `value_p` - pointer to an api value
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_set_abort_flag (&value);
jerry_release_value (value);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_value_set_error_flag](#jerry_value_set_error_flag)
- [jerry_create_error_from_value](#jerry_create_error_from_value)
- [jerry_create_abort_from_value](#jerry_create_abort_from_value)
# Getter functions of 'jerry_value_t'
@ -2890,7 +2972,7 @@ jerry_create_error (jerry_error_t error_type,
- [jerry_value_is_error](#jerry_value_is_error)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_value_set_error_flag](#jerry_value_set_error_flag)
- [jerry_create_error_from_value](#jerry_create_error_from_value)
## jerry_create_error_sz
@ -4317,106 +4399,6 @@ jerry_set_prototype (const jerry_value_t obj_val,
- [jerry_get_prototype](#jerry_get_prototype)
## jerry_get_object_native_handle
**Summary**
**Deprecated: Please use jerry_get_object_native_pointer instead.**
Get native handle, previously associated with specified object.
**Prototype**
```c
bool
jerry_get_object_native_handle (const jerry_value_t obj_val,
uintptr_t *out_handle_p);
```
- `obj_val` - object value
- `out_handle_p` - handle value (output parameter).
- return value
- true, if there is handle associated with the object
- false, otherwise
**Example**
```c
{
jerry_value_t object;
uintptr_t handle_set;
... // receive or construct object and handle_set value
jerry_set_object_native_handle (object, handle_set, NULL);
...
uintptr_t handle_get;
bool is_there_associated_handle = jerry_get_object_native_handle (object, &handle_get);
}
```
**See also**
- [jerry_create_object](#jerry_create_object)
- [jerry_set_object_native_handle](#jerry_set_object_native_handle)
- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
## jerry_set_object_native_handle
**Summary**
**Deprecated: Please use jerry_set_object_native_pointer instead.**
Set native handle and an optional free callback for the specified object.
*Note*: If native handle was already set for the object, its value is updated.
*Note*: If a non-NULL free callback is specified, it will be called
by the garbage collector when the object is freed. The free
callback always overwrites the previous value, so passing
a NULL value deletes the current free callback.
**Prototype**
```c
void
jerry_set_object_native_handle (const jerry_value_t obj_val,
uintptr_t handle_p,
jerry_object_free_callback_t freecb_p);
```
- `obj_val` - object value to set handle in
- `handle_p` - handle value
- `freecb_p` - pointer to "free" callback or NULL
**Example**
```c
{
jerry_value_t object;
uintptr_t handle_set;
... // receive or construct object and handle_set value
jerry_set_object_native_handle (object, handle_set, NULL);
...
uintptr_t handle_get;
bool is_there_associated_handle = jerry_get_object_native_handle (object, &handle_get);
}
```
**See also**
- [jerry_create_object](#jerry_create_object)
- [jerry_get_object_native_handle](#jerry_get_object_native_handle)
- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
## jerry_get_object_native_pointer
**Summary**
@ -4437,7 +4419,7 @@ The pointer and the type information are previously associated with the object b
and dereferencing `out_native_pointer_p`.
*Note*: `out_native_pointer_p` and `out_native_info_p` can be NULL, and it means the
caller doesn't want to get the native_pointer or type infomation.
caller doesn't want to get the native_pointer or type information.
**Prototype**
@ -4450,7 +4432,7 @@ jerry_get_object_native_pointer (const jerry_value_t obj_val,
- `obj_val` - object value to get native pointer from.
- `out_native_pointer_p` - native pointer (output parameter).
- `out_native_info_p` - native pointer's type infomation (output parameter).
- `out_native_info_p` - native pointer's type information (output parameter).
- return value
- true, if there is native pointer associated with the object
- false, otherwise
@ -4547,7 +4529,7 @@ jerry_set_object_native_pointer (const jerry_value_t obj_val,
- `obj_val` - object to set native pointer in.
- `native_p` - native pointer.
- `info_p` - native pointer's type infomation or NULL. When used, this should
- `info_p` - native pointer's type information or NULL. When used, this should
be a long-lived pointer, usually a pointer to a
`static const jerry_object_native_info_t` makes most sense.
@ -4705,7 +4687,7 @@ bool jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *nat
void *user_data_p);
```
- `native_info_p` - native pointer's type infomation.
- `native_info_p` - native pointer's type information.
- return value
- `true`, if the search function terminated the traversal by returning `false`
- `false`, if the end of the list of objects was reached
@ -4903,6 +4885,105 @@ main (void)
- [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer)
# External context functions
## jerry_create_instance
**Summary**
Creates a JerryScript instance for external context.
**Prototype**
```c
jerry_instance_t *
jerry_create_instance (uint32_t heap_size,
jerry_instance_alloc_t alloc,
void *cb_data_p);
```
- `heap_size` - requested heap size of the JerryScript instance
- `alloc` - function for allocation
- `cb_data_p` - user data
- return value
- pointer to the newly created JerryScript instance if success
- NULL otherwise.
**Example**
[doctest]: # (test="compile")
```c
#include <stdlib.h>
#include <pthread.h>
#include "jerryscript.h"
#include "jerryscript-port.h"
/* A different Thread Local Storage variable for each jerry instance. */
__thread jerry_instance_t *tls_instance;
jerry_instance_t *
jerry_port_get_current_instance (void)
{
/* Returns the instance assigned to the thread. */
return tls_instance;
}
/* Allocate JerryScript heap for each thread. */
static void *
instance_alloc_fn (size_t size, void *cb_data)
{
(void) cb_data;
return malloc (size);
}
static void *
thread_function (void *param)
{
tls_instance = jerry_create_instance (512 * 1024,
instance_alloc_fn,
NULL);
jerry_init (JERRY_INIT_EMPTY);
/* Run the JerryScript instance (e.g.: jerry_parse & jerry_run) */
jerry_cleanup ();
/* Deallocate JerryScript instance */
free (tls_instance);
return NULL;
}
#define NUM_OF_THREADS 8
int
main (void)
{
pthread_t threads[NUM_OF_THREADS];
/* Create the threads. */
for (int i = 0; i < NUM_OF_THREADS; i++)
{
pthread_create (&threads[i], NULL, thread_function, (void *) (intptr_t) i);
}
/* Wait for the threads to complete, and release their resources. */
for (int i = 0; i < NUM_OF_THREADS; i++)
{
pthread_join (threads[i], NULL);
}
return 0;
}
```
**See also**
- [jerry_instance_t](#jerry_instance_t)
- [jerry_instance_alloc_t](#jerry_instance_alloc_t)
- [jerry_port_get_current_instance](05.PORT-API.md#jerry_port_get_current_instance)
# Snapshot functions
## jerry_generate_snapshot

16
03.API-EXAMPLE.md
View File

@ -115,7 +115,7 @@ main (void)
/* Evaluate script1 */
eval_ret = jerry_eval (script_1,
strlen ((const char *) script_1),
false);
JERRY_PARSE_NO_OPTS);
/* Free JavaScript value, returned by eval */
jerry_release_value (eval_ret);
@ -123,7 +123,7 @@ main (void)
/* Evaluate script2 */
eval_ret = jerry_eval (script_2,
strlen ((const char *) script_2),
false);
JERRY_PARSE_NO_OPTS);
/* Free JavaScript value, returned by eval */
jerry_release_value (eval_ret);
@ -179,7 +179,7 @@ main (void)
/* Now starting script that would output value of just initialized field */
jerry_value_t eval_ret = jerry_eval (script,
strlen ((const char *) script),
false);
JERRY_PARSE_NO_OPTS);
/* Free JavaScript value, returned by eval */
jerry_release_value (eval_ret);
@ -332,7 +332,7 @@ main (void)
/* Evaluate entered command */
ret_val = jerry_eval ((const jerry_char_t *) cmd,
len,
false);
JERRY_PARSE_NO_OPTS);
/* If command evaluated successfully, print value, returned by eval */
if (jerry_value_is_error (ret_val))
@ -430,7 +430,7 @@ main (void)
size_t script_size = strlen ((const char *) script);
/* Evaluate script */
jerry_value_t eval_ret = jerry_eval (script, script_size, false);
jerry_value_t eval_ret = jerry_eval (script, script_size, JERRY_PARSE_NO_OPTS);
/* Free JavaScript value, returned by eval */
jerry_release_value (eval_ret);
@ -519,7 +519,7 @@ main (void)
/* Evaluate script */
my_js_obj_val = jerry_eval (my_js_object,
strlen ((const char *) my_js_object),
false);
JERRY_PARSE_NO_OPTS);
/* Create a JS function object and wrap into a jerry value */
jerry_value_t add_func_obj = jerry_create_external_function (add_handler);
@ -542,7 +542,7 @@ main (void)
size_t script_size = strlen ((const char *) script);
/* Evaluate script */
jerry_value_t eval_ret = jerry_eval (script, script_size, false);
jerry_value_t eval_ret = jerry_eval (script, script_size, JERRY_PARSE_NO_OPTS);
/* Free JavaScript value, returned by eval */
jerry_release_value (eval_ret);
@ -593,7 +593,7 @@ main (void)
jerryx_handler_print);
/* Evaluate the script */
jerry_value_t eval_ret = jerry_eval (script, script_size, false);
jerry_value_t eval_ret = jerry_eval (script, script_size, JERRY_PARSE_NO_OPTS);
/* Free the JavaScript value returned by eval */
jerry_release_value (eval_ret);

5
05.PORT-API.md
View File

@ -73,6 +73,11 @@ typedef enum
*
* Example: a libc-based port may implement this with vfprintf(stderr) or
* vfprintf(logfile), or both, depending on log level.
*
* Note:
* This port function is called by jerry-core when JERRY_ENABLE_LOGGING is
* defined. It is also common practice though to use this function in
* application code.
*/
void jerry_port_log (jerry_log_level_t level, const char *fmt, ...);
```

190
07.DEBUGGER.md
View File

@ -13,24 +13,23 @@ permalink: /debugger/
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.
separate client application. Currently a Python-based debugger
client is available in the /jerry-debugger subdirectory.
This simple application demonstrates 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`
`--jerry-debugger=on`
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.
The transport layer of the communication protocol is pluggable.
At the moment, a WebSocket-based implementation is provided as a
JerryScript extension, which transmits messages over TCP/IP networks.
If necessary/implemented, any reliable stream or datagram based
protocol can be used for transmitting debugger messages.
## Debugging JavaScript applications
@ -59,8 +58,8 @@ 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
The Python client can connect to the server by specifying its
IP address on the command line. The 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
@ -75,9 +74,12 @@ All available commands of the client can be queried by the
## Integrating debugger support into applications using JerryScript
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 using the extension-provided WebSocket transport layer, the
debugger can be enabled by calling `jerryx_debugger_after_connect
(jerryx_debugger_tcp_create (debug_port) && jerryx_debugger_ws_create ())`
after the `jerry_init ()` function. It initializes the debugger and
blocks until a client connects. (Custom transport layers may be
implemented and initialized similarly.)
The resource name provided to `jerry_parse ()` is used by the client
to identify the resource name of the source code. This resource name
@ -86,7 +88,7 @@ is usually a file name.
## JerryScript debugger C-API interface
The following section describes the debugger functions
available for the host application.
available to the host application.
## JerryScript debugger types
@ -117,36 +119,6 @@ typedef jerry_value_t
## JerryScript debugger functions
### 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**
@ -162,10 +134,18 @@ jerry_debugger_is_connected (void);
**Example**
[doctest]: # (test="link")
```c
#include "jerryscript.h"
#include "jerryscript-ext/debugger.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_debugger_init (5001);
jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
&& jerryx_debugger_ws_create ());
if (jerry_debugger_is_connected ())
{
@ -194,10 +174,18 @@ jerry_debugger_stop (void)
**Example**
[doctest]: # (test="link")
```c
#include "jerryscript.h"
#include "jerryscript-ext/debugger.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_debugger_init (5001);
jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
&& jerryx_debugger_ws_create ());
jerry_debugger_stop ();
@ -228,10 +216,18 @@ jerry_debugger_continue (void)
**Example**
[doctest]: # (test="link")
```c
#include "jerryscript.h"
#include "jerryscript-ext/debugger.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_debugger_init (5001);
jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
&& jerryx_debugger_ws_create ());
jerry_debugger_continue ();
@ -243,7 +239,7 @@ jerry_debugger_continue (void)
- [jerry_debugger_stop](#jerry_debugger_stop)
### jerry_debugger_disable_stop_at_breakpoint
### jerry_debugger_stop_at_breakpoint
**Summary**
@ -262,15 +258,26 @@ jerry_debugger_stop_at_breakpoint (bool enable_stop_at_breakpoint)
**Example**
[doctest]: # (test="link")
```c
#include <string.h>
#include "jerryscript.h"
#include "jerryscript-ext/debugger.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_debugger_init (5001);
jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
&& jerryx_debugger_ws_create ());
jerry_debugger_stop_at_breakpoint (true);
// Protected execution of JavaScript code.
jerry_eval (...);
const jerry_char_t script[] = "42";
size_t script_size = strlen ((const char *) script);
jerry_eval (script, script_size, JERRY_PARSE_NO_OPTS);
jerry_debugger_stop_at_breakpoint (false);
@ -298,7 +305,12 @@ jerry_debugger_wait_for_client_source (jerry_debugger_wait_for_source_callback_t
**Example**
[doctest]: # (test="link")
```c
#include "jerryscript.h"
#include "jerryscript-ext/debugger.h"
/**
* Runs the source code received by jerry_debugger_wait_for_client_source.
*/
@ -325,20 +337,23 @@ wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource nam
return ret_val;
} /* wait_for_source_callback */
int main ()
int
main (void)
{
jerry_debugger_wait_for_source_status_t receive_status;
do
{
/* Create a new JerryScript instance when a context reset is
* received. Applications usually registers their core bindings
* here as well (e.g. print, setTimeout). */
jerry_init (JERRY_INIT_EMPTY);
jerry_debugger_init (5001);
jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
&& jerryx_debugger_ws_create ());
do
{
jerry_value_t run_result;
jerry_debugger_wait_for_source_status_t receive_status;
receive_status = jerry_debugger_wait_for_client_source (wait_for_source_callback,
NULL,
@ -369,20 +384,67 @@ 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)
void
jerry_debugger_send_output (const jerry_char_t *buffer, jerry_size_t string_size)
```
**Example**
```c
jerry_init (JERRY_INIT_EMPTY);
jerry_debugger_init (5001);
[doctest]: # (test="link")
jerry_char_t my_output = "Hey, this should be sent too!";
```c
#include "jerryscript.h"
#include "jerryscript-ext/debugger.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
&& jerryx_debugger_ws_create ());
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_debugger_send_output (my_output, my_output_size);
jerry_cleanup ();
}
```
### jerry_debugger_send_log
**Summary**
Sends the program's log to the debugger client.
**Prototype**
```c
void
jerry_debugger_send_log (jerry_log_level_t level, const jerry_char_t *buffer, jerry_size_t string_size)
```
**Example**
[doctest]: # (test="link")
```c
#include "jerryscript.h"
#include "jerryscript-ext/debugger.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
&& jerryx_debugger_ws_create ());
jerry_char_t my_log[] = "Custom diagnostics";
jerry_size_t my_log_size = sizeof (my_log);
jerry_debugger_send_log (JERRY_LOG_LEVEL_DEBUG, my_log, my_log_size);
jerry_cleanup ();
}
```

4
10.EXT-REFERENCE-HANDLER.md
View File

@ -41,7 +41,9 @@ jerryx_handler_assert (const jerry_value_t func_obj_val, const jerry_value_t thi
**Summary**
Expose garbage collector to scripts.
Expose garbage collector to scripts. If the first argument of the function
is logical true, it performs a high severity gc. Otherwise a low severity
gc is performed, which is also the default if no parameters passed.
**Prototype**

2
12.EXT-REFERENCE-MODULE.md
View File

@ -192,7 +192,7 @@ load_and_evaluate_js_file (const jerry_value_t name, jerry_value_t *result)
{
/* We read the file into memory and call jerry_eval (), assigning the result to the out-parameter. */
fread (js_file_contents, file_size, 1, js_file);
(*result) = jerry_eval (js_file_contents, file_size, false);
(*result) = jerry_eval (js_file_contents, file_size, JERRY_PARSE_NO_OPTS);
/* We release the memory holding the contents of the file. */
free (js_file_contents);

258
13.DEBUGGER-TRANSPORT.md Normal file
View File

@ -0,0 +1,258 @@
---
layout: page
title: debugger transport
category: documents
permalink: /debugger-transport/
---
* toc
{:toc}
# JerryScript debugger transport interface
The transport interface support allows dynamic selection of transportation
layers which can encode/decode or send/receive messages transmitted between
the debugger client and server.
# Types
## jerry_debugger_transport_receive_context_t
**Summary**
This context represents the current status of processing received data.
The final state is returned by
[jerry_debugger_transport_receive](#jerry_debugger_transport_receive)
and must be passed to
[jerry_debugger_transport_receive_completed](#jerry_debugger_transport_receive_completed)
after the message is processed.
**Prototype**
```c
typedef struct
{
uint8_t *buffer_p; /**< buffer for storing the received data */
size_t received_length; /**< number of currently received bytes */
uint8_t *message_p; /**< start of the received message */
size_t message_length; /**< length of the received message */
size_t message_total_length; /**< total length for datagram protocols,
* 0 for stream protocols */
} jerry_debugger_transport_receive_context_t;
```
## jerry_debugger_transport_header_t
**Summary**
Shared header for each transport interface. It mostly contains callback functions
used by the JerryScript debugger server.
**Prototype**
```c
typedef struct jerry_debugger_transport_layer_t
{
/* The following fields must be filled before calling jerry_debugger_transport_add(). */
jerry_debugger_transport_close_t close; /**< close connection callback */
jerry_debugger_transport_send_t send; /**< send data callback */
jerry_debugger_transport_receive_t receive; /**< receive data callback */
/* The following fields are filled by jerry_debugger_transport_add(). */
struct jerry_debugger_transport_layer_t *next_p; /**< next transport layer */
} jerry_debugger_transport_header_t;
```
## jerry_debugger_transport_close_t
**Summary**
Called when the connection is closed. Must release all resources (including the
memory area for the transport interface) allocated for the transport interface.
**Prototype**
```c
typedef void (*jerry_debugger_transport_close_t) (struct jerry_debugger_transport_interface_t *header_p);
```
## jerry_debugger_transport_send_t
**Summary**
Called when a message needs to be sent. Must either transmit the message or call
the `header_p->next_p->send()` method.
**Prototype**
```c
typedef bool (*jerry_debugger_transport_send_t) (struct jerry_debugger_transport_interface_t *header_p,
uint8_t *message_p, size_t message_length);
```
## jerry_debugger_transport_receive_t
**Summary**
Called during message processing. If messages are available it must return with
the next message.
**Prototype**
```c
typedef bool (*jerry_debugger_transport_receive_t) (struct jerry_debugger_transport_interface_t *header_p,
jerry_debugger_transport_receive_context_t *context_p);
```
# Transport interface API functions
## jerry_debugger_transport_malloc
**Summary**
Allocates memory for the transport interface.
**Prototype**
```c
void * jerry_debugger_transport_malloc (size_t size);
```
- `size`: size of the memory block.
- return value: non-NULL pointer, if the memory is successfully allocated,
NULL otherwise.
## jerry_debugger_transport_free
**Summary**
Free memory allocated by [jerry_debugger_transport_malloc](#jerry_debugger_transport_malloc)
**Prototype**
```c
void jerry_debugger_transport_free (void *mem_p, size_t size);
```
- `header_p`: header of a transporation interface.
- `size`: total size of the transportation interface.
## jerry_debugger_transport_add
**Summary**
Add a new interface to the transporation interface chain. The interface
will be the first item of the interface chain.
**Prototype**
```c
void jerry_debugger_transport_add (jerry_debugger_transport_header_t *header_p,
size_t send_message_header_size, size_t max_send_message_size,
size_t receive_message_header_size, size_t max_receive_message_size);
```
- `header_p`: header of a transporation interface.
- `send_message_header_size`: size of the outgoing message header, can be 0.
- `max_send_message_size`: maximum outgoing message size supported by the interface.
- `receive_message_header_size`: size of the incoming message header, can be 0.
- `max_receive_message_size`: maximum incoming message size supported by the interface.
## jerry_debugger_transport_start
**Summary**
Starts the communication to the debugger client. Must be called after the
connection is successfully established.
**Prototype**
```c
void jerry_debugger_transport_start (void);
```
## jerry_debugger_transport_is_connected
**Summary**
Tells whether a debugger client is connected to the debugger server.
**Prototype**
```c
bool jerry_debugger_transport_is_connected (void);
```
- return value: `true`, if a client is connected, `false` otherwise.
## jerry_debugger_transport_close
**Summary**
Disconnect from the current debugger client. It does nothing if a client is
not connected,
**Prototype**
```c
void jerry_debugger_transport_close (void);
```
## jerry_debugger_transport_send
**Summary**
Send message to the client.
**Prototype**
```c
bool jerry_debugger_transport_send (const uint8_t *message_p, size_t message_length);
```
- `message_p`: message to be sent.
- `message_length`: message length in bytes.
- return value: `true`, if a client is still connected, `false` otherwise.
## jerry_debugger_transport_receive
**Summary**
Receive message from the client.
**Prototype**
```c
bool jerry_debugger_transport_receive (jerry_debugger_transport_receive_context_t *context_p);
```
- `context_p`: an unused [jerry_debugger_transport_receive_context_t](#jerry_debugger_transport_receive_context_t).
- return value: `true`, if a client is still connected, `false` otherwise.
## jerry_debugger_transport_receive_completed
**Summary**
Must be called after [jerry_debugger_transport_receive](#jerry_debugger_transport_receive)
returns with a valid message. Must not be called otherwise.
**Prototype**
```c
void jerry_debugger_transport_receive_completed (jerry_debugger_transport_receive_context_t *context_p);
```
- `context_p`: a [jerry_debugger_transport_receive_context_t](#jerry_debugger_transport_receive_context_t)
passed to [jerry_debugger_transport_receive](#jerry_debugger_transport_receive).
## jerry_debugger_transport_sleep
**Summary**
Can be used to wait for incoming messages. Currently the delay is 100ms.
**Prototype**
```c
void jerry_debugger_transport_sleep (void);
```