Libclangjs NPM

Quickstart

1. Install the package from NPM

$ npm install libclangjs

2.a. Usage with NodeJS

Add the Code you want to analyze using clang

// main.cpp in the root of your project, alongside the package.json
class TestClass {
public:
  TestClass();
  ~TestClass();
};

Analyze the code using clang

import init from "libclangjs/node.js"; // The NodeJS version of libclang uses the CommonJS module format

const cwd = "/home/web_user";

init().then(clang => {
  clang.FS.mount(clang.NODEFS, { root: "." }, cwd); // Share the current directory with libclang
  const index = clang.createIndex(1, 1);
  const tu = clang.parseTranslationUnit(index, `${cwd}/main.cpp`, null, null, 0);
  const cursor = clang.getTranslationUnitCursor(tu);

  clang.visitChildren(cursor, (c, p) => {
    console.log(clang.getCursorKindSpelling(clang.getCursorKind(c)), clang.getCursorSpelling(c), clang.getPresumedLocation(clang.getCursorLocation(c)));
    return clang.CXChildVisitResult.Recurse;
  });

  clang.PThread.terminateAllThreads();
});

2.b. Usage with the browser

const code =
`class TestClass {
public:
  TestClass();
  ~TestClass();
};
`;

// ...

import init from "libclangjs/web"; // The web version of libclang uses the ESM module format

const cwd = "/home/web_user";
init().then(clang => {
  clang.FS.writeFile(`${cwd}/main.cpp`, code); // Create a source file in the memory file system (sharing is not possible, here)
  const index = clang.createIndex(1, 1);
  const tu = clang.parseTranslationUnit(index, `${cwd}/main.cpp`, null, null, 0);
  const cursor = clang.getTranslationUnitCursor(tu);

  clang.visitChildren(cursor, (c, p) => {
    console.log(clang.getCursorKindSpelling(clang.getCursorKind(c)), clang.getCursorSpelling(c), clang.getPresumedLocation(clang.getCursorLocation(c)));
    return clang.CXChildVisitResult.Recurse;
  });

  clang.PThread.terminateAllThreads();
});

Libclang uses multi-threading for maximum performance, which requires the use of a SharedArrayBuffer, which is a well supported feature in modern browsers. Enabling this feature requires setting the Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp headers on the top level document, as described here. An example config for NextJS would look like this:

// next.config.js
const nextConfig = {
  headers: async () => [{
    source: "/:path*",
    headers: [{
      key: "Cross-Origin-Opener-Policy",
      value: "same-origin",
    }, {
      key: "Cross-Origin-Embedder-Policy",
      value: "require-corp",
    }],
  }],
}

module.exports = nextConfig

3. Output

ClassDecl TestClass { filename: '/home/web_user/main.cpp', line: 1, column: 7 }
CXXAccessSpecifier  { filename: '/home/web_user/main.cpp', line: 2, column: 1 }
CXXConstructor TestClass { filename: '/home/web_user/main.cpp', line: 3, column: 3 }
CXXDestructor ~TestClass { filename: '/home/web_user/main.cpp', line: 4, column: 3 }

The execution will take several seconds to complete. A big part of that time is taken by the call to init. Subsequent function calls should run fast - but so far no benchmarking against the native version has been done.