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 USING
  12 =====
  13
  14 1) Build the shared library.
  15
  16    Ensure you have llvm installed (including llvm-dev if applicable
  17    for your distribution), then run:
  18
  19    $ make -C src build
  20
  21 2) Make the asdf system available.
  22
  23    The way I do that is like this:
  24
  25    $ ln -s $PWD/cl-llvm.asd ~/.sbcl/systems
  26
  27 3) (require 'cl-llvm)
  28
  29 NOTES
  30 =====
  31
  32 There are a few things which I have adjusted in the wrapper:
  33
  34 1) The LLVM C API has a concept of a global context.  I do not use the
  35    C-level global context in the Lisp bindings, but instead have a
  36    lisp-level dynamic variable *llvm-context*, which you may
  37    rebind. (e.g. if you want to use LLVM from multiple threads without
  38    locking, give each thread its own *llvm-context*).
  39
  40    Whenever the LLVM C API has a pair of functions like
  41    "LLVMInt32Type" and "LLVMInt32TypeInContext", I have instead
  42    created a single function "LLVMInt32Type", which takes the same
  43    arguments as the C function, but also takes an extra optional
  44    argument for the context that defaults to *llvm-context*.
  45
  46 2) Where the C API takes a pointer and a count for an array of values,
  47    such as LLVMFunctionType, I have replaced the pointer/length
  48    arguments with a list argument, in the same position.
  49
  50 3) ...Except for LLVMAddIncoming, which in the C API, took an array of
  51    incoming values/blocks to add to the PHI node. I simplified it to
  52    take one at a time: call it multiple times to add multiple incoming
  53    values.
  54
  55 4) Where the C API uses an output array argument, such as
  56    LLVMGetStructElementTypes, I instead return a list.
  57
  58 5) Where the C API takes a pointer to a char *ErrorMsg, ...FIXME
  59    something...