llvmpym documentation

llvmpym is a python library that provides LLVM binding. Target LLVM version: 18.1.8.

The aim of this project is to provide a full python binding built on top of the LLVM C API.

Currently this project is still in its very early stage. Using the library means involving in the development (reporting bugs, providing ideas and advice, etc.) and accepts potential bugs. Although the binary wheel is hosted on PyPI, it is recommended to build it yourself.

nanobind is used to build the binding.

Features

  1. Editor integration (Language server integration: code completion, docs for API, etc.), though it is normal for pure python library.

  2. Fine-tuned API and well-organized classes.

  3. Follows latest LLVM version.

  4. Sane and Python style memory management (i.e. You don’t need to care about it).

Major differences from the existing LLVM python binding libraries

  • llvmlite

    Pros:

    • Possibly faster than llvmpym in case of IR builder since its implementation is pure python and

    • Better tailored for python use as for some API. For example, it provides attributes property to achieve all the attribute sets of an Function. While in llvmpym, f.get_attributes_at_index(i) is used for doing this job since llvmpym is totally built on top of LLVM C API, which doesn’t provide ability to retrieve attribute sets.

    • Stable and well-tested.

    Cons:

    • Only support old version of LLVM (v14, moving towards v15)

    • Originally tailored for Numba’s use. Till today, some functionalities are not achieved, which is possibly due to sticking on old LLVM version.

    • Separate implementation of LLVM IR builder (in pure python) and binding. The information cannot be seamlessly exchanged.

    • For binding part, the categorization of classes is not as detailed as llvmpym.

    • Possibly high maintenance cost

  • llvmcpy

    Pros:

    • Exceptionally low maintenance cost for tracking API change (automatically generated code).

    • Widely supported LLVM versions and python versions.

    Cons:

    • Interfaces is not well designed (automatically generated code).

    • C style memory management.

    • No editor integration (e.g. language server: code completion, docs)

    • When error occurs, tracing error could be tough since everyone runs programs on different machine, using different python version, LLVM version.

Status

LLVM C API Header File Mapping Status

Header File

Python Modules

Analysis.h

core, analysis

BitReader.h

bit_reader, core

BitWriter.h

core

blake3.h

Comdat.h

Core.h

core

DebugInfo.h

Disassembler.h

Error.h

ErrorHandling.h

error_handling

ExecutionEngine

IRReader.h

core

Linker.h

linker

LLJIT.h

LLJITUtils.h

lto.h

Object.h

OrcEE.h

Orc.h

Remarks.h

Support.h

support

Target.h

target, core

TargetMachine.h

target_machine

<extra>

utils

Table of contents

Misc

Special Thanks