bun-libclang

clang C binding for TypeScript using bun FFI, with comprehensive TypeScript-native object wrapper

You can use it to parse C/C++/ObjC source codes and extract informations.

Background

I just want to grab some enum definitions from Xcode.app for bun-objc, why it's that hard :)

Install

You need Bun and libclang library (often bundled with llvm) to use this library. These are all dependencies.

Core facilities are in bindings.ts, which contains clang C foreign definitions, and index.ts, which builds the API from definitions.

Usage

Above everything, you should call load() before using any of API or function in bun-libclang. This function will open the libclang dynamic library and load FFI functions for you. Always call it first! You can specify the path of your libclang library, or it will try guessing it and finally fallback to DYLD_LIBRARY_PATH.

All clang C data structures have been properly wrapped into native JS objects, for example, new CXCursor() will gives you a "NULL Cursor", which essencially equal to libclang!.getNullCursor(), corresponds to clang_getNullCursor() in C.

You don't need to care about memory management when using the object wrapper. The object wrapper have integrated into JS object finalization protocol, which will dispose resource in C alongside with the garbage collection of JS object.

A typical routine is like:

import { load, CXIndex, CXTranslationUnit, CXCursor } from "./index";
import { CXChildVisitResult } from "./bindings";

load();
const idx = new CXIndex()
const tu = CXTranslationUnit.fromSource(idx, './test/hello.c');
const rootCursor = tu.cursor;
rootCursor.visitChildren((cursor, parent) => {
  // do your things here
  return CXChildVisitResult.recurse;
});

For those needs comprehensive control over FFI, You can use libclang object for raw foreign function access. makeCXCursorVisitor() can be used to create CXCursorVisitor callback function eazily from JS.

By-value structures are properly wrapped into ArrayBuffer using N-API.

See the test folder and official clang C documentation for how to use. You can also consult AI for typical routines.

Todo

This is my hobby project, thus I'm not prioritizing it. If you want any features or need any help, feel free to send an email or open a ticket, and I'll try my best to fullfill your request.

• [ ] Object wrapper for sections below CINDEX_DEBUG of Index.c (~1000 lines) is incomplete;
• [ ] Object wrapper for CINDEX_CPP section lacks documentation;
• [ ] Needs more tests;