JerryGen

A WebIDL to Jerryscript-glue-code compiler

Overview

This compiler takes as input a subset of WebIDL and produces C-code that will "glue" existing C libraries into Jerryscript using that API. The overarching purpose is to allow existing C code libraries to be used in other languages without having to rewrite those libraries, and Javascript, implemented by Jerryscript, is the first language that we attack. Details of the high-level design can be found in our whitepaper and poster presented at the TI Technical Conference in 2017.

We currently support only a subset of the large WebIDL standard. Our design goal was to support the functionality that makes sense for programming embedded architectures, and we used the zephyr.js project as our guide.

Click here to see the list of WebIDL constructs supported.

Enumeration types

- these are strings in WebIDL and Javascript, but we treat them as proper enum types in C.

Callbacks

- these are function pointers in all three languages.

Dictionaries

- these are data structures in all three languages.

Interfaces

- these are objects, containing both methods and attributes, and as such, are stored in the Javascript environment and only accessed by getters/setters on the C side.

Building the generator

JerryGen is controlled by the generate.js script, found in the generator repo.

Click to show installation instructions for the generator.

Clone the generator repo:

git clone https://github.com/t-harvey/JerryGen.git

The generator is built on top of Javascript, so no compilation of the tool is necessary.

Click to show installation instructions for node packages.

First, if you clone the repo and cd into that directory, you should be able to run a single command:

npm install

...if that doesn't work, the individual steps are as follows:

the WebIDL parser:

sudo npm install -g webidl2

file i/o:

sudo npm install -g q-io
npm install file-exists

ast compiler:

sudo npm install -g hogan.js

(NOTE: "hogan.js", not "hogan"!)

boost-y type functions:

sudo npm install lodash

continuation passing/async calls through promises:

sudo npm install q

npm install minimist

...then set NODE_PATH to /usr/local/lib/node_modules (the "-g" on the npm-install command puts them here; you can alternatively install them locally, and then do the obvious...

Building Jerryscript

The instructions for building Jerryscript are here -- note that building Jerryscript without ES2015 features can give results that are difficult to pin down. For example, if the config.h file in the jerry-core directory does not have the variable CONFIG_DISABLE_ES2015_TYPEDARRAY_BUILTIN commented out, then any attempt to use the ArrayBuffer in a script will result in a "Script Error" message from the interpreter, even though the script containing the ArrayBuffer declaration may be otherwise error free. Of course, if a user's scripts don't use ArrayBuffer, then it might behoove him to compile without that feature and thus minimize the size of the interpreter.

Using tools/build.py will produce libraries in the build/lib directory. To get an executable interpreter, these libraries must be linked in to a main.c file. The main_jerrygen.c file provided in the generator/unit_tests/template directory also requires the JerryGen utility files, which are produced by running the generator with the --output_utility_files flag.

We provide an empty WebIDL file for just such a minimal build. Assuming that the user has cloned both the generator and Jerryscript into a directory called work, the commands to build a barebones repl are as follows:

~/work -> generator/generate.js --output_utility_files --package=empty generator/unit_tests/template/empty.idl

~/work -> gcc -g --std=c99 -Djerry_value_has_error_flag=jerry_value_is_error -Ijerryscript/jerry-port/default/include -Ijerryscript/jerry-core/include -Ijerryscript/jerry-ext/include -Ijerryscript/jerry-ext/include/jerryscript-ext/ -I./empty generator/unit_tests/template/main_jerrygen.c empty/webidl*.c jerryscript/build/lib/libjerry-core.a jerryscript/build/lib/libjerry-ext.a jerryscript/build/lib/libjerry-port-default.a -lm
~/work -> ./a.out

Further Documentation

Consult the two-part tutorial, here and here.