diff options
Diffstat (limited to 'Doc/Manual/Lisp.html')
| -rw-r--r-- | Doc/Manual/Lisp.html | 246 |
1 files changed, 24 insertions, 222 deletions
diff --git a/Doc/Manual/Lisp.html b/Doc/Manual/Lisp.html index ba42f735c..6eb448a12 100644 --- a/Doc/Manual/Lisp.html +++ b/Doc/Manual/Lisp.html @@ -7,11 +7,10 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Lisp">27 SWIG and Common Lisp</a></H1> +<H1><a name="Lisp">29 SWIG and Common Lisp</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> -<li><a href="#Lisp_nn2">Allegro Common Lisp</a> <li><a href="#Lisp_nn3">Common Foreign Function Interface(CFFI)</a> <ul> <li><a href="#Lisp_nn4">Additional Commandline Options </a> @@ -19,12 +18,9 @@ <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> -<li><a href="#Lisp_nn8">CLISP</a> <ul> <li><a href="#Lisp_nn9">Additional Commandline Options </a> -<li><a href="#Lisp_nn10">Details on CLISP bindings</a> </ul> -<li><a href="#Lisp_nn11">UFFI </a> </ul> </div> <!-- INDEX --> @@ -38,26 +34,17 @@ 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 only the Allegro Common - Lisp, Common Foreign Function Interface(CFFI), CLisp and UFFI - foreign function interfaces. + interfaces. SWIG currently supports the + Common Foreign Function Interface(CFFI). </p> -<H2><a name="Lisp_nn2">27.1 Allegro Common Lisp</a></H2> - -<p> - Allegro Common Lisp support in SWIG has been updated to include - support for both C and C++. You can read about the interface - <a href="Allegrocl.html#Allegrocl">here</a> -</p> - -<H2><a name="Lisp_nn3">27.2 Common Foreign Function Interface(CFFI)</a></H2> +<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, similar in - spirit to UFFI. Unlike UFFI, CFFI requires only a small set of + 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. @@ -78,17 +65,8 @@ swig -cffi -module <i>module-name</i> <i>file-name</i> files and the various things which you can do with them. </p> -<H3><a name="Lisp_nn4">27.2.1 Additional Commandline Options </a></H3> - - -<p> -The following table list the additional commandline options available for the CLISP module. They can also be seen by using: -</p> +<H3><a name="Lisp_nn4">29.2.1 Additional Commandline Options </a></H3> -<div class="code"><pre> -swig -cffi -help -</pre></div> -<br/> <table summary="CFFI specific options"> <tr> @@ -119,12 +97,15 @@ swig -cffi -help </table> -<H3><a name="Lisp_nn5">27.2.2 Generating CFFI bindings</a></H3> +<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 @@ -155,7 +136,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 @@ -163,7 +147,9 @@ Corresponding to this we will write a simple interface file: </pre></div> +<p> The generated SWIG Code will be: +</p> <div class="targetlang"><pre> ;;;SWIG wrapper code starts here @@ -395,7 +381,7 @@ The feature <i>intern_function</i> ensures that all C names are </pre></div> -<H3><a name="Lisp_nn6">27.2.3 Generating CFFI bindings for C++ code</a></H3> +<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 @@ -430,8 +416,10 @@ Also, while parsing the C++ file and generating C wrapper code SWIG %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 @@ -478,8 +466,10 @@ namespace OpenDemo { %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) @@ -528,11 +518,13 @@ SWIG generates 3 files, the first one is a C wrap which we don't show, (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> @@ -568,7 +560,7 @@ 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">27.2.4 Inserting user code into generated files</a></H3> +<H3><a name="Lisp_nn7">29.2.4 Inserting user code into generated files</a></H3> <p> @@ -608,195 +600,5 @@ Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for </p> -<H2><a name="Lisp_nn8">27.3 CLISP</a></H2> - - -<p> -<a href="http://clisp.cons.org">CLISP</a> is a feature-loaded - implementation of common lisp which is portable across most of the - operating system environments and hardware. CLISP includes an - interpreter, a compiler, a debugger, CLOS, MOP, a foreign - language interface, i18n, regular expressions, a socket - interface, and more. An X11 interface is available through CLX, - Garnet and CLUE/CLIO. Command line editing is provided by - readline. CLISP runs Maxima, ACL2 and many other Common Lisp - packages. -</p> -<p> - To run the clisp module of SWIG requires very little effort, you - just need to execute: -</p> -<div class="code"><pre> -swig -clisp -module <i>module-name</i> <i>file-name</i> - -</pre></div> - -<p> - Because of the high level nature of the CLISP FFI, the bindings - generated by SWIG may not be absolutely correct, and you may need - to modify them. The good thing is that you don't need to complex - interface file for the CLISP module. The CLISP module tries to - produce code which is both human readable and easily modifyable. -</p> -<H3><a name="Lisp_nn9">27.3.1 Additional Commandline Options </a></H3> - - -<p> -The following table list the additional commandline options available for the CLISP module. They can also be seen by using: -</p> - -<div class="code"><pre> -swig -clisp -help -</pre></div> -<br/> -<table summary="CLISP specific options"> -<tr> -<th>CLISP specific options</th> -</tr> - -<tr> -<td>-extern-all</td> -<td>If this option is given then clisp definitions for all the functions<br/> -and global variables will be created otherwise only definitions for<br/> -externed functions and variables are created. -</td> -</tr> - -<tr> -<td>-generate-typedef</td> -<td>If this option is given then def-c-type will be used to generate<br/> -shortcuts according to the typedefs in the input. -</td> -</tr> - -</table> - -<H3><a name="Lisp_nn10">27.3.2 Details on CLISP bindings</a></H3> - - -<p> -As mentioned earlier the CLISP bindings generated by SWIG may need -some modifications. The clisp module creates a lisp file with -the same name as the module name. This -lisp file contains a 'defpackage' declaration, with the -package name same as the module name. This package uses the -'common-lisp' and 'ffi' packages. Also, package exports all -the functions, structures and variables for which an ffi -binding was generated.<br/> -After generating the defpackage statement, the clisp module also -sets the default language. - -<div class="targetlang"><pre> -(defpackage :test - (:use :common-lisp :ffi) - (:export - :make-bar - :bar-x - :bar-y - :bar-a - :bar-b - :bar-z - :bar-n - :pointer_func - :func123 - :make-cfunr - :lispsort_double - :test123)) - -(in-package :test) - -(default-foreign-language :stdc) -</pre></div> -<p> -The ffi wrappers for functions and variables are generated as shown - below. When functions have arguments of type "double * array", - SWIG doesn't knows whether it is an 'out' argument or it is - an array which will be passed, so SWIG plays it safe by - declaring it as an '(array (ffi:c-ptr DOUBLE-FLOAT))'. For - arguments of type "int **z[100]" where SWIG has more - information, i.e., it knows that 'z' is an array of pointers to - pointers of integers, SWIG defines it to be '(z (ffi:c-ptr - (ffi:c-array (ffi:c-ptr (ffi:c-ptr ffi:int)) 100)))' -</p> -<div class="code"><pre> -extern "C" { -int pointer_func(void (*ClosureFun)( void* _fun, void* _data, void* _evt ), int y); - -int func123(div_t * x, int **z[100], int y[][1000][10]); - -void lispsort_double (int n, double * array); - -void test123(float x , double y); - -} -</pre></div> -<div class="targetlang"><pre> -(ffi:def-call-out pointer_func - (:name "pointer_func") - (:arguments (ClosureFun (ffi:c-function (:arguments (arg0 (ffi:c-pointer NIL)) - (arg1 (ffi:c-pointer NIL)) - (arg2 (ffi:c-pointer NIL))) - (:return-type NIL))) - (y ffi:int)) - (:return-type ffi:int) - (:library +library-name+)) - -(ffi:def-call-out func123 - (:name "func123") - (:arguments (x (ffi:c-pointer div_t)) - (z (ffi:c-ptr (ffi:c-array (ffi:c-ptr (ffi:c-ptr ffi:int)) 100))) - (y (ffi:c-ptr (ffi:c-ptr (ffi:c-array ffi:int (1000 10)))))) - (:return-type ffi:int) - (:library +library-name+)) - - -(ffi:def-call-out lispsort_double - (:name "lispsort_double") - (:arguments (n ffi:int) - (array (ffi:c-ptr DOUBLE-FLOAT))) - (:return-type NIL) - (:library +library-name+)) - -(ffi:def-call-out test123 - (:name "test") - (:arguments (x SINGLE-FLOAT) - (y DOUBLE-FLOAT)) - (:return-type NIL) - (:library +library-name+)) - -</pre></div> - -<p> -The module also handles strutcures and #define constants as shown - below. SWIG automatically adds the constructors and accessors - created for the struct to the list of symbols exported by the - package. -</p> -<div class="code"><pre> -struct bar { - short x, y; - char a, b; - int *z[1000]; - struct bar * n; -}; - -#define max 1000 -</pre></div> -<div class="targetlang"><pre> -(ffi:def-c-struct bar - (x :type ffi:short) - (y :type ffi:short) - (a :type character) - (b :type character) - (z :type (ffi:c-array (ffi:c-ptr ffi:int) 1000)) - (n :type (ffi:c-pointer bar))) - -(defconstant max 1000) - -</pre></div> - -<H2><a name="Lisp_nn11">27.4 UFFI </a></H2> - - </body> </html> |