Skip to content

Latest commit

 

History

History
39 lines (22 loc) · 2.66 KB

README.md

File metadata and controls

39 lines (22 loc) · 2.66 KB
Raw

libjs

Simple and ABI stable C bindings to V8 built on libuv. It tightly integrates with libuv, using a dedicated V8 platform implementation for scheduling platform and isolate tasks on libuv event loops.

API

See include/js.h for the public API.

Exceptions

JavaScript exceptions are used for all error handling. A negative return value therefore indicates that an exception is either pending in the case of js_pending_exception, or uncaught if the JavaScript execution stack is empty and an uncaught exception handler is installed in case of js_uncaught_exception. Furthermore, certain functions will immediately return an error value if an exception is already pending when the function was called.

To handle a pending exception in native code, rather than defer it to JavaScript, use the js_get_and_clear_last_exception() function. If the exception cannot be handled, it may be rethrown with js_throw(). If the JavaScript execution stack becomes empty without the exception being handled, it will trigger the uncaught exception handler if installed. If no exception handler is installed and the exception isn't handled explicitly it will be swallowed.

Building

By default, the library is compiled with static V8 prebuilds generated by https://github.com/holepunchto/chromium-prebuilds. You can bring along your own build of V8 by defining the v8 target in your build definition. If you rely on the default V8 prebuilds, make sure to first checkout https://github.com/holepunchto/chromium-prebuilds and follow the instructions on how to make a prebuild.

When configuring the build tree, make sure to define the GN_DIR and GN_OUT_DIR variables, pointing them to your Chromium checkout and the GN output directory:

bare-make generate -D GN_DIR=<chromium>/src -D GN_OUT_DIR=<chromium>/src/<out>

For more information about the GN to CMake bridge, see https://github.com/holepunchto/cmake-gn.

Alternatives

The API is designed in a way that minimises its coupling to V8, making it possible to implement ABI compatible alternatives for cases where V8 might not be ideal. We maintain two such alternatives that might be more appropriate for your use case:

  • https://github.com/holepunchto/libjsc
    Based on the builtin JavaScriptCore framework on Darwin. It implements most of the functionality available in the V8 version and is mostly suitable for iOS and iPadOS.

  • https://github.com/holepunchto/libqjs
    Based on QuickJS. It implements all of the functionality also available in the V8 version, but in a fraction of the size. The performance and memory footprint is comparable to V8 Lite.

License

Apache-2.0