diff --git a/01.GETTING-STARTED.md b/01.GETTING-STARTED.md index b17e117f4..b771f1a30 100644 --- a/01.GETTING-STARTED.md +++ b/01.GETTING-STARTED.md @@ -54,10 +54,10 @@ python tools/build.py --debug --lto=off python tools/build.py --cmake-param=CMAKE_PARAM ``` -**Set a profile mode (full, minimal)** +**Set a profile mode (ES5.1, subset of ES2015, minimal)** ```bash -python tools/build.py --feature=full|minimal +python tools/build.py --profile=es5.1|es2015-subset|minimal ``` **Use (jerry, compiler-default, external) libc** @@ -73,7 +73,7 @@ python tools/build.py --jerry-libc=off - external libc: ```bash -python tools/build.py --jerry-libc=off --compile-flag="-nostdlib -I/path/to/ext-libc/include" --link-lib="-lext-c" +python tools/build.py --jerry-libc=off --compile-flag="-nostdlib -I/path/to/ext-libc/include" --link-lib="ext-c" ``` **Add toolchain file** @@ -90,6 +90,37 @@ For example the cross-compile to RaspberryPi 2 is something like this: 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 +``` + +*Note*: System allocator is only supported on 32 bit systems. + +**Enable 32bit compressed pointers** + +```bash +python tools/build.py --cpointer-32bit=on +``` + +*Note*: There is no compression/decompression on 32 bit systems, if enabled. + +**Change default heap size (512K)** + +```bash +python tools/build.py --mem-heap=256 +``` + +If you would like to use more than 512K, then you must enable the 32 bit compressed pointers. + +```bash +python tools/build.py --cpointer-32bit=on --mem-heap=1024 +``` + +*Note*: The heap size will be allocated statically at compile time, when JerryScript memory +allocator is used. + **To get a list of all the available buildoptions for Linux** ```bash diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index 370afb74f..c703844dd 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -18,6 +18,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 @@ -220,6 +221,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** @@ -460,6 +462,40 @@ jerry_parse (const jerry_char_t *source_p, - [jerry_run](#jerryrun) +## 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](#jerryreleasevalue) 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](#jerryparse), except that an additional filename parameter has been added. ## jerry_run @@ -1206,6 +1242,7 @@ jerry_get_string_size (const jerry_value_t value); - [jerry_create_string](#jerrycreatestring) - [jerry_get_string_length](#jerrygetstringlength) +- [jerry_is_valid_cesu8_string](#jerryisvalidcesu8string) ## jerry_get_utf8_string_size @@ -1245,6 +1282,8 @@ jerry_get_utf8_string_size (const jerry_value_t value); - [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) - [jerry_get_utf8_string_length](#jerrygetutf8stringlength) +- [jerry_is_valid_utf8_string](#jerryisvalidutf8string) + ## jerry_get_string_length @@ -1281,6 +1320,8 @@ jerry_get_string_length (const jerry_value_t value); - [jerry_create_string](#jerrycreatestring) - [jerry_get_string_size](#jerrygetstringsize) +- [jerry_is_valid_cesu8_string](#jerryisvalidcesu8string) + ## jerry_get_utf8_string_length @@ -1320,15 +1361,20 @@ jerry_get_utf8_string_length (const jerry_value_t value); - [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) - [jerry_get_utf8_string_size](#jerrygetutf8stringsize) +- [jerry_is_valid_utf8_string](#jerryisvalidutf8string) + ## jerry_string_to_char_buffer **Summary** -Copy the characters of a string into a specified buffer. The -'\0' character could occur in character buffer. Returns 0, -if the value parameter is not a string or the buffer is -not large enough for the whole string. +Copy the characters of a string into a specified cesu-8 buffer. +The '\0' character could occur in the character buffer. Returns 0, +if the value parameter is not a string or the buffer is not large +enough for the whole string. + +*Note*: Does not put '\0' to the end of string, the return value identifies +the number of valid bytes in the output buffer. **Prototype** @@ -1364,6 +1410,8 @@ jerry_string_to_char_buffer (const jerry_value_t value, - [jerry_create_string](#jerrycreatestring) - [jerry_get_string_size](#jerrygetstringsize) +- [jerry_is_valid_cesu8_string](#jerryisvalidcesu8string) + ## jerry_string_to_utf8_char_buffer @@ -1371,9 +1419,12 @@ jerry_string_to_char_buffer (const jerry_value_t value, Copy the characters of a string into a specified utf-8 buffer. The '\0' character could occur in character buffer. Returns 0, -if the value parameter is not a string or the buffer isn't +if the value parameter is not a string or the buffer is not large enough for the whole string. +*Note*: Does not put '\0' to the end of string, the return value identifies +the number of valid bytes in the output buffer. + **Prototype** ```c @@ -1408,6 +1459,8 @@ jerry_string_to_utf8_char_buffer (const jerry_value_t value, - [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) - [jerry_get_utf8_string_size](#jerrygetutf8stringsize) +- [jerry_is_valid_utf8_string](#jerryisvalidutf8string) + ## jerry_substring_to_char_buffer @@ -1419,6 +1472,9 @@ parameter is not a string. It will extract the substring between the specified start position and the end position (or the end of the string, whichever comes first). +*Note*: Does not put '\0' to the end of string, the return value identifies +the number of valid bytes in the output buffer. + **Prototype** ```c @@ -1460,6 +1516,8 @@ jerry_substring_to_char_buffer (const jerry_value_t value, - [jerry_create_string](#jerrycreatestring) - [jerry_get_string_size](#jerrygetstringsize) - [jerry_get_string_length](#jerrygetstringlength) +- [jerry_is_valid_cesu8_string](#jerryisvalidcesu8string) + ## jerry_substring_to_utf8_char_buffer @@ -1471,6 +1529,9 @@ parameter is not a string. It will extract the substring between the specified start position and the end position (or the end of the string, whichever comes first). +*Note*: Does not put '\0' to the end of string, the return value identifies +the number of valid bytes in the output buffer. + **Prototype** ```c @@ -1509,9 +1570,12 @@ jerry_substring_to_utf8_char_buffer (const jerry_value_t value, **See also** -- [jerry_create_string_from_utf8](#jerrycreatestring) +- [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) - [jerry_get_utf8_string_size](#jerrygetutf8stringsize) - [jerry_get_utf8_string_length](#jerrygetutf8stringlength) +- [jerry_is_valid_utf8_string](#jerryisvalidutf8string) + + # Functions for array object values ## jerry_get_array_length @@ -2221,6 +2285,7 @@ jerry_create_string (const jerry_char_t *str_p); **See also** +- [jerry_is_valid_cesu8_string](#jerryisvalidcesu8string) - [jerry_create_string_sz](#jerrycreatestringsz) @@ -2259,8 +2324,10 @@ jerry_create_string_sz (const jerry_char_t *str_p, **See also** +- [jerry_is_valid_cesu8_string](#jerryisvalidcesu8string) - [jerry_create_string](#jerrycreatestring) + ## jerry_create_string_from_utf8 **Summary** @@ -2294,6 +2361,7 @@ jerry_create_string_from_utf8 (const jerry_char_t *str_p); **See also** +- [jerry_is_valid_utf8_string](#jerryisvalidutf8string) - [jerry_create_string_sz_from_utf8](#jerrycreatestringszfromutf8) @@ -2334,8 +2402,10 @@ jerry_create_string_sz (const jerry_char_t *str_p, **See also** +- [jerry_is_valid_utf8_string](#jerryisvalidutf8string) - [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) + ## jerry_create_undefined **Summary** @@ -3248,6 +3318,99 @@ bool foreach_function (const jerry_value_t prop_name, - [jerry_object_property_foreach_t](#jerryobjectpropertyforeacht) +# Input validator functions + +## jerry_is_valid_utf8_string + +**Summary** + +Validate UTF-8 string. + +**Prototype** + +```c +bool +jerry_is_valid_utf8_string (const jerry_char_t *utf8_buf_p, /**< UTF-8 string */ + jerry_size_t buf_size) /**< string size */ +``` + +- `utf8_buf_p` - UTF-8 input string +- `buf_size` - input string size + +**Example** + +```c +{ + const jerry_char_t script[] = "print ('Hello, World!');"; + size_t script_size = strlen ((const char *) script); + + if (jerry_is_valid_utf8_string (script, (jerry_size_t) script_size)) + { + jerry_run_simple (script, script_size, JERRY_INIT_EMPTY); + } +} +``` + +**See also** + +- [jerry_run_simple](#jerryrunsimple) +- [jerry_create_string_from_utf8](#jerrycreatestringfromutf8) +- [jerry_create_string_sz_from_utf8](#jerrycreatestringszfromutf8) +- [jerry_get_utf8_string_size](#jerrygetutf8stringsize) +- [jerry_get_utf8_string_length](#jerrygetutf8stringlength) +- [jerry_string_to_utf8_char_buffer](#jerrystringtoutf8charbuffer) +- [jerry_substring_to_utf8_char_buffer](#jerrysubstringtoutf8charbuffer) + +## jerry_is_valid_cesu8_string + +**Summary** + +Validate CESU-8 string. + +**Prototype** + +```c +bool +jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, /**< CESU-8 string */ + jerry_size_t buf_size) /**< string size */ +``` + +- `cesu8_buf_p` - CESU-8 input string +- `buf_size` - input string size + +**Example** + +```c +{ + jerry_init (JERRY_INIT_EMPTY); + + const jerry_char_t script[] = "Hello, World!"; + size_t script_size = strlen ((const char *) script); + + if (jerry_is_valid_cesu8_string (script, (jerry_size_t) script_size)) + { + jerry_value_t string_value = jerry_create_string_sz (script, + (jerry_size_t) script_size)); + + ... // usage of string_value + + jerry_release_value (string_value); + } + + jerry_cleanup (); +} +``` + +**See also** + +- [jerry_create_string](#jerrycreatestring) +- [jerry_create_string_sz](#jerrycreatestringsz) +- [jerry_get_string_size](#jerrygetstringsize) +- [jerry_get_string_length](#jerrygetstringlength) +- [jerry_string_to_char_buffer](#jerrystringtocharbuffer) +- [jerry_substring_to_char_buffer](#jerrysubstringtocharbuffer) + + # Snapshot functions ## jerry_parse_and_save_snapshot diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md index 535ed78cf..b4eb2ce3b 100644 --- a/03.API-EXAMPLE.md +++ b/03.API-EXAMPLE.md @@ -15,7 +15,7 @@ This guide is intended to introduce you to JerryScript embedding API through cre ```c #include -#include "jerry-api.h" +#include "jerryscript.h" int main (int argc, char *argv[]) @@ -47,7 +47,7 @@ Here we perform the same actions, as `jerry_run_simple`, while splitting into se ```c #include -#include "jerry-api.h" +#include "jerryscript.h" int main (int argc, char *argv[]) @@ -86,7 +86,7 @@ Our code is more complex now, but it introduces possibilities to interact with J ```c #include -#include "jerry-api.h" +#include "jerryscript.h" int main (int argc, char *argv[]) @@ -128,7 +128,7 @@ This way, we execute two independent script parts in one execution environment. ```c #include -#include "jerry-api.h" +#include "jerryscript.h" int main (int argc, char *argv[]) { @@ -185,7 +185,7 @@ The following example function will output a JavaScript value: #include #include -#include "jerry-api.h" +#include "jerryscript.h" #include "jerry-port.h" static void @@ -255,7 +255,7 @@ Shell operation can be described with the following loop: #include #include -#include "jerry-api.h" +#include "jerryscript.h" #include "jerry-port.h" static void print_value (const jerry_value_t); @@ -333,7 +333,7 @@ In this example we demonstrate how to use native function and structures in Java ```c #include -#include "jerry-api.h" +#include "jerryscript.h" struct my_struct { @@ -419,7 +419,7 @@ Here we create a JS Object with `jerry_eval`, then extend it with a native funct ```c #include -#include "jerry-api.h" +#include "jerryscript.h" /** * Add param to 'this.x' diff --git a/07.DEBUGGER.md b/07.DEBUGGER.md new file mode 100644 index 000000000..55083ab61 --- /dev/null +++ b/07.DEBUGGER.md @@ -0,0 +1,81 @@ +--- +layout: page +title: Debugger +permalink: /debugger/ +--- + +* toc +{:toc} + +## 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. diff --git a/_includes/header.html b/_includes/header.html index 7d4f52007..c4f0d388c 100644 --- a/_includes/header.html +++ b/_includes/header.html @@ -22,7 +22,7 @@