aapoalas / libclang_deno

Deno FFI bindings for libclang

Deno libclang C API bindings

Deno bindings to the C lang library C API. The project aims to provide complete C API bindings for libclang.so.14.0.6. The bindings are meant to be close to the original API, while adding garbage collection, adding some JavaScript convenience APIs, prettifying some API names (f.ex. expanding Attr to Attribute, Param to Parameter etc.) and of course, wrapping the raw Deno FFI API with a more idiomatic and fully typed TypeScript API.

The Deno FFI binding declarations are generated automatically by libclang-deno build script which uses the library's APIs to implement a basic C header walker, complete with comment JSDoc'ifying. Check out build.ts for the ugly details.

Starting up

To find libclang, the library uses the LIBCLANG_PATH environment variable. This variable can either contain the direct path to a libclang shared library or a path to the directory containing the shared library. To read the environment variable the library naturally needs the --allow-env=LIBCLANG_PATH Deno permissions flag.

Additionally, as with all FFI libraries at this moment, the library of course needs the --unstable and --allow-ffi flags. Unfortunately, at present it is not enough to give a limited FFI permission flag to just the libclang shared library, eg. --allow-ffi=/lib64/libclang.so.14.0.6 as the library needs to use some Deno FFI APIs beyond dlopen, and those currently require unrestricted FFI permissions.

An example startup:

LIBCLANG_PATH=/lib64 deno run --unstable --allow-env=LIBCLANG_PATH --allow-ffi lib/mod.ts

Entry points and memory management

The main entry point into the libclang API is the CXIndex and its parseTranslationUnit API which matches the clang_parseTranslationUnit2 C API. Once a CXTranslationUnit is created using that API, then its APIs are used to f.ex. get CXFile instances or a CXCursor to traverse the AST.

All classes in libclang-deno are garbage collected, releasing the underlying C memory when the JavaScript object gets garbage collected. If you want to speed up memory releasing, some of the classes have an explicit dispose() method that can be called to synchronously release their memory. Note that unlike the C API, the classes may perform disposing recursively, releasing memory and disabling usage of dependent instances. As an example, calling the dispose() method of CXIndex will also dispose of all CXTranslationUnits owned by the index, which will in turn dipose of all CXFiles created from those.

libclang_deno's Issues

Regression in [email protected]

On macOS M1 on Deno v1.30.0 (latest stable):

// index.ts
const index = new CXIndex(false);

# Run the script using Clang 14.0.0 (which comes with Xcode)
LIBCLANG_PATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib deno run --unstable --allow-env=LIBCLANG_PATH --allow-ffi index.ts

This gives the following error on [email protected] which was not present in [email protected]:

error: Uncaught TypeError: Cannot read properties of undefined (reading 'symbols')
    this.#pointer = libclang.symbols.clang_createIndex(
                             ^
    at new CXIndex (https://deno.land/x/[email protected]/mod.ts:281:30)
    at generateFrameworkMetadata (file:///Users/jamie/Documents/git/clang_metagen_deno/src/gen.ts:150:17)
    at file:///Users/jamie/Documents/git/clang_metagen_deno/src/index.ts:3:16

Failed to use libclang on widows.

I'm trying to use libclang with on windows and that fail:

setup:

in an admin powershell, install llvm with chocolatey:

choco install llvm

prepare a test script:

import * as libclang from "https://deno.land/x/[email protected]/mod.ts";
import { walkSync } from "https://deno.land/[email protected]/fs/walk.ts";
import {
  dirname,
  fromFileUrl,
  join,
} from "https://deno.land/[email protected]/path/mod.ts";

const __dirname = dirname(fromFileUrl(import.meta.url));
const index = new libclang.CXIndex();
const sourceDirectory = join(__dirname, "..", "vips-dev-8.14");
const headers = walkSync(sourceDirectory, { exts: [".h"] });
let allHeaders: string[] = []
for (const header of headers) {
  allHeaders.push(header.path)
}

allHeaders = allHeaders.filter(a => a.endsWith('ffi.h'))

for (const allHeader of allHeaders) {
  const tu = index.parseTranslationUnit(allHeader, [
    `-I${sourceDirectory}`,
  ]);

  tu.getCursor().visitChildren((cursor) => {
    console.log(`${cursor.getKindSpelling()}: ${cursor.getSpelling()}`);
    return libclang.CXChildVisitResult.CXChildVisit_Recurse;
  });
}

Then try to run it from a powershell terminal:

$Env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin\libclang.dll"
echo Global Env Path point to $Env:LIBCLANG_PATH
deno run --unstable -A .\build\generator2.ts

Deno lib access activity viewed by Procmon

Deno never try to load libs next to C:\Program Files\LLVM\bin\

the output error is:

error: Uncaught Error: Could not open library: The specified module could not be found.

  libclang = Deno.dlopen(

that the same issue as: issue 17466

for ref list of file in the LLVM bin directory:

C:\Program Files\LLVM\bin> ls *.dll


    Directory: C:\Program Files\LLVM\bin


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----        02/12/2020     05:30          12240 api-ms-win-core-console-l1-1-0.dll
-a----        02/12/2020     05:30         XXX     39 other api-*.dll
-a----        02/12/2020     05:30          12240 api-ms-win-crt-utility-l1-1-0.dll
-a----        12/07/2022     10:51         317864 concrt140.dll
-a----        16/11/2022     12:19       91027968 libclang.dll
-a----        16/11/2022     12:20      112992768 liblldb.dll
-a----        16/11/2022     12:16         745984 libomp.dll
-a----        16/11/2022     12:20       82832896 LLVM-C.dll
-a----        16/11/2022     12:16       81676288 LTO.dll
-a----        12/07/2022     10:51         566704 msvcp140.dll
-a----        12/07/2022     10:51          23944 msvcp140_1.dll
-a----        12/07/2022     10:51         186800 msvcp140_2.dll
-a----        12/07/2022     10:51          57264 msvcp140_atomic_wait.dll
-a----        12/07/2022     10:51          21424 msvcp140_codecvt_ids.dll
-a----        16/11/2022     12:20         220672 Remarks.dll
-a----        02/12/2020     05:31        1035728 ucrtbase.dll
-a----        12/07/2022     10:51          98224 vcruntime140.dll
-a----        12/07/2022     10:51          37256 vcruntime140_1.dll