Skip to main content
Deno 2 is finally here 🎉️
Learn more

deno-ffigen - FFI Bindings generator for Deno

This tool will create typesafe bindings for a C library. You need to provide a C header file and shared library file.

Status

EXPERIMENTAL

Bindings generation tested for:

  • LLVM-C, versions (14, 15)
  • sqlite3
  • lua 5.4

Try it out though, it might just work.

Prerequisites

Following sections assume that [[C_LIB]] is the name of the library you are generating bindings for.

Usage

There are 2 usage variants:

  • build script (recommended)
  • manual steps and cli (for simple cases)

Usage: Build script

Create a build.ts file that uses functions from ffigen.

You can find example (working) build scripts in:

Run it using:

deno run -A build.ts

Usage: Manual steps + cli

Extract definitions from [[C_LIB]].h

docker run -v $(pwd):/data glebbash/deno-ffigen-c2ffi /data/input/[[C_LIB]].h > input/[[C_LIB]].json

This will use prebuilt docker image of c2ffi to generate input/[[C_LIB]].json file containing all symbols found in input/[[C_LIB]].h.

Extract symbols from [[C_LIB]].so

readelf -Ws --dyn-syms input/[[C_LIB]].so > input/[[C_LIB]]_symbols.txt

This will generate input/[[C_LIB]]_symbols.txt file containing names of all exposed symbols of input/[[C_LIB]].so.

Generate bindings

deno run -A https://deno.land/x/ffigen/cli.ts \
  --definitions input/[[C_LIB]].json \
  --symbols input/[[C_LIB]]_symbols.txt \
  --headers [[HEADERS_BASE_URL]] \
  --lib-name [[LIB_NAME]]

Using input/[[C_LIB]].json and input/[[C_LIB]]_symbols.txt as inputs deno-ffigen generates the following files:

  • [[LIB_NAME]]/mod.ts - Bindings entry that also dlopens the shared lib
  • [[LIB_NAME]]/types.ts - Namespace with all type/enum/function definitions
  • [[LIB_NAME]]/symbols.ts - Exports object with lib definition for Deno.dlopen
  • [[LIB_NAME]]/safe-ffi.ts - Type utils for making pointers typesafe

For all the available options run

deno run -A https://deno.land/x/ffigen/cli.ts --help