mirror of https://github.com/swig/swig
605 lines
18 KiB
HTML
605 lines
18 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>SWIG and Common Lisp</title>
|
|
<link rel="stylesheet" type="text/css" href="style.css">
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
<H1><a name="Lisp">29 SWIG and Common Lisp</a></H1>
|
|
<!-- INDEX -->
|
|
<div class="sectiontoc">
|
|
<ul>
|
|
<li><a href="#Lisp_nn3">Common Foreign Function Interface(CFFI)</a>
|
|
<ul>
|
|
<li><a href="#Lisp_nn4">Additional Commandline Options </a>
|
|
<li><a href="#Lisp_nn5">Generating CFFI bindings</a>
|
|
<li><a href="#Lisp_nn6">Generating CFFI bindings for C++ code</a>
|
|
<li><a href="#Lisp_nn7">Inserting user code into generated files</a>
|
|
</ul>
|
|
<ul>
|
|
<li><a href="#Lisp_nn9">Additional Commandline Options </a>
|
|
</ul>
|
|
</ul>
|
|
</div>
|
|
<!-- INDEX -->
|
|
|
|
|
|
|
|
<p>
|
|
Common Lisp is a high-level, all-purpose, object-oriented,
|
|
dynamic, functional programming language with long history.
|
|
Common Lisp is used in many fields, ranging from web development to
|
|
finance, and also common in computer science education.
|
|
There are more than 9 different implementations of common lisp which
|
|
are available, all have different foreign function
|
|
interfaces. SWIG currently supports the
|
|
Common Foreign Function Interface(CFFI).
|
|
</p>
|
|
|
|
<H2><a name="Lisp_nn3">29.2 Common Foreign Function Interface(CFFI)</a></H2>
|
|
|
|
|
|
<p>
|
|
CFFI, the Common Foreign Function Interface, is a portable foreign
|
|
function interface for ANSI Common Lisp systems.
|
|
CFFI requires only a small set of
|
|
low-level functionality from the Lisp implementation, such as
|
|
calling a foreign function by name, allocating foreign memory,
|
|
and dereferencing pointers.
|
|
</p>
|
|
|
|
<p>
|
|
To run the cffi module of SWIG requires very little effort, you
|
|
just need to run:
|
|
</p>
|
|
<div class="code"><pre>
|
|
swig -cffi -module <i>module-name</i> <i>file-name</i>
|
|
|
|
</pre></div>
|
|
|
|
<p>
|
|
But a better was of using all the power of SWIG is to write SWIG
|
|
interface files. Below we will explain how to write interface
|
|
files and the various things which you can do with them.
|
|
</p>
|
|
|
|
<H3><a name="Lisp_nn4">29.2.1 Additional Commandline Options </a></H3>
|
|
|
|
|
|
<table summary="CFFI specific options">
|
|
<tr>
|
|
<th> CFFI specific options</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-generate-typedef</td>
|
|
<td>If this option is given then defctype will be used to generate<br/>
|
|
shortcuts according to the typedefs in the input.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-[no]cwrap</td>
|
|
<td>Turn on or turn off generation of an intermediate C file when<br/>
|
|
creating a C interface. By default this is only done for C++ code.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-[no]swig-lisp</td>
|
|
<td>Turns on or off generation of code for helper lisp macro, functions,
|
|
etc. which SWIG uses while generating wrappers. These macros, functions
|
|
may still be used by generated wrapper code.
|
|
</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<H3><a name="Lisp_nn5">29.2.2 Generating CFFI bindings</a></H3>
|
|
|
|
|
|
<p>
|
|
|
|
As we mentioned earlier the ideal way to use SWIG is to use interface
|
|
files. To illustrate the use of it, let's assume that we have a
|
|
file named <i>test.h</i> with the following C code:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
#define y 5
|
|
#define x (y >> 1)
|
|
|
|
typedef int days;
|
|
|
|
struct bar {
|
|
short p, q;
|
|
char a, b;
|
|
int *z[1000];
|
|
struct bar * n;
|
|
};
|
|
|
|
struct bar * my_struct;
|
|
|
|
struct foo {
|
|
int a;
|
|
struct foo * b[100];
|
|
};
|
|
|
|
int pointer_func(void (*ClosureFun)( void* _fun, void* _data, void* _evt ), int p);
|
|
|
|
int func123(div_t * p, int **q[100], int r[][1000][10]);
|
|
|
|
void lispsort_double (int n, double * array);
|
|
|
|
enum color { RED, BLUE, GREEN};
|
|
</pre></div>
|
|
|
|
<p>
|
|
Corresponding to this we will write a simple interface file:
|
|
</p>
|
|
|
|
<div class="code"><pre>
|
|
%module test
|
|
|
|
%include "test.h"
|
|
|
|
</pre></div>
|
|
|
|
<p>
|
|
The generated SWIG Code will be:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
;;;SWIG wrapper code starts here
|
|
|
|
(cl:defmacro defanonenum (&body enums)
|
|
"Converts anonymous enums to defconstants."
|
|
`(cl:progn , @(cl:loop for value in enums
|
|
for index = 0 then (cl:1+ index)
|
|
when (cl:listp value) do (cl:setf index (cl:second value)
|
|
value (cl:first value))
|
|
collect `(cl:defconstant , value , index))))
|
|
|
|
(cl:eval-when (:compile-toplevel :load-toplevel)
|
|
(cl:unless (cl:fboundp 'swig-lispify)
|
|
(cl:defun swig-lispify (name flag cl:&optional (package cl:*package*))
|
|
(cl:labels ((helper (lst last rest cl:&aux (c (cl:car lst)))
|
|
(cl:cond
|
|
((cl:null lst)
|
|
rest)
|
|
((cl:upper-case-p c)
|
|
(helper (cl:cdr lst) 'upper
|
|
(cl:case last
|
|
((lower digit) (cl:list* c #\- rest))
|
|
(cl:t (cl:cons c rest)))))
|
|
((cl:lower-case-p c)
|
|
(helper (cl:cdr lst) 'lower (cl:cons (cl:char-upcase c) rest)))
|
|
((cl:digit-char-p c)
|
|
(helper (cl:cdr lst) 'digit
|
|
(cl:case last
|
|
((upper lower) (cl:list* c #\- rest))
|
|
(cl:t (cl:cons c rest)))))
|
|
((cl:char-equal c #\_)
|
|
(helper (cl:cdr lst) '_ (cl:cons #\- rest)))
|
|
(cl:t
|
|
(cl:error "Invalid character: ~A" c)))))
|
|
(cl:let ((fix (cl:case flag
|
|
((constant enumvalue) "+")
|
|
(variable "*")
|
|
(cl:t ""))))
|
|
(cl:intern
|
|
(cl:concatenate
|
|
'cl:string
|
|
fix
|
|
(cl:nreverse (helper (cl:concatenate 'cl:list name) cl:nil cl:nil))
|
|
fix)
|
|
package))))))
|
|
|
|
;;;SWIG wrapper code ends here
|
|
|
|
|
|
(cl:defconstant y 5)
|
|
|
|
(cl:defconstant x (cl:ash 5 -1))
|
|
|
|
(cffi:defcstruct bar
|
|
(p :short)
|
|
(q :short)
|
|
(a :char)
|
|
(b :char)
|
|
(z :pointer)
|
|
(n :pointer))
|
|
|
|
(cffi:defcvar ("my_struct" my_struct)
|
|
:pointer)
|
|
|
|
(cffi:defcstruct foo
|
|
(a :int)
|
|
(b :pointer))
|
|
|
|
(cffi:defcfun ("pointer_func" pointer_func) :int
|
|
(ClosureFun :pointer)
|
|
(p :int))
|
|
|
|
(cffi:defcfun ("func123" func123) :int
|
|
(p :pointer)
|
|
(q :pointer)
|
|
(r :pointer))
|
|
|
|
(cffi:defcfun ("lispsort_double" lispsort_double) :void
|
|
(n :int)
|
|
(array :pointer))
|
|
|
|
(cffi:defcenum color
|
|
:RED
|
|
:BLUE
|
|
:GREEN)
|
|
</pre></div>
|
|
|
|
<p>
|
|
The <i>SWIG wrapper</i> code refers to the special code which SWIG
|
|
may need to use while wrapping C code. You can turn on/off the
|
|
generation of this code by using the <i>-[no]swig-lisp</i>
|
|
option. You must have noticed that SWIG goes one extra step to
|
|
ensure that CFFI does not do automatic lispification of the C
|
|
function names. The reason SWIG does this is because quite often
|
|
developers want to build a nice CLOS based lispy API, and this one
|
|
to one correspondence between C function names and lisp function
|
|
name helps.
|
|
</p>
|
|
|
|
<p> Maybe you want to have your own convention for generating lisp
|
|
function names for corresponding C function names, or you just
|
|
want to lispify the names, also, before we forget you want to
|
|
export the generated lisp names. To do this, we will use the
|
|
SWIG <a
|
|
href="Customization.html#Customization_features">feature directive</a>.
|
|
Let's edit the interface file such that the C type "div_t*" is changed
|
|
to Lisp type ":my-pointer", we lispify all names,
|
|
export everything, and do some more stuff.
|
|
|
|
</p>
|
|
<div class="code"><pre>
|
|
%module test
|
|
|
|
%typemap(cin) div_t* ":my-pointer"
|
|
|
|
%feature("intern_function", "1");
|
|
%feature("export");
|
|
|
|
%feature("inline") lispsort_double;
|
|
%feature("intern_function", "my-lispify") lispsort_double;
|
|
%feature("export", package="'some-other-package") lispsort_double;
|
|
|
|
%rename func123 renamed_cool_func;
|
|
|
|
%ignore "pointer_func";
|
|
|
|
%include "test.h"
|
|
|
|
</pre></div>
|
|
|
|
<p>
|
|
The <i>typemap(cin)</i> ensures that for all arguments which are input
|
|
to C with the type "div_t*", the ":my-pointer" type be
|
|
used. Similarly <i>typemap(cout)</i> are used for all types which
|
|
are returned from C.
|
|
</p>
|
|
<p>
|
|
The feature <i>intern_function</i> ensures that all C names are
|
|
interned using the <b>swig-lispify</b> function. The "1" given
|
|
to the feature is optional. The use of feature like
|
|
<i>%feature("intern_function", "1");</i> globally enables
|
|
interning for everything. If you want to target a single
|
|
function, or declaration then use the targeted version of
|
|
feature, <i>%feature("intern_function", "my-lispify")
|
|
lispsort_double;</i>, here we are using an additional feature
|
|
which allows us to use our lispify function.
|
|
</p>
|
|
<p>The <i>export</i> feature allows us to export the symbols. If
|
|
the <i>package</i> argument is given, then the symbol will be exported to
|
|
the specified Lisp package. The <i>inline</i> feature declaims the
|
|
declared function as inline. The <i>rename</i> directive allows us to
|
|
change the name(it is useful when generating C wrapper code for handling
|
|
overloaded functions). The <i>ignore</i> directive ignores a certain
|
|
declaration.
|
|
</p>
|
|
<p>There are several other things which are possible, to see some
|
|
example of usage of SWIG look at the Lispbuilder and wxCL
|
|
projects. The generated code with 'noswig-lisp' option is:
|
|
</p>
|
|
|
|
<div class="targetlang"><pre>
|
|
(cl:defconstant #.(swig-lispify "y" 'constant) 5)
|
|
|
|
(cl:export '#.(swig-lispify "y" 'constant))
|
|
|
|
(cl:defconstant #.(swig-lispify "x" 'constant) (cl:ash 5 -1))
|
|
|
|
(cl:export '#.(swig-lispify "x" 'constant))
|
|
|
|
(cffi:defcstruct #.(swig-lispify "bar" 'classname)
|
|
(#.(swig-lispify "p" 'slotname) :short)
|
|
(#.(swig-lispify "q" 'slotname) :short)
|
|
(#.(swig-lispify "a" 'slotname) :char)
|
|
(#.(swig-lispify "b" 'slotname) :char)
|
|
(#.(swig-lispify "z" 'slotname) :pointer)
|
|
(#.(swig-lispify "n" 'slotname) :pointer))
|
|
|
|
(cl:export '#.(swig-lispify "bar" 'classname))
|
|
|
|
(cl:export '#.(swig-lispify "p" 'slotname))
|
|
|
|
(cl:export '#.(swig-lispify "q" 'slotname))
|
|
|
|
(cl:export '#.(swig-lispify "a" 'slotname))
|
|
|
|
(cl:export '#.(swig-lispify "b" 'slotname))
|
|
|
|
(cl:export '#.(swig-lispify "z" 'slotname))
|
|
|
|
(cl:export '#.(swig-lispify "n" 'slotname))
|
|
|
|
(cffi:defcvar ("my_struct" #.(swig-lispify "my_struct" 'variable))
|
|
:pointer)
|
|
|
|
(cl:export '#.(swig-lispify "my_struct" 'variable))
|
|
|
|
(cffi:defcstruct #.(swig-lispify "foo" 'classname)
|
|
(#.(swig-lispify "a" 'slotname) :int)
|
|
(#.(swig-lispify "b" 'slotname) :pointer))
|
|
|
|
(cl:export '#.(swig-lispify "foo" 'classname))
|
|
|
|
(cl:export '#.(swig-lispify "a" 'slotname))
|
|
|
|
(cl:export '#.(swig-lispify "b" 'slotname))
|
|
|
|
(cffi:defcfun ("renamed_cool_func" #.(swig-lispify "renamed_cool_func" 'function)) :int
|
|
(p :my-pointer)
|
|
(q :pointer)
|
|
(r :pointer))
|
|
|
|
(cl:export '#.(swig-lispify "renamed_cool_func" 'function))
|
|
|
|
(cl:declaim (cl:inline #.(my-lispify "lispsort_double" 'function)))
|
|
|
|
(cffi:defcfun ("lispsort_double" #.(my-lispify "lispsort_double" 'function)) :void
|
|
(n :int)
|
|
(array :pointer))
|
|
|
|
(cl:export '#.(my-lispify "lispsort_double" 'function) 'some-other-package)
|
|
|
|
(cffi:defcenum #.(swig-lispify "color" 'enumname)
|
|
#.(swig-lispify "RED" 'enumvalue :keyword)
|
|
#.(swig-lispify "BLUE" 'enumvalue :keyword)
|
|
#.(swig-lispify "GREEN" 'enumvalue :keyword))
|
|
|
|
(cl:export '#.(swig-lispify "color" 'enumname))
|
|
|
|
</pre></div>
|
|
|
|
<H3><a name="Lisp_nn6">29.2.3 Generating CFFI bindings for C++ code</a></H3>
|
|
|
|
|
|
<p>This feature to SWIG (for CFFI) is very new and still far from
|
|
complete. Pitch in with your patches, bug reports and feature
|
|
requests to improve it.
|
|
</p>
|
|
<p> Generating bindings for C++ code, requires <i>-c++</i> option to be
|
|
present and it first generates C binding which will wrap the C++
|
|
code, and then generates the
|
|
corresponding CFFI wrapper code. In the generated C wrapper
|
|
code, you will often want to put your own C code, such as the
|
|
code to include various files. This can be done by making use of
|
|
"%{" and "%}" as shown below.
|
|
</p>
|
|
<div class="code"><pre>
|
|
%{
|
|
#include "Test/test.h"
|
|
%}
|
|
</pre></div>
|
|
<p>
|
|
Also, while parsing the C++ file and generating C wrapper code SWIG
|
|
may need to be able to understand various symbols used in other
|
|
header files. To help SWIG in doing this while ensuring that
|
|
wrapper code is generated for the target file, use the "import"
|
|
directive. The "include" directive specifies the target file for
|
|
which wrapper code will be generated.
|
|
</p>
|
|
<div class="code"><pre>
|
|
|
|
%import "ancillary/header.h"
|
|
|
|
%include "target/header.h"
|
|
|
|
</pre></div>
|
|
<p>
|
|
Various features which were available for C headers can also be used
|
|
here. The target header which we are going to use here is:
|
|
</p>
|
|
<div class="code"><pre>
|
|
namespace OpenDemo {
|
|
class Test
|
|
{
|
|
public:
|
|
float x;
|
|
// constructors
|
|
Test (void) {x = 0;}
|
|
Test (float X) {x = X;}
|
|
|
|
// vector addition
|
|
Test operator+ (const Test& v) const {return Test (x+v.x);}
|
|
|
|
// length squared
|
|
float lengthSquared (void) const {return this->dot (*this);}
|
|
|
|
static float distance (const Test& a, const Test& b){return(a-b).length();}
|
|
|
|
inline Test parallelComponent (const Test& unitBasis) const {
|
|
return unitBasis * projection;
|
|
}
|
|
|
|
Test setYtoZero (void) const {return Test (this->x);}
|
|
|
|
static const Test zero;
|
|
};
|
|
|
|
inline Test operator* (float s, const Test& v) {return v*s;}
|
|
|
|
inline std::ostream& operator<< (std::ostream& o, const Test& v)
|
|
{
|
|
return o << "(" << v.x << ")";
|
|
}
|
|
|
|
inline Test RandomUnitVectorOnXZPlane (void)
|
|
{
|
|
return RandomVectorInUnitRadiusSphere().setYtoZero().normalize();
|
|
}
|
|
}
|
|
</pre></div>
|
|
<p>The interface used is: </p>
|
|
<div class="code"><pre>
|
|
%module test
|
|
%include "test.cpp"
|
|
</pre></div>
|
|
|
|
<p>
|
|
SWIG generates 3 files, the first one is a C wrap which we don't show,
|
|
the second is the plain CFFI wrapper which is as shown below:
|
|
</p>
|
|
<div class="targetlang"><pre>
|
|
(cffi:defcfun ("_wrap_Test_x_set" Test_x_set) :void
|
|
(self :pointer)
|
|
(x :float))
|
|
|
|
(cffi:defcfun ("_wrap_Test_x_get" Test_x_get) :float
|
|
(self :pointer))
|
|
|
|
(cffi:defcfun ("_wrap_new_Test__SWIG_0" new_Test) :pointer)
|
|
|
|
(cffi:defcfun ("_wrap_new_Test__SWIG_1" new_Test) :pointer
|
|
(X :float))
|
|
|
|
(cffi:defcfun ("_wrap_Test___add__" Test___add__) :pointer
|
|
(self :pointer)
|
|
(v :pointer))
|
|
|
|
(cffi:defcfun ("_wrap_Test_lengthSquared" Test_lengthSquared) :float
|
|
(self :pointer))
|
|
|
|
(cffi:defcfun ("_wrap_Test_distance" Test_distance) :float
|
|
(a :pointer)
|
|
(b :pointer))
|
|
|
|
(cffi:defcfun ("_wrap_Test_parallelComponent" Test_parallelComponent) :pointer
|
|
(self :pointer)
|
|
(unitBasis :pointer))
|
|
|
|
(cffi:defcfun ("_wrap_Test_setYtoZero" Test_setYtoZero) :pointer
|
|
(self :pointer))
|
|
|
|
(cffi:defcvar ("Test_zero" Test_zero)
|
|
:pointer)
|
|
|
|
(cffi:defcfun ("_wrap_delete_Test" delete_Test) :void
|
|
(self :pointer))
|
|
|
|
(cffi:defcfun ("_wrap___mul__" __mul__) :pointer
|
|
(s :float)
|
|
(v :pointer))
|
|
|
|
(cffi:defcfun ("_wrap___lshift__" __lshift__) :pointer
|
|
(o :pointer)
|
|
(v :pointer))
|
|
|
|
(cffi:defcfun ("_wrap_RandomUnitVectorOnXZPlane" RandomUnitVectorOnXZPlane) :pointer)
|
|
</pre></div>
|
|
|
|
<p>
|
|
The output is pretty good but it fails in disambiguating overloaded
|
|
functions such as the constructor, in this case. One way of
|
|
resolving this problem is to make the interface use the rename
|
|
directiv, but hopefully there are better solutions.
|
|
In addition SWIG also generates, a CLOS file
|
|
</p>
|
|
|
|
|
|
<div class="targetlang"><pre>
|
|
(clos:defclass test()
|
|
((ff :reader ff-pointer)))
|
|
|
|
(clos:defmethod (cl:setf x) (arg0 (obj test))
|
|
(Test_x_set (ff-pointer obj) arg0))
|
|
|
|
(clos:defmethod x ((obj test))
|
|
(Test_x_get (ff-pointer obj)))
|
|
|
|
(cl:shadow "+")
|
|
(clos:defmethod + ((obj test) (self test) (v test))
|
|
(Test___add__ (ff-pointer obj) (ff-pointer self) (ff-pointer v)))
|
|
|
|
(clos:defmethod length-squared ((obj test) (self test))
|
|
(Test_lengthSquared (ff-pointer obj) (ff-pointer self)))
|
|
|
|
(clos:defmethod parallel-component ((obj test) (self test) (unitBasis test))
|
|
(Test_parallelComponent (ff-pointer obj) (ff-pointer self) (ff-pointer unitBasis)))
|
|
|
|
(clos:defmethod set-yto-zero ((obj test) (self test))
|
|
(Test_setYtoZero (ff-pointer obj) (ff-pointer self)))
|
|
</pre></div>
|
|
|
|
<p>I agree that the CFFI C++ module needs lot more work. But I hope it
|
|
provides a starting point, on which you can base your work of
|
|
importing C++ libraries to Lisp.
|
|
</p>
|
|
<p>
|
|
If you have any questions, suggestions, patches, etc., related to CFFI
|
|
module feel free to contact us on the SWIG mailing list, and
|
|
also please add a "[CFFI]" tag in the subject line.
|
|
|
|
<H3><a name="Lisp_nn7">29.2.4 Inserting user code into generated files</a></H3>
|
|
|
|
|
|
<p>
|
|
It is often necessary to <a href="SWIG.html#SWIG_nn40">include user-defined code</a>
|
|
into the automatically generated interface files. For example, when building
|
|
a C++ interface, example_wrap.cxx will likely not compile unless
|
|
you add a <tt>#include "header.h"</tt> directive. This can be done
|
|
using the SWIG <tt>%insert(section) %{ ...code... %}</tt> directive:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%module example
|
|
|
|
%{
|
|
#include "header.h"
|
|
%}
|
|
|
|
%include "header.h"
|
|
|
|
int fact(int n);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Additional sections have been added for inserting into the
|
|
generated lisp interface file:
|
|
</p>
|
|
<ul>
|
|
<li><tt>lisphead</tt> - inserts before type declarations</li>
|
|
<li><tt>swiglisp</tt> - inserts after type declarations according to
|
|
where it appears in the .i file</li>
|
|
</ul>
|
|
<p>
|
|
Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for
|
|
<tt>%insert("header") %{ ... %}</tt>.
|
|
</p>
|
|
|
|
|
|
</body>
|
|
</html>
|