Updated content on the JerryScript GitHub Pages site
- API refenrece is updated. - API examples are updated. - How To page renamed to Getting Started. - Fixes in Internlas. JerryScript-DCO-1.0-Signed-off-by: István Kádár ikadar@inf.u-szeged.hu
This commit is contained in:
Istvan Kadar
committed by
László Langó
László Langó
parent
6e72dd22fe
commit
c0978d1a42
@@ -0,0 +1,76 @@
|
||||
---
|
||||
layout: page
|
||||
title: Getting Started
|
||||
permalink: /getting-started/
|
||||
---
|
||||
|
||||
* toc
|
||||
{:toc}
|
||||
|
||||
### Setting Up Prerequisites
|
||||
|
||||
Currently, only Ubuntu 14.04+ is officially supported as primary development environment.
|
||||
|
||||
There are several dependencies, that should be installed manually. The following list is required for building:
|
||||
|
||||
- `gcc` higher than `4.8.2`
|
||||
- native
|
||||
- arm-none-eabi
|
||||
- `cmake` higher than `2.8.12.2`
|
||||
- `make` higher than `3.81`
|
||||
- `bash` higher than `4.3.11`
|
||||
- `cppcheck` higher than 1.61
|
||||
- `vera++` higher than 1.2.1
|
||||
|
||||
```bash
|
||||
sudo apt-get install gcc g++ gcc-arm-none-eabi cmake cppcheck vera++
|
||||
```
|
||||
|
||||
To make our scripts run correctly, several shell utilities should be available on the system:
|
||||
|
||||
- `find`
|
||||
- `bc`
|
||||
- `awk`
|
||||
- `sed`
|
||||
- `sha256sum`
|
||||
- `wget`
|
||||
|
||||
Upon first build, `make` would try to setup prerequisites, required for further development and pre-commit testing:
|
||||
|
||||
- STM32F3 and STM32F4 libraries
|
||||
|
||||
```bash
|
||||
make prerequisites -j
|
||||
```
|
||||
|
||||
It may take time, so go grab some coffee:
|
||||
|
||||
```bash
|
||||
Setting up prerequisites... (log file: ./build/prerequisites/prerequisites.log)
|
||||
```
|
||||
|
||||
### Building Debug Version
|
||||
|
||||
To build debug version for Linux:
|
||||
|
||||
```bash
|
||||
make debug.linux -j
|
||||
```
|
||||
|
||||
To build debug version for Linux without LTO (Link Time Optimization):
|
||||
|
||||
```bash
|
||||
LTO=OFF make debug.linux -j
|
||||
```
|
||||
|
||||
### Checking Patch
|
||||
|
||||
```bash
|
||||
make precommit -j
|
||||
```
|
||||
|
||||
If some style guidelines, build or test runs fail during precommit, then this is indicated with a message like this:
|
||||
|
||||
```
|
||||
Build failed. See ./build/bin/unittests/make.log for details.
|
||||
```
|
||||
+2931
File diff suppressed because it is too large
Load Diff
-100
@@ -1,100 +0,0 @@
|
||||
---
|
||||
layout: page
|
||||
title: How To
|
||||
permalink: /how-to/
|
||||
---
|
||||
|
||||
* toc
|
||||
{:toc}
|
||||
|
||||
# How to Get the Sources
|
||||
This step should be simple:
|
||||
|
||||
{% highlight bash %}
|
||||
git clone https://github.com/Samsung/jerryscript.git
|
||||
cd jerryscript
|
||||
{% endhighlight %}
|
||||
|
||||
# How to Setup Recommended Prerequisites
|
||||
|
||||
Currently, we are using Ubuntu Linux 14.04+ as our development environment, so this tutorial was written based on this assumption. Additionaly, it'll be useful to read [Prerequisites]({{ site.baseurl }}/wiki/Prerequisites) wiki page, also.
|
||||
|
||||
There are dependencies, that should be installed manually. The following list is required for building:
|
||||
|
||||
- `gcc` or `g++` higher than `4.8.2`
|
||||
- native
|
||||
- arm-none-eabi
|
||||
- `cmake` higher than `2.8.12.2`
|
||||
- `make` higher than `3.81`
|
||||
- `bash` higher than `4.3.11`
|
||||
|
||||
These tools are required for development:
|
||||
|
||||
- `cppcheck` requires `libpcre`
|
||||
- `vera++` requires `tcl`, `tk` and `boost`
|
||||
|
||||
{% highlight bash %}
|
||||
sudo apt-get install gcc g++
|
||||
sudo apt-get install gcc-arm-none-eabi
|
||||
sudo apt-get install cmake
|
||||
sudo apt-get install libpcre3 libpcre3-dev
|
||||
sudo apt-get install tcl8.6 tcl8.6-dev tk8.6-dev libboost-all-dev
|
||||
{% endhighlight %}
|
||||
|
||||
To make our scripts run correctly, several shell utilities should be available on the system:
|
||||
|
||||
- `find`
|
||||
- `bc`
|
||||
- `awk`
|
||||
- `sed`
|
||||
- `sha256sum`
|
||||
- `wget`
|
||||
|
||||
# How to Build
|
||||
|
||||
After setting up prerequisites, let's built the engine:
|
||||
|
||||
{% highlight bash %}
|
||||
make
|
||||
{% endhighlight %}
|
||||
|
||||
Upon first build, `make` would try to setup prerequisites, required for further development and pre-commit testing:
|
||||
- stm32f3 and stm32f4 libraries
|
||||
- nuttx's headers
|
||||
- cppcheck 1.66
|
||||
- vera++ 1.2.1
|
||||
|
||||
It may take time, so go grab some coffee:
|
||||
|
||||
{% highlight bash %}
|
||||
Setting up prerequisites... (log file: ./build/prerequisites/prerequisites.log)
|
||||
{% endhighlight %}
|
||||
|
||||
# How to Build Debug Version
|
||||
To build debug version for Linux:
|
||||
|
||||
{% highlight bash %}
|
||||
make debug.linux
|
||||
{% endhighlight %}
|
||||
|
||||
To build debug version for Linux without LTO (Link Time Optimization):
|
||||
|
||||
{% highlight bash %}
|
||||
LTO=off make debug.linux
|
||||
{% endhighlight %}
|
||||
|
||||
# How to Run Unittests
|
||||
{% highlight bash %}
|
||||
make unittests
|
||||
{% endhighlight %}
|
||||
|
||||
# How to Check the Patch
|
||||
{% highlight bash %}
|
||||
make precommit -j
|
||||
{% endhighlight %}
|
||||
|
||||
Sometimes pre-commit testing fails, in that case you'll see message like that:
|
||||
|
||||
{% highlight bash %}
|
||||
Build failed. See ./build/bin/unittests/make.log for details.
|
||||
{% endhighlight %}
|
||||
@@ -0,0 +1,517 @@
|
||||
---
|
||||
layout: page
|
||||
title: API Examples
|
||||
permalink: /api-example/
|
||||
---
|
||||
|
||||
* toc
|
||||
{:toc}
|
||||
|
||||
JerryScript Engine can be embedded into any application, providing the way to run JavaScript in a large range of environments - from desktops to low-memory microcontrollers.
|
||||
|
||||
This guide is intended to introduce you to JerryScript embedding API through creation of simple JavaScript shell.
|
||||
|
||||
## Step 1. Execute JavaScript from your application
|
||||
|
||||
```c
|
||||
#include <string.h>
|
||||
#include "jerry-api.h"
|
||||
|
||||
int
|
||||
main (int argc, char * argv[])
|
||||
{
|
||||
const jerry_char_t script[] = "print ('Hello, World!');";
|
||||
size_t script_size = strlen ((const char *) script);
|
||||
|
||||
bool ret_value = jerry_run_simple (script, script_size, JERRY_INIT_EMPTY);
|
||||
|
||||
return (ret_value ? 1 : 0);
|
||||
}
|
||||
```
|
||||
|
||||
The application will generate the following output:
|
||||
|
||||
```bash
|
||||
Hello, World!
|
||||
```
|
||||
|
||||
## Step 2. Split engine initialization and script execution
|
||||
|
||||
Here we perform the same actions, as `jerry_run_simple`, while splitting into several steps:
|
||||
|
||||
- engine initialization
|
||||
- script code setup
|
||||
- script execution
|
||||
- engine cleanup
|
||||
|
||||
|
||||
```c
|
||||
#include <string.h>
|
||||
#include "jerry-api.h"
|
||||
|
||||
int
|
||||
main (int argc, char * argv[])
|
||||
{
|
||||
const jerry_char_t script[] = "print ('Hello, World!');";
|
||||
size_t script_size = strlen ((const char *) script);
|
||||
|
||||
/* Initialize engine */
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
/* Setup Global scope code */
|
||||
jerry_value_t parsed_code = jerry_parse (script, script_size, false);
|
||||
|
||||
if (!jerry_value_has_error_flag (parsed_code))
|
||||
{
|
||||
/* Execute the parsed source code in the Global scope */
|
||||
jerry_value_t ret_value = jerry_run (parsed_code);
|
||||
|
||||
/* Returned value must be freed */
|
||||
jerry_release_value (ret_value);
|
||||
}
|
||||
|
||||
/* Parsed source code must be freed */
|
||||
jerry_release_value (parsed_code);
|
||||
|
||||
/* Cleanup engine */
|
||||
jerry_cleanup ();
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
Our code is more complex now, but it introduces possibilities to interact with JerryScript step-by-step: setup native objects, call JavaScript functions, etc.
|
||||
|
||||
## Step 3. Execution in 'eval'-mode
|
||||
|
||||
```c
|
||||
#include <string.h>
|
||||
#include "jerry-api.h"
|
||||
|
||||
int
|
||||
main (int argc, char * argv[])
|
||||
{
|
||||
const jerry_char_t script_1[] = "var s = 'Hello, World!';";
|
||||
const jerry_char_t script_2[] = "print (s);";
|
||||
|
||||
/* Initialize engine */
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
jerry_value_t eval_ret;
|
||||
|
||||
/* Evaluate script1 */
|
||||
eval_ret = jerry_eval (script_1,
|
||||
strlen ((const char *) script_1),
|
||||
false);
|
||||
|
||||
/* Free JavaScript value, returned by eval */
|
||||
jerry_release_value (eval_ret);
|
||||
|
||||
/* Evaluate script2 */
|
||||
eval_ret = jerry_eval (script_2,
|
||||
strlen ((const char *) script_2),
|
||||
false);
|
||||
|
||||
/* Free JavaScript value, returned by eval */
|
||||
jerry_release_value (eval_ret);
|
||||
|
||||
/* Cleanup engine */
|
||||
jerry_cleanup ();
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
This way, we execute two independent script parts in one execution environment. The first part initializes string variable, and the second outputs the variable.
|
||||
|
||||
## Step 4. Interaction with JavaScript environment
|
||||
|
||||
```c
|
||||
#include <string.h>
|
||||
#include "jerry-api.h"
|
||||
|
||||
int
|
||||
main (int argc, char * argv[]) {
|
||||
const jerry_char_t str[] = "Hello, World!";
|
||||
const jerry_char_t script[] = "print (s);";
|
||||
|
||||
/* Initializing JavaScript environment */
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
/* Getting pointer to the Global object */
|
||||
jerry_value_t global_object = jerry_get_global_object ();
|
||||
|
||||
/* Constructing strings */
|
||||
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "s");
|
||||
jerry_value_t prop_value = jerry_create_string (str);
|
||||
|
||||
/* Setting the string value as a property of the Global object */
|
||||
jerry_set_property (global_object, prop_name, prop_value);
|
||||
|
||||
/* Releasing string values, as it is no longer necessary outside of engine */
|
||||
jerry_release_value (prop_name);
|
||||
jerry_release_value (prop_value);
|
||||
|
||||
/* Releasing the Global object */
|
||||
jerry_release_value (global_object);
|
||||
|
||||
/* Now starting script that would output value of just initialized field */
|
||||
jerry_value_t eval_ret = jerry_eval (script,
|
||||
strlen ((const char *) script),
|
||||
false);
|
||||
|
||||
/* Free JavaScript value, returned by eval */
|
||||
jerry_release_value (eval_ret);
|
||||
|
||||
/* Freeing engine */
|
||||
jerry_cleanup ();
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
The sample will also output 'Hello, World!'. However, now it is not just a part of the source script, but the value, dynamically supplied to the engine.
|
||||
|
||||
## Step 5. Description of JerryScript value descriptors
|
||||
|
||||
JerryScript value can be a boolean, number, null, object, string or undefined. The value has an error flag,
|
||||
that indicates whether is an error or not. Every type has an error flag not only objects. The error flag should
|
||||
be cleared before the value is passed as an argument, otherwise it can lead to a type error. The error objects
|
||||
created by API functions has the error flag set.
|
||||
|
||||
The following example function will output a JavaScript value:
|
||||
|
||||
```c
|
||||
#include <stdlib.h>
|
||||
#include <string.h>
|
||||
|
||||
#include "jerry-api.h"
|
||||
#include "jerry-port.h"
|
||||
|
||||
static void
|
||||
print_value (const jerry_value_t value)
|
||||
{
|
||||
if (jerry_value_is_undefined (value))
|
||||
{
|
||||
jerry_port_logmsg (stdout, "undefined");
|
||||
}
|
||||
else if (jerry_value_is_null (value))
|
||||
{
|
||||
jerry_port_logmsg (stdout, "null");
|
||||
}
|
||||
else if (jerry_value_is_boolean (value))
|
||||
{
|
||||
if (jerry_get_boolean_value (value))
|
||||
{
|
||||
jerry_port_logmsg (stdout, "true");
|
||||
}
|
||||
else
|
||||
{
|
||||
jerry_port_logmsg (stdout, "false");
|
||||
}
|
||||
}
|
||||
/* Float value */
|
||||
else if (jerry_value_is_number (value))
|
||||
{
|
||||
jerry_port_logmsg (stdout, "number");
|
||||
}
|
||||
/* String value */
|
||||
else if (jerry_value_is_string (value))
|
||||
{
|
||||
/* Determining required buffer size */
|
||||
jerry_size_t req_sz = jerry_get_string_size (value);
|
||||
jerry_char_t str_buf_p[req_sz];
|
||||
|
||||
jerry_string_to_char_buffer (value, str_buf_p, req_sz);
|
||||
|
||||
jerry_port_logmsg (stdout, "%s", (const char *) str_buf_p);
|
||||
}
|
||||
/* Object reference */
|
||||
else if (jerry_value_is_object (value))
|
||||
{
|
||||
jerry_port_logmsg (stdout, "[JS object]");
|
||||
}
|
||||
|
||||
jerry_port_logmsg (stdout, "\n");
|
||||
}
|
||||
```
|
||||
|
||||
## Simple JavaScript shell
|
||||
|
||||
Now all building blocks, necessary to construct JavaScript shell, are ready.
|
||||
|
||||
Shell operation can be described with the following loop:
|
||||
|
||||
- read command;
|
||||
- if command is 'quit'
|
||||
- exit loop;
|
||||
- else
|
||||
- eval (command);
|
||||
- print result of eval;
|
||||
- loop.
|
||||
|
||||
```c
|
||||
#include <stdlib.h>
|
||||
#include <string.h>
|
||||
|
||||
#include "jerry-api.h"
|
||||
#include "jerry-port.h"
|
||||
|
||||
static void print_value (const jerry_api_value_t);
|
||||
|
||||
int
|
||||
main (int argc, char * argv[])
|
||||
{
|
||||
bool is_done = false;
|
||||
|
||||
/* Initialize engine */
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
while (!is_done)
|
||||
{
|
||||
char cmd [256];
|
||||
char *cmd_tail = cmd;
|
||||
size_t len = 0;
|
||||
|
||||
jerry_port_logmsg (stdout, "> ");
|
||||
|
||||
/* Read next command */
|
||||
while (true)
|
||||
{
|
||||
if (fread (cmd_tail, 1, 1, stdin) != 1 && len == 0)
|
||||
{
|
||||
is_done = true;
|
||||
break;
|
||||
}
|
||||
if (*cmd_tail == '\n')
|
||||
{
|
||||
break;
|
||||
}
|
||||
|
||||
cmd_tail++;
|
||||
len++;
|
||||
}
|
||||
|
||||
jerry_value_t ret_val;
|
||||
|
||||
/* Evaluate entered command */
|
||||
ret_val = jerry_eval ((const jerry_char_t *) cmd,
|
||||
len,
|
||||
false);
|
||||
|
||||
/* If command evaluated successfully, print value, returned by eval */
|
||||
if (jerry_value_has_error_flag (ret_val))
|
||||
{
|
||||
/* Evaluated JS code thrown an exception
|
||||
* and didn't handle it with try-catch-finally */
|
||||
jerry_port_errormsg ("Unhandled JS exception occured: ");
|
||||
}
|
||||
|
||||
print_value (ret_val);
|
||||
jerry_release_value (ret_val);
|
||||
}
|
||||
|
||||
/* Cleanup engine */
|
||||
jerry_cleanup ();
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
The application inputs commands and evaluates them, one after another.
|
||||
|
||||
## Step 6. Creating JS object in global context
|
||||
|
||||
In this example we demonstrate how to use native function and structures in JavaScript.
|
||||
|
||||
```c
|
||||
#include <string.h>
|
||||
#include "jerry-api.h"
|
||||
|
||||
struct my_struct
|
||||
{
|
||||
const char *msg;
|
||||
} my_struct;
|
||||
|
||||
/**
|
||||
* Get a string from a native object
|
||||
*/
|
||||
static jerry_value_t
|
||||
get_msg_handler (const jerry_value_t func_value, /**< function object */
|
||||
const jerry_value_t this_value, /**< this arg */
|
||||
const jerry_value_t *args_p, /**< function arguments */
|
||||
const jerry_length_t args_cnt) /**< number of function arguments */
|
||||
{
|
||||
return jerry_create_string ((const jerry_char_t *) my_struct.msg);
|
||||
} /* get_msg_handler */
|
||||
|
||||
int
|
||||
main (int argc, char * argv[])
|
||||
{
|
||||
/* Initialize engine */
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
/* Do something with the native object */
|
||||
my_struct.msg = "Hello World";
|
||||
|
||||
/* Create an empty JS object */
|
||||
jerry_value_t object = jerry_create_object ();
|
||||
|
||||
/* Create a JS function object and wrap into a jerry value */
|
||||
jerry_value_t func_obj = jerry_create_external_function (get_msg_handler);
|
||||
|
||||
/* Set the native function as a property of the empty JS object */
|
||||
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "myFunc");
|
||||
jerry_set_property (object, prop_name, func_obj);
|
||||
jerry_release_value (prop_name);
|
||||
jerry_release_value (func_obj);
|
||||
|
||||
/* Wrap the JS object (not empty anymore) into a jerry api value */
|
||||
jerry_value_t global_object = jerry_get_global_object ();
|
||||
|
||||
/* Add the JS object to the global context */
|
||||
prop_name = jerry_create_string ((const jerry_char_t *) "MyObject");
|
||||
jerry_set_property (global_object, prop_name, object);
|
||||
jerry_release_value (prop_name);
|
||||
jerry_release_value (object);
|
||||
jerry_release_value (global_object);
|
||||
|
||||
/* Now we have a "builtin" object called MyObject with a function called myFunc()
|
||||
*
|
||||
* Equivalent JS code:
|
||||
* var MyObject = { myFunc : function () { return "some string value"; } }
|
||||
*/
|
||||
const jerry_char_t script[] = " \
|
||||
var str = MyObject.myFunc (); \
|
||||
print (str); \
|
||||
";
|
||||
size_t script_size = strlen ((const char *) script);
|
||||
|
||||
/* Evaluate script */
|
||||
jerry_value_t eval_ret = jerry_eval (script, script_size, false);
|
||||
|
||||
/* Free JavaScript value, returned by eval */
|
||||
jerry_release_value (eval_ret);
|
||||
|
||||
/* Cleanup engine */
|
||||
jerry_cleanup ();
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
The application will generate the following output:
|
||||
|
||||
```bash
|
||||
Hello World
|
||||
```
|
||||
|
||||
## Step 7. Extending JS Objects with native functions
|
||||
|
||||
Here we create a JS Object with `jerry_eval`, then extend it with a native function. This function shows how to get a property value from the object and how to manipulate it.
|
||||
|
||||
```c
|
||||
#include <string.h>
|
||||
#include "jerry-api.h"
|
||||
|
||||
/**
|
||||
* Add param to 'this.x'
|
||||
*/
|
||||
static jerry_value_t
|
||||
add_handler (const jerry_value_t func_value, /**< function object */
|
||||
const jerry_value_t this_val, /**< this arg */
|
||||
const jerry_value_t *args_p, /**< function arguments */
|
||||
const jerry_length_t args_cnt) /**< number of function arguments */
|
||||
{
|
||||
/* Get 'this.x' */
|
||||
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "x");
|
||||
jerry_value_t x_val = jerry_get_property (this_val, prop_name);
|
||||
|
||||
if (!jerry_value_has_error_flag (x_val))
|
||||
{
|
||||
/* Convert Jerry API values to double */
|
||||
double x = jerry_get_number_value (x_val);
|
||||
double d = jerry_get_number_value (*args_p);
|
||||
|
||||
/* Add the parameter to 'x' */
|
||||
jerry_value_t res_val = jerry_create_number (x + d);
|
||||
|
||||
/* Set the new value of 'this.x' */
|
||||
jerry_set_property (this_val, prop_name, res_val);
|
||||
jerry_release_value (res_val);
|
||||
}
|
||||
|
||||
jerry_release_value (x_val);
|
||||
jerry_release_value (prop_name);
|
||||
|
||||
return jerry_create_undefined ();
|
||||
} /* add_handler */
|
||||
|
||||
int
|
||||
main (int argc, char * argv[])
|
||||
{
|
||||
/* Initialize engine */
|
||||
jerry_init (JERRY_INIT_EMPTY);
|
||||
|
||||
/* Create a JS object */
|
||||
const jerry_char_t my_js_object[] = " \
|
||||
MyObject = \
|
||||
{ x : 12, \
|
||||
y : 'Value of x is ', \
|
||||
foo: function () \
|
||||
{ \
|
||||
return this.y + this.x; \
|
||||
} \
|
||||
} \
|
||||
";
|
||||
|
||||
jerry_value_t my_js_obj_val;
|
||||
|
||||
/* Evaluate script */
|
||||
my_js_obj_val = jerry_eval (my_js_object,
|
||||
strlen ((const char *) my_js_object),
|
||||
false);
|
||||
|
||||
/* Create a JS function object and wrap into a jerry value */
|
||||
jerry_value_t add_func_obj = jerry_create_external_function (add_handler);
|
||||
|
||||
/* Set the native function as a property of previously created MyObject */
|
||||
jerry_value_t prop_name = jerry_create_string ((const jerry_char_t *) "add2x");
|
||||
jerry_set_property (my_js_obj_val, prop_name, add_func_obj);
|
||||
jerry_release_value (add_func_obj);
|
||||
jerry_release_value (prop_name);
|
||||
|
||||
/* Free JavaScript value, returned by eval (my_js_object) */
|
||||
jerry_release_value (my_js_obj_val);
|
||||
|
||||
const jerry_char_t script[] = " \
|
||||
var str = MyObject.foo (); \
|
||||
print (str); \
|
||||
MyObject.add2x (5); \
|
||||
print (MyObject.foo ()); \
|
||||
";
|
||||
size_t script_size = strlen ((const char *) script);
|
||||
|
||||
/* Evaluate script */
|
||||
jerry_value_t eval_ret = jerry_eval (script, script_size, false);
|
||||
|
||||
/* Free JavaScript value, returned by eval */
|
||||
jerry_release_value (eval_ret);
|
||||
|
||||
/* Cleanup engine */
|
||||
jerry_cleanup ();
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
The application will generate the following output:
|
||||
|
||||
```bash
|
||||
Value of x is 12
|
||||
Value of x is 17
|
||||
```
|
||||
|
||||
## Further steps
|
||||
|
||||
For further API description, please visit [API Reference page](https://samsung.github.io/jerryscript/API/) on [JerryScript home page](https://samsung.github.io/jerryscript/).
|
||||
@@ -10,7 +10,7 @@ permalink: /internals/
|
||||
# High-Level Design
|
||||
{: class="thumbnail center-block img-responsive" }
|
||||
|
||||
On the diagram above is shown interaction of major components of JerryScript: Parser and Virtual Machine (VM). Parser performs translation of input ECMAScript application into the byte-code with the specified format (refer to [Bytecode](#byte-code) and [Parser](#parser) page for details). Prepared bytecode is executed by the Virtual Machine that performs interpretation (refer to [Virtual Machine](#virtual-machine) and [ECMA](#ecma) pages for details).
|
||||
The diagram above shows the interactions between the major components of JerryScript: Parser and Virtual Machine (VM). Parser performs translation of input ECMAScript application into the byte-code with the specified format (refer to [Bytecode](#byte-code) and [Parser](#parser) page for details). Prepared bytecode is executed by the Virtual Machine that performs interpretation (refer to [Virtual Machine](#virtual-machine) and [ECMA](#ecma) pages for details).
|
||||
|
||||
# Parser
|
||||
|
||||
@@ -134,7 +134,7 @@ Since most functions require less than 255 literal, small encoding provides a si
|
||||
|
||||
## Literal Store
|
||||
|
||||
JerryScript do not have a global string table for literals, but stores them into the Literal Store. During the parsing phase, when a new literal appears with the same identifier that already has occurred before, the string won't be stored once again, but the identifier in the Literal Store will be used. If a new literal is not in the Literal Store yet, it will be inserted.
|
||||
JerryScript does not have a global string table for literals, but stores them into the Literal Store. During the parsing phase, when a new literal appears with the same identifier that has already occurred before, the string won't be stored once again, but the identifier in the Literal Store will be used. If a new literal is not in the Literal Store yet, it will be inserted.
|
||||
|
||||
## Byte-code Categories
|
||||
|
||||
@@ -245,6 +245,7 @@ simple value is a pre-defined constant which can be:
|
||||
### Compressed Pointers
|
||||
|
||||
Compressed pointers were introduced to save heap space.
|
||||
|
||||
{: class="thumbnail center-block img-responsive" }
|
||||
|
||||
These pointers are 8 byte alligned 16 bit long pointers which can address 512 Kb of memory which is also the maximum size of the JerryScript heap.
|
||||
@@ -283,6 +284,7 @@ The objects are represented as following structure:
|
||||
* type (function object, lexical environment, etc.)
|
||||
|
||||
### Properties of Objects
|
||||
|
||||
{: class="thumbnail center-block img-responsive" }
|
||||
|
||||
Objects have a linked list that contains their properties. This list actually contains property pairs, in order to save memory described in the followings:
|
||||
-307
@@ -1,307 +0,0 @@
|
||||
---
|
||||
layout: page
|
||||
title: Development
|
||||
permalink: /dev-guide/
|
||||
---
|
||||
|
||||
* toc
|
||||
{:toc}
|
||||
|
||||
JerryScript Engine can be embedded into any application, providing the way to run JavaScript in a large range of environments - from desktops to low-memory microcontrollers.
|
||||
|
||||
This guide is intended to introduce you to JerryScript embedding API through creation of simple JavaScript shell.
|
||||
|
||||
## Step 1. Execute JavaScript from your application
|
||||
|
||||
{% highlight cpp %}
|
||||
#include <string.h>
|
||||
#include "jerry.h"
|
||||
|
||||
int
|
||||
main (int argc, char * argv[]) {
|
||||
char script [] = "print ('Hello, World!');";
|
||||
|
||||
jerry_completion_code_t code = jerry_run_simple (script,
|
||||
strlen (script),
|
||||
JERRY_FLAG_EMPTY);
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
The application will generate the following output:
|
||||
|
||||
{% highlight bash %}
|
||||
Hello, World!
|
||||
{% endhighlight %}
|
||||
|
||||
## Step 2. Split engine initialization and script execution
|
||||
|
||||
Here we perform the same actions, as `jerry_run_simple`, while splitting into several steps:
|
||||
|
||||
- engine initialization
|
||||
- script code setup
|
||||
- script execution
|
||||
- engine cleanup
|
||||
|
||||
|
||||
{% highlight cpp %}
|
||||
#include <string.h>
|
||||
#include "jerry.h"
|
||||
|
||||
int
|
||||
main (int argc, char * argv[]) {
|
||||
char script [] = "print ('Hello, World!');";
|
||||
|
||||
// Initialize engine
|
||||
jerry_init (JERRY_FLAG_EMPTY);
|
||||
|
||||
// Setup Global scope code
|
||||
jerry_parse (script, strlen (script));
|
||||
|
||||
// Execute Global scope code
|
||||
jerry_completion_code_t code = jerry_run ();
|
||||
|
||||
// Cleanup engine
|
||||
jerry_cleanup ();
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
Our code is more complex now, but it introduces possibilities to interact with JerryScript step-by-step: setup native objects, call JavaScript functions, etc.
|
||||
|
||||
## Step 3. Execution in 'eval'-mode
|
||||
|
||||
{% highlight cpp %}
|
||||
#include <string.h>
|
||||
#include "jerry.h"
|
||||
|
||||
int
|
||||
main (int argc, char * argv[]) {
|
||||
char script1 [] = "var s = 'Hello, World!';";
|
||||
char script2 [] = "print (s);";
|
||||
|
||||
// Initialize engine
|
||||
jerry_init (JERRY_FLAG_EMPTY);
|
||||
|
||||
jerry_api_value_t eval_ret;
|
||||
|
||||
// Evaluate script1
|
||||
jerry_api_eval (script1, strlen (script1),
|
||||
false, false, &eval_ret);
|
||||
// Free JavaScript value, returned by eval
|
||||
jerry_api_release_value (&eval_ret);
|
||||
|
||||
// Evaluate script2
|
||||
jerry_api_eval (script2, strlen (script2),
|
||||
false, false, &eval_ret);
|
||||
// Free JavaScript value, returned by eval
|
||||
jerry_api_release_value (&eval_ret);
|
||||
|
||||
// Cleanup engine
|
||||
jerry_cleanup ();
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
This way, we execute two independent script parts in one execution environment. The first part initializes string variable, and the second outputs the variable.
|
||||
|
||||
## Step 4. Interaction with JavaScript environment
|
||||
|
||||
{% highlight cpp %}
|
||||
#include <string.h>
|
||||
#include "jerry.h"
|
||||
|
||||
int
|
||||
main (int argc, char * argv[]) {
|
||||
char str [] = "Hello, World!";
|
||||
char var_name [] = "s";
|
||||
char script [] = "print (s);";
|
||||
|
||||
// Initializing JavaScript environment
|
||||
jerry_init (JERRY_FLAG_EMPTY);
|
||||
|
||||
// Getting pointer to the Global object
|
||||
jerry_api_object_t *obj_p = jerry_api_get_global_object ();
|
||||
|
||||
// Constructing string
|
||||
jerry_api_string_t *str_val_p = jerry_api_create_string (str);
|
||||
|
||||
// Constructing string value descriptor
|
||||
jerry_api_value_t val;
|
||||
val.type = JERRY_API_DATA_TYPE_STRING;
|
||||
val.string_p = str_val_p;
|
||||
|
||||
// Setting the string value to field of the Global object
|
||||
jerry_api_set_object_field_value (obj_p, var_name, &val);
|
||||
|
||||
// Releasing string value, as it is no longer necessary outside of engine
|
||||
jerry_api_release_string (str_val_p);
|
||||
|
||||
// Same for pointer to the Global object
|
||||
jerry_api_release_object (obj_p);
|
||||
|
||||
jerry_api_value_t eval_ret;
|
||||
|
||||
// Now starting script that would output value of just initialized field
|
||||
jerry_api_eval (script, strlen (script),
|
||||
false, false, &eval_ret);
|
||||
jerry_api_release_value (&eval_ret);
|
||||
|
||||
// Freeing engine
|
||||
jerry_cleanup ();
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
The sample will also output 'Hello, World!'. However, now it is not just a part of the source script, but the value, dynamically supplied to the engine.
|
||||
|
||||
## Step 5. Description of JavaScript value descriptors
|
||||
|
||||
Structure, used to put values to or receive values from the engine is the following:
|
||||
|
||||
- `type` of the value:
|
||||
- JERRY_API_DATA_TYPE_UNDEFINED (undefined);
|
||||
- JERRY_API_DATA_TYPE_NULL (null);
|
||||
- JERRY_API_DATA_TYPE_BOOLEAN (true / false);
|
||||
- JERRY_API_DATA_TYPE_FLOAT64 (number);
|
||||
- JERRY_API_DATA_TYPE_STRING (string);
|
||||
- JERRY_API_DATA_TYPE_OBJECT (object reference);
|
||||
- `v_bool` (if JERRY_API_DATA_TYPE_BOOLEAN) - boolean value;
|
||||
- `v_float64` (if JERRY_API_DATA_TYPE_FLOAT64) - number value;
|
||||
- `v_string` (if JERRY_API_DATA_TYPE_STRING) - pointer to string;
|
||||
- `v_object` (if JERRY_API_DATA_TYPE_OBJECT) - pointer to object.
|
||||
|
||||
Abstract values, to be sent to or received from the engine are described with the structure.
|
||||
|
||||
Pointers to strings or objects and values should be released just when become unnecessary, using `jerry_api_release_string` or `jerry_api_release_object` and `jerry_api_release_value`, correspondingly.
|
||||
|
||||
The following example function will output a JavaScript value:
|
||||
|
||||
{% highlight cpp %}
|
||||
static void
|
||||
print_value (const jerry_api_value_t * value_p)
|
||||
{
|
||||
switch (value_p->type)
|
||||
{
|
||||
// Simple values: undefined, null, false, true
|
||||
case JERRY_API_DATA_TYPE_UNDEFINED:
|
||||
printf ("undefined");
|
||||
break;
|
||||
case JERRY_API_DATA_TYPE_NULL:
|
||||
printf ("null");
|
||||
break;
|
||||
case JERRY_API_DATA_TYPE_BOOLEAN:
|
||||
if (value_p->v_bool)
|
||||
printf ("true");
|
||||
else
|
||||
printf ("false");
|
||||
break;
|
||||
|
||||
// Number value
|
||||
case JERRY_API_DATA_TYPE_FLOAT64:
|
||||
printf ("%lf", value_p->v_float64);
|
||||
break;
|
||||
|
||||
// String value
|
||||
case JERRY_API_DATA_TYPE_STRING:
|
||||
{
|
||||
ssize_t neg_req_sz, sz;
|
||||
// determining required buffer size
|
||||
neg_req_sz = jerry_api_string_to_char_buffer (value_p->v_string,
|
||||
NULL,
|
||||
0);
|
||||
assert (neg_req_sz < 0);
|
||||
char * str_buf_p = (char*) malloc (-neg_req_sz);
|
||||
sz = jerry_api_string_to_char_buffer (value_p->v_string,
|
||||
str_buf_p,
|
||||
-neg_req_sz);
|
||||
assert (sz == -neg_req_sz);
|
||||
|
||||
printf ("%s", str_buf_p);
|
||||
|
||||
free (str_buf_p);
|
||||
break;
|
||||
}
|
||||
|
||||
// Object reference
|
||||
case JERRY_API_DATA_TYPE_OBJECT:
|
||||
printf ("[JS object]");
|
||||
break;
|
||||
}
|
||||
|
||||
printf ("\n");
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
## Simple JavaScript shell
|
||||
|
||||
Now all building blocks, necessary to construct JavaScript shell, are ready.
|
||||
|
||||
Shell operation can be described with the following loop:
|
||||
|
||||
- read command;
|
||||
- if command is 'quit'
|
||||
- exit loop;
|
||||
- else
|
||||
- eval (command);
|
||||
- print result of eval;
|
||||
- loop.
|
||||
|
||||
{% highlight cpp %}
|
||||
#include <assert.h>
|
||||
#include <stdio.h>
|
||||
#include <stdlib.h>
|
||||
#include <string.h>
|
||||
|
||||
#include "jerry.h"
|
||||
|
||||
static void
|
||||
print_value (const jerry_api_value_t * value_p);
|
||||
|
||||
int
|
||||
main (int argc, char * argv[]) {
|
||||
// Initialize engine
|
||||
jerry_init (JERRY_FLAG_EMPTY);
|
||||
|
||||
char cmd [256];
|
||||
while (true) {
|
||||
printf ("> ");
|
||||
|
||||
// Input next command
|
||||
if (fgets (cmd, sizeof (cmd), stdin) == NULL
|
||||
|| strcmp (cmd, "quit\n") == 0) {
|
||||
// If the command is 'quit', exit from loop
|
||||
break;
|
||||
}
|
||||
|
||||
jerry_api_value_t ret_val;
|
||||
|
||||
// Evaluate entered command
|
||||
jerry_completion_code_t status = jerry_api_eval (cmd, strlen (cmd),
|
||||
false, false,
|
||||
&ret_val);
|
||||
|
||||
// If command evaluated successfully, print value, returned by eval
|
||||
if (status == JERRY_COMPLETION_CODE_OK) {
|
||||
// 'eval' completed successfully
|
||||
print_value (&ret_val);
|
||||
jerry_api_release_value (&ret_val);
|
||||
} else {
|
||||
// evaluated JS code thrown an exception
|
||||
// and didn't handle it with try-catch-finally
|
||||
printf ("Unhandled JS exception occured\n");
|
||||
}
|
||||
|
||||
printf ("\n");
|
||||
fflush (stdout);
|
||||
}
|
||||
|
||||
// Cleanup engine
|
||||
jerry_cleanup ();
|
||||
|
||||
return 0;
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
The application inputs commands and evaluates them, one after another.
|
||||
|
||||
|
||||
## Further steps
|
||||
|
||||
For further API description, please look at [Embedding API](/API).
|
||||
Reference in New Issue
Block a user