1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
========
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.
EXAMPLE: Llvmlite 0.12.0 works with LLVM 3.8.0 and 3.8.1, but
it does not work with LLVM 3.7.0 or 3.9.0.
Numba's requirements determine which LLVM version is supported.
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
|
