@@ -31,11 +31,11 @@
- The latest release is 0.2, released xx-Jun-2008 (full Changelog
+ The latest release is 0.2, released xx-Jun-2008 (Changelog
below).
Download it here:
@@ -94,162 +94,46 @@ cellspacing="0" cellpadding="4">
-
-
- Bleeding Edge
-
- The latest code can be checked out from SVN thusly:
+ The latest code can be checked out from SVN like so:
$ svn checkout http://llvm-py.googlecode.com/svn/trunk/ llvm-py
- Happy hacking, and please send in your patches.
+ Follow the steps described here to install the
+package.
- Setting Up
-
- Follow these steps to get llvm-py up and running:
-
--
-
-Uninstall any previous version of llvm-py.
-
-
--
-
-Get and build LLVM.
-
-
--
-
-Optionally, install it.
-
-
--
-
-Get the latest release (see above) of llvm-py and untar it:
-
-
-
-
-
- $ wget http://link/llvm-py-0.2.tar.bz2
-$ tar jxvf llvm-py-0.2.tar.bz2
-
-
-
-
- $ cd llvm-py-0.2
-$ sudo python setup.py install
-
-
-
-
- $ cd llvm-py-0.2
-$ sudo python setup.py install --llvm-config=/path/to/llvm-config
-
- That's it!
- Notes:
--
-
-setup.py is a standard Python distutils script. See the Python
- documentation regarding
- Installing Python Modules and
- Distributing Python Modules for
- more information on such scripts.
-
-
--
-
-To build the debug version, build with the -g flag and the debug
- version of llvm-config:
-
-
-
- $ python setup.py build -g --llvm-config=/path/to/Debug/bin/llvm-config
-$ sudo python setup.py install
-
--
-
-Debug binaries are huge! (65 MB+)
-
-
--
-
-If --llvm-config is not specified, setup.py looks for
- llvm-config in the PATH, which will succeed if LLVM is installed.
-
-
-
-
- Uninstall
-
- To get rid of llvm-py completely, if you wish to do so:
-
-
- # rm -rf /usr/lib/python2.5/site-packages/llvm
-# rm -f /usr/lib/python2.5/site-packages/llvm_py-0.1.egg-info
-
-
--
-
-You need to be root to do this.
-
-
--
-
-Paths are for debian-based systems, in other distros it might be different.
-
-
--
-
-Note that there is a version number in the egg file name.
-
-
-
Changelog
- 0.1, 10-May-2008:
+0.2, ongoing:
+
+ * Independent package, need not be unpacked into llvm/bindings
+ * Fixed ownership issues with Module/ModuleProvider
+ * Modules, values and types can be stringified, to get their LLVM
+ assembly representation
+ * Modules and functions can be verified
+ * MemoryBuffer and TypeHandle are available
+ * ExecutionEngine, TargetData and passes are available
+ * Unit tester added (but doesn't test much for now)
+ * Python doc string documentation added (still incomplete)
+ * Many minor style/cosmetic changes and bug fixes
+ * Added documentation as on website into SVN
+
+
+0.1, 10-May-2008:
* Initial release.
-0.2, ongoing:
-
- * Independent package, need not be unpacked into llvm/bindings
- * Modules can be dumped to a string
- * Modules can be verified
- * Module.global_variables, Module.functions, Function.args,
- Function.basic_blocks and BasicBlock.instructions are
- now proper iterators (generators in fact) than plain lists
-
- * MemoryBuffer is done
- * TypeHandle is done
- * Unit tester added (but doesn't do much for now)
diff --git a/www/web/examples.html b/www/web/examples.html
index bc40125..4640e3f 100644
--- a/www/web/examples.html
+++ b/www/web/examples.html
@@ -103,7 +103,7 @@ entry:
diff --git a/www/web/index.html b/www/web/index.html
index 6caa47f..9dae87d 100644
--- a/www/web/index.html
+++ b/www/web/index.html
@@ -35,17 +35,13 @@
- llvm-py provides Python bindings for
-LLVM. It currently provides APIs to build the in-memory IR
-(intermediate representation) and to dump it. Execution engine and related APIs
-should appear soon.
- llvm-py is a set of Python-based and C-based Python modules. It makes use of
-llvm-c, the C binding for LLVM. It is based on the latest SVN version of LLVM
-(and will not work on 2.2). It has been tested only with Python 2.5, although
-it should be usable with 2.4 also. I've built and tested it only on Linux/i386
-machines.
- Download links, setup help and changelog are on the
-download page.
+ llvm-py provides Python bindings for
+LLVM. It's goal is to expose enough of LLVM APIs to
+implement a compiler or VM in pure Python. Currently, llvm-py is
+available for LLVM 2.3 and Python 2.5, on Linux/x86. It is expected to
+be usable on various unices, as well as with Python 2.4, with minimal
+changes, if any. It should be stable enough for you to play with.
+ llvm-py is just hatching, and your contributions would be most welcome.
News
@@ -64,7 +60,7 @@ machines.
diff --git a/www/web/license.html b/www/web/license.html
index 6974210..fb3aaed 100644
--- a/www/web/license.html
+++ b/www/web/license.html
@@ -56,9 +56,9 @@ modification, are permitted provided that the following conditions are met:
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
- * Neither the name of the Mahadevan R, llvm-py nor the names of its
- contributors may be used to endorse or promote products derived from this
- software without specific prior written permission.
+ * Neither the name of this software, nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
@@ -76,7 +76,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/www/web/userguide.html b/www/web/userguide.html
index e05587e..a82d02e 100644
--- a/www/web/userguide.html
+++ b/www/web/userguide.html
@@ -35,7 +35,7 @@
- llvm-py provides Python bindings for LLVM. This document explains how
+ llvm-py provides Python bindings for LLVM. This document explains how
you can setup and use it. A working knowledge of Python and a basic idea
of LLVM is assumed.
@@ -48,27 +48,26 @@ 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 prove easier to create working
+with the LLVM APIs. It should also be easier to create working
prototypes and experimental languages using this medium.
License
- Both LLVM and llvm-py are distributed under (different) permissive
-open source licenses. llvm-py uses the
+ Both LLVM and llvm-py are distributed under (different) permissive
+open source licenses. llvm-py uses the
new BSD license. More
information is available here.
Platforms
- Currently, llvm-py has been built and tested only on Linux/x86. However,
+ Currently, llvm-py has been built and tested only on Linux/x86. However,
it should be trivial to build it on other unices. Windows is not
supported, for a variety of reasons.
Versions
- As of now, llvm-py requires the latest SVN version of LLVM. It will
-not work with version 2.2 of LLVM. However, 2.3 should be release soon,
-and llvm-py should work with stock 2.3 LLVM.
- llvm-py has been built and tested with Python 2.5. It should work with
+ llvm-py requires verion 2.3 of LLVM. It will not work with previous
+versions.
+ llvm-py has been built and tested with Python 2.5. It should work with
Python 2.4, with minimal changes, if any.
-Installation
+Installation
- llvm-py is distributed as a source tarball. You'll need to build and
+ llvm-py is distributed as a source tarball. You'll need to build and
install it before it can be used. At least the following will be
required for this:
@@ -96,7 +95,9 @@ 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'. Note that
ubuntu repository has an old version of llvm (1.8) which will not work
-with llvm-py.
+with llvm-py.
+Tip: If LLVM 2.3 does not install cleanly, try installing ocamldoc
+first.
llvm-config
Inorder to build llvm-py, it's build script needs to know from where to
invoke the llvm helper program, llvm-config. If you've installed LLVM,
@@ -104,6 +105,9 @@ 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 llvm-py. 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
The commands illustrated below assume that the LLVM source is available
under /home/mdevan/llvm. If you've a previous version of llvm-py
@@ -252,8 +256,8 @@ b = PHI(a1, a2);
The PHI node selects a1 or a2, depending on where the control
reached the PHI node. The argument a1 of the PHI node is associated
with the block "a1 = 1;" and a2 with the block "a2 = 2;".
-PHI nodes have to be explicitly created in the LLVM IR. The LLVM
-instruction set therefore has an instruction called phi.
+PHI nodes have to be explicitly created in the LLVM IR. Accordingly the
+LLVM instruction set has an instruction called phi.
LLVM Assembly Language
The LLVM IR can be represented offline in two formats
- a textual, human-readable form, similar to assembly language, called
@@ -323,10 +327,11 @@ most suitable for the code in the module.
There is a LLVM binary called opt,
which lets you run passes on bitcode files from the command line. You
can write your own passes (in C/C++, as a shared library). This can be
-loaded and executed by opt. (Although llvm-py does not allow you to
+loaded and executed by opt. (Although llvm-py does not allow you to
write your own passes, it does allow you to navigate the entire IR at
any stage, and perform any transforms on it as you like.)
-Passes are run using a pass manager. For our purposes, there are two
+Passes are run using a pass manager. For our purposes, there are two
+pass managers TODO
Execution Engine
TODO
BitCode
@@ -334,19 +339,474 @@ any stage, and perform any transforms on it as you like.)
llvm-gcc
TODO
The llvm-py Package
+The llvm-py Package
- modules overview: llvm, llvm.core, llvm.ee, llvm.passes
- importing modules
- core:
- types
- constants
- values
+ The llvm-py is a Python package, consisting of 6 modules, that wrap
+over enough LLVM APIs to allow the implementation of your own
+compiler/VM backend in pure Python. If you're come this far, you
+probably know why this is a good idea.
+ Out of the 6 modules, one is an "extension" module (i.e., it's written
+in C), and another one is a private utility module, which leaves 4
+public modules. These are:
+
+-
+
+llvm — top-level package, common classes (like exceptions)
+
+
+-
+
+llvm.core — IR-related APIs
+
+
+-
+
+llvm.ee — execution engine related APIs
+
+
+-
+
+llvm.passes — pass manager and passes related APIs
+
+
+
+ The modules contain only classes and (integer) constants. Mostly simple
+Python constructs are used (deliberately) —
+property() and
+property
+decorators are probably the most exotic animals around. The APIs are
+designed to be navigable (and guessable!) once you know a few
+conventions. These conventions are highlighted in the sections below.
+ Here is a quick overview of the contents of each package:
+ llvm
+ llvm.core
+-
+
+Module — represents an LLVM Module
+
+
+-
+
+Type — represents an LLVM Type
+
+
+-
+
+IntegerType, FunctionType, StructType, ArrayType, PointerType,
+ VectorType — derived classes of Type
+
+
+-
+
+TypeHandle — used for constructing recursive (self-referencing) types
+ (e.g. linked list nodes)
+
+
+-
+
+Value — represents an LLVM Value
+
+
+-
+
+Constant, GlobalValue, GlobalVariable, Argument, Function,
+ Instruction, CallOrInvokeInstruction, PHINode, SwitchInstruction —
+ various derived classes of Value
+
+
+-
+
+BasicBlock — another derived of Value, represents an LLVM basic block
+
+
+-
+
+Builder — used for creating instructions, wraps LLVM IRBuilder helper
+ class
+
+
+-
+
+ModuleProvider — required to use modules in execution engine and pass
+ manager
+
+
+-
+
+constants TYPE_* that represents various types
+
+
+-
+
+constants CC_* that represent calling conventions
+
+
+-
+
+constants IPRED_* and RPRED_* that represent integer and real
+ comparison predicates (like less than, greater than etc.)
+
+
+-
+
+constants LINKAGE_* that represent linkage of symbols (external,
+ internal etc.)
+
+
+-
+
+constants VISIBILITY_* that represents visibility of symbols
+ (default, hidden, protected)
+
+
+-
+
+constants ATTR_* that represent function parameter attributes
+
+
+
+ llvm.ee
+-
+
+ExecutionEngine — represents an execution engine (which can be an
+ either an interpreter or a JIT)
+
+
+-
+
+TargetData — represents the ABI of the target platform (details like
+ sizes and alignment of primitive types, endinanness etc)
+
+
+
+ llvm.passes
+-
+
+PassManager — represents an LLVM pass manager
+
+
+-
+
+FunctionPassManager — represents an LLVM function pass manager
+
+
+-
+
+constants PASS_* that represent various passes
+
+
+
+ A note on the 'import'ing of these modules
+ Pythonically, modules are imported with the statement "import
+llvm.core" and not "from llvm.core import *". However, you might find
+it more convenient to import llvm-py modules thus:
+
+
+ from llvm import *
+from llvm.core import *
+from llvm.ee import *
+from llvm.passes import *
+
+ This avoids quite some typing. Both conventions work, however.
+
+
+
+
+ |
+Python-style documentation strings (doc) are present in
+llvm-py. You can use the help() of the interactive Python
+interpreter or the object? of IPython
+to get online help. (Note: not complete yet!) |
+
+
+ Module (llvm.core)
+ Modules are top-level container objects. You need to create a module
+object first, before you can add global variables, aliases or functions.
+Modules are created using the static method Module.new:
+
+
+ #!/usr/bin/env python
+
+from llvm import *
+from llvm.core import *
+
+# create a module
+my_module = Module.new('my_module')
+
+ The constructor of the Module class should not be used to instantiate
+a Module object. This is a common feature for all llvm-py classes.
+
+
+|
+
+ |
+
+ Convention
+All llvm-py objects are instantiated using static methods of
+corresponding classes. Constructors should not be used.
+ |
+
+
+ The argument my_module is a module identifier (a plain string).
+ Types (llvm.core)
+ Types are what you think they are. A instance of llvm.core.Type, or
+one of its derived classes, represent a type. llvm-py does not use as
+many classes to represent types as does LLVM itself. Some types are
+represented using llvm.core.Type itself and the rest are represented
+using derived classes of llvm.core.Type. As usual, an instance is created
+via one of the static methods of Type. These methods return an
+instance of either llvm.core.Type itself or one of its derived
+classes.
+ The following table lists all the available types along with the static
+method which has to be used to construct it and the name of the class whose
+object is actually returned by the static method.
+
+
+
+
+
+
+
+ |
+ Name
+ |
+
+ Constructor Method
+ |
+
+ Class
+ |
+
+
+
+
+ |
+ integer of bitwidth n
+ |
+
+ Type.int(n)
+ |
+
+ IntegerType
+ |
+
+
+ |
+ 32-bit float
+ |
+
+ Type.float()
+ |
+
+ Type
+ |
+
+
+ |
+ 64-bit double
+ |
+
+ Type.double()
+ |
+
+ Type
+ |
+
+
+ |
+ 80-bit float
+ |
+
+ Type.x86_fp80()
+ |
+
+ Type
+ |
+
+
+ |
+ 128-bit float (112-bit mantissa)
+ |
+
+ Type.fp128()
+ |
+
+ Type
+ |
+
+
+ |
+ 128-bit float (two 64-bits)
+ |
+
+ Type.ppc_fp128()
+ |
+
+ Type
+ |
+
+
+ |
+ function
+ |
+
+ Type.function(r, p, v)
+ |
+
+ FunctionType
+ |
+
+
+ |
+ unpacked struct
+ |
+
+ Type.struct(eltys)
+ |
+
+ StructType
+ |
+
+
+ |
+ packed struct
+ |
+
+ Type.packed_struct(eltys)
+ |
+
+ StructType
+ |
+
+
+ |
+ array
+ |
+
+ Type.array(elty, count)
+ |
+
+ ArrayType
+ |
+
+
+ |
+ pointer to value of type pty
+ |
+
+ Type.pointer(pty, addrspc)
+ |
+
+ PointerType
+ |
+
+
+ |
+ vector
+ |
+
+ Type.vector(elty, count)
+ |
+
+ VectorType
+ |
+
+
+ |
+ void
+ |
+
+ Type.void()
+ |
+
+ Type
+ |
+
+
+ |
+ label
+ |
+
+ Type.label()
+ |
+
+ Type
+ |
+
+
+ |
+ opaque
+ |
+
+ Type.opaque()
+ |
+
+ Type
+ |
+
+
+
+
+ Values (llvm.core)
+ TODO
+ Instructions (llvm.core)
+ TODO
+ Basic Block (llvm.core)
+ TODO
+ Builder (llvm.core)
+ TODO
+ Module Provider (llvm.core)
+ TODO
+ Execution Engine (llvm.ee)
+ TODO
+ Target Data (llvm.ee)
+ TODO
+ Pass Managers and Passes (llvm.passes)
+ TODO
+ Annotated Examples
+
+About the llvm-py Project
+
+ llvm-py lives at
+http://mdevan.nfshost.com/llvm-py/.
+The code (subversion repository) and the issue tracker are hosted on google
+code, at
+http://code.google.com/p/llvm-py/.
+llvm-py is distributed under the new BSD license, the full license
+text is in the file named
+LICENSE
+available in the source distribution.
+ The entire llvm-py website is generated from marked up text files
+using the tool AsciiDoc. These text
+files and the generated HTML pages are available in the source
+distribution.
+ llvm-py is an ongoing, live project. Your contributions in any form
+are most welcome. You can checkout the latest SVN HEAD from
+here.
+ Mahadevan R wrote llvm-py and works on it in his spare time. He can be
+reached at mdevan.foobar@gmail.com.
| 
-