ffi qjs-ffi

qjs-ffi

What is it?

qjs-ffi is a foreign function interface for QuickJS. A script can

  • load shared libraries and call their C functions, with bigint for 64-bit integers and structs passed by value,
  • hand JavaScript functions back to C as function pointers (JSCallback),
  • read and write native memory (ptr(), read, toArrayBuffer(), CString),
  • compile and run C code in memory (cc(), optional, uses TinyCC),
  • use a buffer class (usually extending ArrayBuffer) as the type of an argument, a return or a variable (args: [Point], or "Point *" with a types object),
  • generate bindings from C and C++ headers (tools/gen-bindings.js), for this module, for bun:ffi (--target=bun), Deno (--target=deno) or Node 26 (--target=node).

The API follows bun:ffi: dlopen() with a symbol table returns directly callable functions, and there is no name lookup at call time. The older define()/call() interface is available as the module ffi/legacy, see Legacy API.

Linux x86_64 is the main target. mingw64 cross builds compile but have not been tested. libffi and libdl are required.

How to use it

Use dlopen() with a table of symbols. Every entry becomes a function that can be called directly:

import { dlopen } from "ffi";

const lib = dlopen("libm.so.6", {
  pow: { args: ["f64", "f64"], returns: "f64" },
  sqrt: { args: ["f64"], returns: "f64" },
});

console.log(lib.symbols.pow(2, 10)); // 1024
console.log(lib.symbols.sqrt(144)); // 12

lib.close();

dlopen(path, symbolSpecs) returns { symbols, close() }. path may be null to search the symbols already loaded into the process. A missing library or symbol throws a TypeError. Each spec has the form { args, returns, abi }, the same options as CFunction.

Native code can call back into JavaScript. This sorts an array with libc's qsort(), comparing with a JavaScript function:

import { JSCallback, CFunction, dlsym, read, RTLD_DEFAULT } from "ffi";

const compare = new JSCallback((a, b) => read.i32(a) - read.i32(b), {
  args: ["pointer", "pointer"],
  returns: "i32",
});

const qsort = CFunction({
  ptr: dlsym(RTLD_DEFAULT, "qsort"),
  args: ["pointer", "u64", "u64", "pointer"],
  returns: "void",
});

const numbers = new Int32Array([5, 3, 9, 1]);
qsort(numbers, numbers.length, 4n, compare);
console.log(numbers); // 1, 3, 5, 9

compare.close();

With ENABLE_TCC (see below), C source can be compiled and called directly:

import { cc } from "ffi";

const { symbols } = cc({
  source: "hello.c", // int hello() { return 42; }
  symbols: { hello: { args: [], returns: "int" } },
});

console.log(symbols.hello()); // 42

The other functions are in doc/ffi.md.

Installation

Needs CMake, a C compiler, QuickJS with its qjsm launcher. clang is only needed to run the binding generator, and git with network access for ENABLE_TCC, and for BUILD_LIBFFI when the libffi development files are missing (it builds libffi then); see the options below.

cmake -S . -B build
cmake --build build --target quickjs-ffi

This produces the module build/ffi.so (ffi.dll on Windows). To use it from the build directory, point QuickJS at it and import it as ffi:

export QUICKJS_MODULE_PATH=$PWD/build
qjsm script.js

To install it, run cmake --install build. The module goes to the QuickJS C module directory that the configure step prints (C module directory), where import ... from "ffi" finds it without QUICKJS_MODULE_PATH. The binding generator is installed too, see doc/gen-bindings.md.

CMake options:

  • BUILD_STATIC also builds a static quickjs-ffi.a
  • BUILD_LIBFFI is AUTO (default), ON or OFF: ON checks out libffi into third_party/libffi and builds it instead of using the system library, AUTO does that only when no system libffi is found, OFF never does
  • ENABLE_TCC checks out TinyCC into third_party/tinycc, builds libtcc and exports cc(), see doc/c-compiler.md

Documentation

The reference is in doc/, organised like the bun:ffi pages. Good places to start:

See tests/ for small runnable examples and examples/ for bindings to real libraries (cairo, freetype, SDL2, zlib, portmidi).

Tests

tests/run-all.sh

runs every suite in tests/ with qjsm. Scripts in this project are run with qjsm, not qjs: qjs lacks process and other globals, and swallows uncaught errors in module mode.

Limitations

  • A struct passed or returned by value needs its member types spelled out (no unions, no C++ classes, not in a JSCallback).
  • Little-endian targets only.
  • C structures are accessed through classes as types, generated classes (see doc/gen-bindings.md), or with read and toArrayBuffer().
  • The legacy API returns every result as a double.