README.md

   1 [![Build Status](https://travis-ci.org/cffi/cffi.svg?branch=master)](https://travis-ci.org/cffi/cffi)
   2
   3 # What
   4
   5 CFFI, the Common Foreign Function Interface, purports
   6 to be a portable FFI for Common Lisp. It abstracts away the
   7 differences between the API of the native FFI's of the various Common
   8 Lisp implementations.
   9
  10 # How
  11
  12 The CFFI library is composed of a Lisp-implementation-specific backend
  13 in the CFFI-SYS package, and a portable frontend in the CFFI package.
  14
  15 The CFFI-SYS backend package defines a low-level interface to the
  16 native FFI support in the Lisp implementation. It offers operators for
  17 allocating and dereferencing foreign memory, calling foreign
  18 functions, and loading shared libraries.
  19
  20 The CFFI frontend provides a more comfortable, declarative interface
  21 for defining foreign functions, structures, typedefs, enumerated
  22 types, etc. It is implemented in portable ANSI CL making use of the
  23 low-level operators exported by CFFI-SYS.
  24
  25 The CFFI-LIBFFI subsystem loads support for passing structs by
  26 value. It requires [libffi](https://sourceware.org/libffi/) for that.
  27
  28 Please consult [the
  29 manual](http://common-lisp.net/project/cffi/manual/html_node/) for
  30 further details, including installation instructions.
  31
  32 # Where
  33
  34 Please visit [Github](https://github.com/cffi/cffi/issues) for bug
  35 reports, feature suggestions, the latest version, and to send your
  36 contributions. CFFI also has a [mailing
  37 list](https://mailman.common-lisp.net/listinfo/cffi-devel), and a
  38 project page at [cffi.common-lisp.dev](https://cffi.common-lisp.dev/).
  39
  40 # Notes
  41
  42 ### CFFI/C2FFI
  43
  44 CFFI/C2FFI is an ASDF-integrated mechanism to automatically generate a
  45 complete CFFI binding from a C header file. It requires a CLI tool
  46 called [c2ffi](https://github.com/rpav/c2ffi), but only for the
  47 developers of the libraries, not their users. `c2ffi` is written in
  48 C++, and it uses LLVM/Clang as the parsing library. It generates JSON
  49 output that can be checked in into the repositories. CFFI/C2FFI uses
  50 these JSON files to automatically generate a CL file that contains the
  51 CFFI definition forms. The generated bindings mirror the C namespace
  52 into an otherwise empty CL package as closely as possible. It means
  53 that they retain the upper/lower case of the names, and it also
  54 includes the `#define` macros as CL constants.
  55
  56 Until CFFI/C2FFI is properly documented, you may check out these
  57 projects as examples:
  58 [hu.dwim.zlib](https://github.com/hu-dwim/hu.dwim.zlib),
  59 [hu.dwim.sdl](https://github.com/hu-dwim/hu.dwim.sdl),
  60 [hu.dwim.bluez](https://github.com/hu-dwim/hu.dwim.bluez), and
  61 [hu.dwim.mosquitto](https://github.com/attila-lendvai/hu.dwim.mosquitto).
  62
  63 ### Related projects
  64
  65 - [cl-autowrap](https://github.com/rpav/cl-autowrap) is another
  66   project that uses `c2ffi` to generate CFFI bindings.