110 lines
3.7 KiB
ReStructuredText
110 lines
3.7 KiB
ReStructuredText
|
|
Introduction
|
|
============
|
|
|
|
`LLVM <http://www.llvm.org/>`_ (Low-Level Virtual Machine) provides
|
|
enough infrastructure to use it as the backend for your compiled, or
|
|
JIT-compiled language. It provides extensive optimization support, and
|
|
static and dynamic (JIT) backends for many platforms. See the website at
|
|
http://www.llvm.org/ to discover more.
|
|
|
|
Python bindings for LLVM provides a gentler learning curve for working
|
|
with the LLVM APIs. It should also be easier to create working
|
|
prototypes and experimental languages using this medium.
|
|
|
|
Together with `clang <http://clang.llvm.org/>`_ or
|
|
`llvm-gcc <http://llvm.org/releases/2.7/docs/CommandGuide/html/llvmgcc.html>`_
|
|
it also a provides a means to quickly instrument C and C++ sources. For e.g.,
|
|
llvm-gcc can be used to generate the LLVM assembly for a given C source file,
|
|
which can then be loaded and manipulated (adding profiling code to every function,
|
|
say) using a llvmpy based Python script.
|
|
|
|
License
|
|
-------
|
|
|
|
Both LLVM and llvmpy are distributed under (different) permissive open
|
|
source licenses. llvmpy uses the `new BSD
|
|
license <http://opensource.org/licenses/bsd-license.php>`_. More
|
|
information is available
|
|
`here <https://github.com/llvmpy/llvmpy/blob/master/LICENSE>`_.
|
|
|
|
Platforms
|
|
---------
|
|
|
|
llvmpy has been built/tested/reported to work on various GNU/Linux
|
|
flavours, BSD, Mac OS X; on i386 and amd64 architectures. Windows is not
|
|
supported, for a variety of reasons.
|
|
|
|
Versions
|
|
--------
|
|
|
|
llvmpy 0.9 requires version 3.1 of LLVM. It may not work with
|
|
previous versions.
|
|
|
|
llvmpy has been built and tested with Python 2.7 and 3.2. It should work with
|
|
earlier versions.
|
|
|
|
|
|
Installation
|
|
============
|
|
|
|
The Git repo of llvmpy is at https://github.com/llvmpy/llvmpy.git.
|
|
You'll need to build and install it before it can be used. At least the
|
|
following will be required for this:
|
|
|
|
- C and C++ compilers (gcc/g++)
|
|
- Python itself
|
|
- Python development files (headers and libraries)
|
|
- LLVM, either installed or built
|
|
|
|
On debian-based systems, the first three can be installed with the
|
|
command ``sudo apt-get install gcc g++ python python-dev``. Ensure that
|
|
your distro's repository has the appropriate version of LLVM!
|
|
|
|
It does not matter which compiler LLVM itself was built with (``g++``,
|
|
``llvm-g++`` or any other); llvmpy can be built with any compiler. It
|
|
has been tried only with gcc/g++ though.
|
|
|
|
|
|
LLVM and ``--enable-pic``
|
|
-------------------------
|
|
|
|
The result of an LLVM build is a set of static libraries and object
|
|
files. The llvmpy contains an extension package that is built into a
|
|
shared object (\_core.so) which links to these static libraries and
|
|
object files. It is therefore required that the LLVM libraries and
|
|
object files be built with the ``-fPIC`` option (generate position
|
|
independent code). Be sure to use the ``--enable-pic`` option while
|
|
configuring LLVM (default is no PIC), like this:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ ~/llvm ./configure --enable-pic --enable-optimized
|
|
|
|
llvm-config
|
|
-----------
|
|
|
|
In order to build llvmpy, it's build script needs to know from where it
|
|
can invoke the llvm helper program, ``llvm-config``. If you've installed
|
|
LLVM, then this will be available in your ``PATH``, and nothing further
|
|
needs to be done. If you've built LLVM yourself, or for any reason
|
|
``llvm-config`` is not in your ``PATH``, you'll need to pass the full
|
|
path of ``llvm-config`` to the build script.
|
|
|
|
You'll need to be 'root' to install llvmpy. Remember that your ``PATH``
|
|
is different from that of 'root', so even if ``llvm-config`` is in your
|
|
``PATH``, it may not be available when you do ``sudo``.
|
|
|
|
Steps
|
|
-----
|
|
|
|
Get 3.1 version of LLVM, build it. Make sure '--enable-pic' is passed to
|
|
LLVM's 'configure'.
|
|
|
|
Get llvmpy and install it:
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
$ git clone git@github.com:numba/llvmpy.git
|
|
$ cd llvmpy $ python setup.py install
|