C Compiler

bun:ffi has experimental support for compiling and running C from JavaScript with low overhead.

Usage (cc in `bun:ffi`)

See the introduction blog post for background. JavaScript:

hello.ts

import { cc } from "bun:ffi";
import source from "./hello.c" with { type: "file" };

const {
  symbols: { hello },
} = cc({
  source,
  symbols: {
    hello: {
      args: [],
      returns: "int",
    },
  },
});

console.log("What is the answer to the universe?", hello());

C source:

hello.c

int hello() {
  return 42;
}

Running hello.ts prints:

terminal

bun hello.ts
What is the answer to the universe? 42

cc uses TinyCC to compile the C code, then links it with the JavaScript runtime, converting types in-place.

Primitive types

cc supports the same FFIType values as dlopen.

`FFIType`	C Type	Aliases
cstring	`char*`
function	`(void)()()`	`fn`, `callback`
ptr	`void*`	`pointer`, `void`, `char`
i8	`int8_t`	`int8_t`
i16	`int16_t`	`int16_t`
i32	`int32_t`	`int32_t`, `int`
i64	`int64_t`	`int64_t`
i64_fast	`int64_t`
u8	`uint8_t`	`uint8_t`
u16	`uint16_t`	`uint16_t`
u32	`uint32_t`	`uint32_t`
u64	`uint64_t`	`uint64_t`
u64_fast	`uint64_t`
f32	`float`	`float`
f64	`double`	`double`
bool	`bool`
char	`char`
napi_env	`napi_env`
napi_value	`napi_value`

Strings, objects, and non-primitive types

For strings, objects, and other non-primitive types that don’t map 1:1 to C types, cc supports N-API. Use napi_value to pass or receive JavaScript values from a C function without any type conversions. You can also pass a napi_env to receive the N-API environment used to call the JavaScript function.

Returning a C string to JavaScript

For example, to return a string from C to JavaScript:

hello.ts

import { cc } from "bun:ffi";
import source from "./hello.c" with { type: "file" };

const {
  symbols: { hello },
} = cc({
  source,
  symbols: {
    hello: {
      args: ["napi_env"],
      returns: "napi_value",
    },
  },
});

const result = hello();

And in C:

hello.c

#include <node/node_api.h>

napi_value hello(napi_env env) {
  napi_value result;
  napi_create_string_utf8(env, "Hello, Napi!", NAPI_AUTO_LENGTH, &result);
  return result;
}

The same approach returns other types like objects and arrays:

hello.c

#include <node/node_api.h>

napi_value hello(napi_env env) {
  napi_value result;
  napi_create_object(env, &result);
  return result;
}

`cc` Reference

`library: string[]`

Use the library array to specify the libraries to link with the C code.

type Library = string[];

cc({
  source: "hello.c",
  library: ["sqlite3"],
});

`symbols`

Use the symbols object to specify the functions and variables to expose to JavaScript.

type Symbols = {
  [key: string]: {
    args: FFIType[];
    returns: FFIType;
  };
};

`source`

source is the path to the C code to compile and link with the JavaScript runtime.

type Source = string | URL | BunFile;

cc({
  source: "hello.c",
  symbols: {
    hello: {
      args: [],
      returns: "int",
    },
  },
});

`flags: string | string[]`

flags is an optional array of strings passed to the TinyCC compiler.

type Flags = string | string[];

These are flags like -I for include directories and -D for preprocessor definitions.

`define: Record<string, string>`

define is an optional object of preprocessor definitions passed to the TinyCC compiler.

type Defines = Record<string, string>;

cc({
  source: "hello.c",
  define: {
    NDEBUG: "1",
  },
});

​Usage (cc in bun:ffi)

​Primitive types

​Strings, objects, and non-primitive types

​Returning a C string to JavaScript

​cc Reference

​library: string[]

​symbols

​source

​flags: string | string[]

​define: Record<string, string>

Usage (cc in `bun:ffi`)

Primitive types

Strings, objects, and non-primitive types

Returning a C string to JavaScript

`cc` Reference

`library: string[]`

`symbols`

`source`

`flags: string | string[]`

`define: Record<string, string>`