Skip to content
WIP C++ <> JerryScript wrapper generator
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
wrapper-generator
.gitignore
LICENSE
README.md
generate.js
package.json

README.md

mbed JerryScript wrapper generator

Generates C++/JS wrappers for JavaScript on mbed. This makes it easy to consume C++ APIs from JerryScript.

How to generate a wrapper

  1. Create a C++ application that uses the library - f.e. the example program that comes with the library.

  2. Produce a debug build via:

    $ mbed compile --profile ./mbed-os/tools/profiles/debug.json
    
  3. Go to the build directory and run an object dump:

    $ arm-none-eabi-objdump -Wi -g *.elf > symbols.txt
    
  4. Run this tool to generate the wrapper - where ClassName is the name of the object you want to wrap, and HeaderFile is the .h file of the native library:

    $ npm install
    $ node generate.js symbols.txt ClassName --header-file NativeHeaderFile.h
    

How to use a wrapper

This instructions only work for projects that build via Gulp. See mbed-js-example.

  1. In the wrapper directory: add the native library via mbed add http://path/to/lib.

  2. In your mbed-js project, run npm install PATH_TO_WRAPPER --save --ignore-scripts.

  3. Compile the project with Gulp.

    $ gulp --target=K64F
    

Caveats / tips

  • C++ APIs often look different than a JS API, passing in a pointer and the number of elements. This requires manual work.

  • Higher-level APIs work better than lower-level APIs. F.e. on C++ level use a string rather than a char*. Same goes for arrays.

  • If you want to have a function in JavaScript that then returns another object (rather than a primitive):

    1. Create wrappers for both objects (with --library-name samelibname parameter).
    2. Make a shared .lib file (rather than 2 separate ones) where you declare both objects.
    3. Include the mbed-js-childname.h header in your parent implementation (to expose the mbed_js_wrap_native_object function).
    4. Probably remove the ctor for the child, unless you want JS users to be able to construct their own versions.
    5. That's it!
  • Enums are automatically exposed under the name of the C++ object that declared them (see the _setup calls). F.e.:

    typedef enum { HTTP_GET } http_method;

    Becomes:

    http_method.HTTP_GET
  • Templated functions require the --js-class-name parameter to be set.

    $ node generate.js mqtt-symbols.txt "Client<MQTTNetwork, Countdown, 100, 5>" --js-class-name MqqtClient
    

Todo

  • Callback<> types. There is mbed::js::EventLoop::getInstance().wrapFunction, but it does not handle arguments.
  • vector / array types.
  • C++ APIs are often synchronous. Should have an easy method to make them async (by waiting on an RTOS thread).
  • A whole bunch of primitives are not implemented yet.

Todo (but not sure if possible)

  • Include the header file where the native object is declared. This info does not seem to be in the .elf file.
You can’t perform that action at this time.