========
llvmlite
========

:emphasis:`A lightweight LLVM-Python binding for writing JIT compilers`

llvmlite provides a Python binding to LLVM for use in Numba_. Numba
previously relied on llvmpy_.

Llvmpy became hard to maintain because:

* It has a cumbersome architecture.
* The C++11 requirement of recent LLVM versions does not go well
  with the compiler and runtime ABI requirements of some Python
  versions, especially under Windows.

Llvmpy also proved to be responsible for a sizable part of
Numba's compilation times, because of its inefficient layering
and object encapsulation. Fixing this issue inside the llvmpy
codebase seemed a time-consuming and uncertain task.

The Numba developers decided to start a new binding from scratch,
with an entirely different architecture, centered around the
specific requirements of a JIT compiler.

.. _Numba: http://numba.pydata.org/
.. _llvmpy: http://www.llvmpy.org/

Philosophy
==========

While llvmpy_ exposed large parts of the LLVM C++ API for direct
calls into the LLVM library, llvmlite takes an entirely different
approach. Llvmlite starts from the needs of a JIT compiler and
splits them into two decoupled tasks:

* Construction of a :ref:`module`, function by function,
  :ref:`instruction` by instruction.

* Compilation and optimization of the module into machine code.

The construction of an LLVM module does not call the LLVM C++ API.
Rather, it constructs the
LLVM :ref:`intermediate representation <intermediate representation>`
(IR) in pure Python. This is the role of the
:ref:`IR layer <ir-layer>`.

The compilation of an LLVM module takes the IR in textual form
and feeds it into LLVM's parsing API. It then returns a thin
wrapper around LLVM's C++ module object. This is the role of the
:ref:`binding layer <binding-layer>`.

Once parsed, the module's source code cannot be modified, which
loses the flexibility of the direct mapping of C++ APIs into
Python that was provided by llvmpy but saves a great deal of
maintenance.

LLVM compatibility
==================

Despite minimizing the API surface with LLVM, llvmlite is
impacted by changes to LLVM's C++ API, which can occur at every
feature release. Therefore, each llvmlite version is targeted to
a specific LLVM feature version and works across all given bugfix
releases of that version.

Numba's requirements determine which LLVM version is supported.

The Python and LLVM version requirements and historical compatibility
table below are maintained in ``README.rst`` and included here to avoid
duplication.

.. include:: ../../README.rst
   :start-line: 56
   :end-line: 85

API stability
=============

At this time, we reserve the possibility of slightly breaking
the llvmlite API at each release, for the following reasons:

* Changes in LLVM behaviour, such as differences in the IR across
  versions.

* As a young library, llvmlite has room for improvement or fixes
  to the existing APIs.


.. toctree::
   :maxdepth: 1
   :hidden:

   admin-guide/install
   user-guide/index
   faqs
   contributing
   release-notes
   glossary

.. |reg| unicode:: U+000AE .. REGISTERED SIGN
