Update the webpage (#1593)

JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
2025-12-15 16:29:21 +00:00 · 2017-02-17 15:05:07 +01:00 · 2017-02-17 15:05:07 +01:00 · be085d866d
commit be085d866d
parent b89c74fd39
5 changed files with 294 additions and 19 deletions
--- 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
--- 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
--- 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 <string.h>
-#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 <string.h>
-#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 <string.h>
-#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 <string.h>
-#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 <stdlib.h>
 #include <string.h>

-#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 <stdlib.h>
 #include <string.h>

-#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 <string.h>
-#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 <string.h>
-#include "jerry-api.h"
+#include "jerryscript.h"

 /**
 * Add param to 'this.x'
--- a/07.DEBUGGER.md
+++ 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.
--- a/_includes/header.html
+++ b/_includes/header.html
@ -22,7 +22,7 @@
      <ul class="nav navbar-nav navbar-right">
        {% for p in site.pages %}
          {% if p.title %}
-            {% if p.url != "/internals/" and p.url != "/port-api/" and p.url != "/reference-counting/" %}
+            {% if p.url != "/debugger/" and p.url != "/internals/" and p.url != "/port-api/" and p.url != "/reference-counting/" %}
              {% if page.url == p.url %}
                <li class="active"><a href="{{ p.url | prepend: site.github.url }}" >{{ p.title }}</a></li>
              {% else %}
@ -35,7 +35,7 @@
          <ul class="dropdown-menu">
            {% for p in site.pages %}
              {% if p.title %}
-                {% if p.url == "/internals/" or p.url == "/port-api/" or p.url == "/reference-counting/" %}
+                {% if p.url == "/debugger/" and p.url == "/internals/" or p.url == "/port-api/" or p.url == "/reference-counting/" %}
                  <li><a href="{{ p.url | prepend: site.github.url }}" >{{ p.title }}</a></li>
                {% endif %}
              {% endif %}