README

   1 This is a wrapper around the LLVM C API. The design is to be a fairly
   2 thin wrapper, without much lispification.
   3
   4 NOTE: currently I've checked in the generated bindings in
   5 src/generated/*.lisp. These are autogenerated with SWIG, but with
   6 slightly modified versions of the LLVM .h files to make them work
   7 better with SWIG. (so you shouldn't rebuild them). I'm working on
   8 getting the changes upstream. Oh, and I patched SWIG too because it's
   9 got some annoying bugs in its CFFI generator. :)
  10
  11 LLVM patch:
  12 http://lists.cs.uiuc.edu/pipermail/llvm-commits/Week-of-Mon-20091221/092943.html
  13
  14 SWIG patch:
  15 https://sourceforge.net/tracker/?func=detail&atid=301645&aid=2919048&group_id=1645
  16
  17 USING
  18 =====
  19
  20 1) Build the shared library.
  21
  22    Ensure you have llvm installed (including llvm-dev if applicable
  23    for your distribution), then run:
  24
  25    $ make -C src build
  26
  27 2) Make the asdf system available.
  28
  29    The way I do that is like this:
  30
  31    $ ln -s $PWD/cl-llvm.asd ~/.sbcl/systems
  32
  33 3) (require 'cl-llvm)
  34
  35
  36 There's an example of usage in examples/test.lisp.
  37
  38 A more substantial example of usage is my work to port SBCL itself to
  39 support an LLVM backend, available at:
  40 http://repo.or.cz/w/sbcl/llvm.git/
  41
  42 NOTES
  43 =====
  44
  45 There are a few things which I have adjusted in the wrapper:
  46
  47 1) The LLVM C API has a concept of a global context.  I do not use the
  48    C-level global context in the Lisp bindings, but instead have a
  49    lisp-level dynamic variable *llvm-context*, which you may
  50    rebind. (e.g. if you want to use LLVM from multiple threads without
  51    locking, give each thread its own *llvm-context*).
  52
  53    Whenever the LLVM C API has a pair of functions like
  54    "LLVMInt32Type" and "LLVMInt32TypeInContext", I have instead
  55    created a single function "LLVMInt32Type", which takes the same
  56    arguments as the C function, but also takes an extra optional
  57    argument for the context that defaults to *llvm-context*.
  58
  59 2) Where the C API takes a pointer and a count for an array of values,
  60    such as LLVMFunctionType, I have replaced the pointer/length
  61    arguments with a list argument, in the same position.
  62
  63 3) ...Except for LLVMAddIncoming, which in the C API, took an array of
  64    incoming values/blocks to add to the PHI node. I simplified it to
  65    take one at a time: call it multiple times to add multiple incoming
  66    values.
  67
  68 4) Where the C API uses an output array argument, such as
  69    LLVMGetStructElementTypes, I instead return a list.
  70
  71 5) In LLVMBuild*, where the last argument is a "char *Name", I have
  72    arranged to make that an optional argument, defaulting to the empty
  73    string. The name is only used to give a human-understandable name
  74    to the LHS of the assignment in the LLVM IR. If it is omitted, LLVM
  75    has the sane default of an auto-incrementing integer.
  76
  77 6) "LLVMConstInt(llvm_type ty, uint64 num, bool sign_extend)" has been
  78    wrapped as: "(LLVMConstInt llvm-type arbitrary-width-integer)"
  79    instead, by using the underlying LLVM-side bignum API when
  80    llvm-type is larger than 64 bits. (This is the more intuitive
  81    behavior, and gets rid of the superfluous "sign_extend" argument)
  82
  83 7) Where the C API takes a pointer to a char *ErrorMsg, ...FIXME
  84    something...