llvm-bindings

LLVM bindings for Node.js/JavaScript/TypeScript

Supported OS

	x86_64	ARM64
macOS 10.15 Catalina	✅	/
macOS 11 Big Sur	✅	✅
macOS 12 Monterey	✅	✅
Ubuntu 18.04	✅	✅
Ubuntu 20.04	✅	✅
Ubuntu 22.04	✅	✅
Windows 10	✅	⚠️
Windows 11	✅	⚠️

⚠️ means not tested.

Supported LLVM methods

listed in the TypeScript definition file.

Install

Install on macOS

Make sure llvm@14 as well as cmake are available, e.g. via

# install cmake and llvm by homebrew
brew install cmake llvm@14

Tell the extra build tool used here (cmake-js) where to find some cmake-specific integration setup of LLVM 14, then npm install the package.

1. First create the required new file named .npmrc
   • alternatively, copy .npmrc.template to .npmrc and adapt the configured path if needed, brew --prefix llvm@14 gives you the install dir of LLVM14.
2. Then run npm install llvm-bindings

# specify the LLVM cmake directory for cmake-js
#  also see '.npmrc.template' for reference
echo "cmake_LLVM_DIR=$($(brew --prefix llvm@14)/bin/llvm-config --cmakedir)" > .npmrc

# install llvm-bindings by npm
npm install llvm-bindings

Install on Ubuntu

#install llvm by installation script
wget https://apt.llvm.org/llvm.sh
sudo chmod +x llvm.sh
sudo ./llvm.sh 14

# install cmake and zlib by apt-get
sudo apt-get install cmake zlib1g-dev

# install llvm-bindings by npm
npm install llvm-bindings

Install on Windows

Update: Use LLVM in version 14.0.6 sequently.

First, please refer to Build LLVM from sources on Windows 10 to build LLVM. An alternative is to download prebuilt LLVM binary.

Then, find the llvm-config command in your LLVM build directory and execute llvm-config --cmakedir to get LLVM cmake directory, assuming C:\Users\dev\llvm-14.0.6.src\build\lib\cmake\llvm.

Finally, execute the following commands.

# specify the LLVM cmake directory for cmake-js
#  also see '.npmrc.template' for reference
echo "cmake_LLVM_DIR=C:\Users\dev\llvm-13.0.1.src\build\lib\cmake\llvm" > .npmrc

# install llvm-bindings by npm
npm install llvm-bindings

Note: The build type of llvm-bindings must be consistent with LLVM, otherwise there will be many compilation errors when building llvm-bindings.

Custom LLVM Installation

You can use the npm configuration options to set the path to the LLVM cmake directory. This is needed if you don't want to use the system default LLVM installation. (Formerly, npm config was used here. Meanwhile npm validates the config keys for being known and valid, and rejects custom keys.)

# specify the llvm cmake directory by npm and cmake-js
#  also see '.npmrc.template' for reference
# on macos `path-to-llvm` can be obtained via `brew --prefix llvm@14`
echo "cmake_LLVM_DIR=$(path-to-llvm/bin/llvm-config --cmakedir)" > .npmrc

# install llvm-bindings by npm
npm install llvm-bindings

Usage

import llvm from 'llvm-bindings';

function main(): void {
    const context = new llvm.LLVMContext();
    const module = new llvm.Module('demo', context);
    const builder = new llvm.IRBuilder(context);

    const returnType = builder.getInt32Ty();
    const paramTypes = [builder.getInt32Ty(), builder.getInt32Ty()];
    const functionType = llvm.FunctionType.get(returnType, paramTypes, false);
    const func = llvm.Function.Create(functionType, llvm.Function.LinkageTypes.ExternalLinkage, 'add', module);

    const entryBB = llvm.BasicBlock.Create(context, 'entry', func);
    builder.SetInsertPoint(entryBB);
    const a = func.getArg(0);
    const b = func.getArg(1);
    const result = builder.CreateAdd(a, b);
    builder.CreateRet(result);

    if (llvm.verifyFunction(func)) {
        console.error('Verifying function failed');
        return;
    }
    if (llvm.verifyModule(module)) {
        console.error('Verifying module failed');
        return;
    }
    console.log(module.print());
}

main();

You cannot declare a variable or constant named module in top level, because module is a built-in object in Node.js.

Note

Due to the limitation of node-addon-api, this project has not implemented inheritance yet, so calling the method of superclass from subclass object will report an error. Please see #1 for details.

Compatibility

llvm-bindings versions	compatible LLVM versions
0.0.x, 0.1.x	11.0.x, 11.1.x
0.2.x	12.0.x
0.3.x	13.0.x
0.4.x	14.0.x

Acknowledgments

• MichaReiser: the creator of llvm-node

llvm-bindings is mostly inspired by llvm-node.