bun:ffi tiene soporte experimental para compilar y ejecutar C desde JavaScript con baja sobrecarga.

---

Uso (cc en bun:ffi)

Consulta la entrada de blog de introducción para obtener más información.

JavaScript:

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("¿Cuál es la respuesta al universo?", hello());

Fuente C:

int hello() {
  return 42;
}

Cuando ejecutes hello.js, imprimirá:

bun hello.js
¿Cuál es la respuesta al universo? 42

Bajo el capó, cc usa TinyCC para compilar el código C y luego enlazarlo con el runtime de JavaScript, convirtiendo eficientemente los tipos en su lugar.

Tipos primitivos

Los mismos valores FFIType en dlopen son compatibles en cc.

FFIType	Tipo C	Alias
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

Cadenas, objetos y tipos no primitivos

Para facilitar el trabajo con cadenas, objetos y otros tipos no primitivos que no se mapean 1:1 a tipos C, cc soporta N-API.

Para pasar o recibir valores de JavaScript sin ninguna conversión de tipo desde una función C, puedes usar napi_value.

También puedes pasar un napi_env para recibir el entorno N-API usado para llamar a la función de JavaScript.

Devolver una cadena C a JavaScript

Por ejemplo, si tienes una cadena en C, puedes devolverla a JavaScript así:

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();

Y en 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;
}

También puedes usar esto para devolver otros tipos como objetos y arrays:

#include <node/node_api.h>

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

Referencia de cc

library: string[]

El array library se usa para especificar las bibliotecas que deben enlazarse con el código C.

type Library = string[];

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

symbols

El objeto symbols se usa para especificar las funciones y variables que deben exponerse a JavaScript.

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

source

El source es una ruta de archivo al código C que debe compilarse y enlazarse con el runtime de JavaScript.

type Source = string | URL | BunFile;

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

flags: string | string[]

El flags es un array opcional de cadenas que deben pasarse al compilador TinyCC.

type Flags = string | string[];

Estas son banderas como -I para directorios de inclusión y -D para definiciones de preprocesador.

define: Record<string, string>

El define es un objeto opcional que debe pasarse al compilador TinyCC.

type Defines = Record<string, string>;

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

Estas son definiciones de preprocesador pasadas al compilador TinyCC.