0.8.13.60:
[sbcl.git] / contrib / sb-grovel / sb-grovel.texinfo
1 @node sb-grovel
2 @section sb-grovel
3 @cindex Foreign Function Interface, generation
4
5 The @code{sb-grovel} module helps in generation of foreign function
6 interfaces. It aids in extracting constants' values from the C
7 compiler and in generating SB-ALIEN structure and union types,
8 @pxref{Defining Foreign Types}.
9
10 The ASDF(@uref{http://www.cliki.net/ASDF}) component type
11 GROVEL-CONSTANTS-FILE has its PERFORM
12 @c @xref for PERFORM when asdf manual is included?
13 operation defined to write out a C source file, compile it, and run
14 it.  The output from this program is Lisp, which is then itself
15 compiled and loaded.
16
17 sb-grovel is used in a few contributed modules, and it is currently
18 compatible only to SBCL. However, if you want to use it, here are a
19 few directions.
20
21 @subsection Using sb-grovel in your own ASDF system
22
23 @enumerate
24
25 @item
26 Create a Lisp package for the foreign constants/functions to go into.
27
28 @item
29 Make your system depend on the 'sb-grovel system.
30
31 @item
32 Create a grovel-constants data file - for an example, see
33 example-constants.lisp in the contrib/sb-grovel/ directory in the SBCL
34 source distribution.
35
36 @item
37 Add it as a component in your system. e.g.
38
39 @lisp
40 (eval-when (:compile-toplevel :load-toplevel :execute)
41   (require :sb-grovel))
42
43 (defpackage :example-package.system
44             (:use :cl :asdf :sb-grovel :sb-alien))
45
46 (in-package :example-package.system)
47             
48 (defsystem example-system
49     :depends-on (sb-grovel)
50     :components
51     ((:module "sbcl"
52               :components
53               ((:file "defpackage")
54                (grovel-constants-file "example-constants"
55                                       :package :example-package)))))
56 @end lisp
57
58 Make sure to specify the package you chose in step 1
59
60 @item
61 Build stuff.
62
63 @end enumerate
64
65 @subsection Contents of a grovel-constants-file
66
67 The grovel-constants-file, typically named @code{constants.lisp},
68 comprises lisp expressions describing the foreign things that you want
69 to grovel for. A @code{constants.lisp} file contains two sections:
70
71 @itemize
72 @item
73 a list of headers to include in the C program, for example:
74 @lisp
75 ("sys/types.h" "sys/socket.h" "sys/stat.h" "unistd.h" "sys/un.h"
76  "netinet/in.h" "netinet/in_systm.h" "netinet/ip.h" "net/if.h"
77  "netdb.h" "errno.h" "netinet/tcp.h" "fcntl.h" "signal.h" )
78 @end lisp
79
80 @item
81 A list of sb-grovel clauses describing the things you want to grovel
82 from the C compiler, for example:
83 @lisp
84 ((:integer af-local
85            #+(or sunos solaris) "AF_UNIX"
86            #-(or sunos solaris) "AF_LOCAL"
87            "Local to host (pipes and file-domain).")
88  (:structure stat ("struct stat"
89                    (integer dev "dev_t" "st_dev")
90                    (integer atime "time_t" "st_atime")))
91  (:function getpid ("getpid" int )))
92 @end lisp
93 @end itemize
94
95 There are two types of things that sb-grovel can sensibly extract from
96 the C compiler: constant integers and structure layouts. It is also
97 possible to define foreign functions in the constants.lisp file, but
98 these definitions don't use any information from the C program; they
99 expand directly to @code{sb-alien:define-alien-routine}
100 (@pxref{The define-alien-routine Macro}) forms.
101
102 Here's how to use the grovel clauses:
103
104 @itemize
105 @item
106 @code{:integer} - constant expressions in C. Used in this form:
107 @lisp
108  (:integer lisp-variable-name "C expression" &optional doc export)
109 @end lisp
110
111 @code{"C expression"} will be typically be the name of a constant. But
112 other forms are possible.
113
114 @item
115 @code{:structure} - alien structure definitions look like this:
116 @lisp
117  (:structure lisp-struct-name ("struct c_structure"
118                                (type-designator lisp-element-name
119                                 "c_element_type" "c_element_name"
120                                 :distrust-length nil)
121                                ; ...
122                                ))
123 @end lisp
124
125 @code{type-designator} is a reference to a type whose size (and type
126 constraints) will be groveled for. sb-grovel accepts a form of type
127 designator that doesn't quite conform to either lisp nor sb-alien's
128 type specifiers. Here's a list of type designators that sb-grovel
129 currently accepts:
130 @itemize
131 @item
132 @code{integer} - a C integral type; sb-grovel will infer the exact
133 type from size information extracted from the C program. All common C
134 integer types can be grovelled for with this type designator, but it
135 is not possible to grovel for bit fields yet.
136
137 @item
138 @code{(unsigned n)} - an unsigned integer variable that is @code{n}
139 bytes long. No size information from the C program will be used.
140 @item
141 @code{(signed n)} - an signed integer variable that is @code{n} bytes
142 long. No size information from the C program will be used.
143
144 @item
145 @code{c-string} - an array of @code{char} in the structure. sb-grovel
146 will use the array's length from the C program, unless you pass it the
147 @code{:distrust-length} keyword argument with non-@code{nil} value
148 (this might be required for structures such as solaris's @code{struct
149 dirent}).
150
151 @item
152 @code{c-string-pointer} - a pointer to a C string, corresponding to
153 the @code{sb-alien:c-string} type (@pxref{Foreign Type Specifiers}).
154 @item
155 @code{(array alien-type)} - An array of the previously-declared alien
156 type. The array's size will be determined from the output of the C
157 program and the alien type's size.
158 @item
159 @code{(array alien-type n)} - An array of the previously-declared alien
160 type. The array's size will be assumed as being @code{n}.
161 @end itemize
162
163
164 Note that @code{c-string} and @code{c-string-pointer} do not have the
165 same meaning. If you declare that an element is of type
166 @code{c-string}, it will be treated as if the string is a part of the
167 structure, whereas if you declare that the element is of type
168 @code{c-string-pointer}, a @emph{pointer to a string} will be the
169 structure member.
170
171 @item
172 @code{:function} - alien function definitions are similar to
173 @code{define-alien-routine} definitions, because they expand to such
174 forms when the lisp program is loaded. @xref{Foreign Function Calls}
175
176 @lisp
177 (:function lisp-function-name ("alien_function_name" alien-return-type
178                                                      (argument alien-type)
179                                                      (argument2 alien-type)))
180 @end lisp
181 @end itemize
182
183
184 @subsection Programming with sb-grovel's structure types
185
186 Let us assume that you have a grovelled structure definition:
187 @lisp
188  (:structure mystruct ("struct my_structure"
189                        (integer myint "int" "st_int")
190                        (c-string mystring "char[]" "st_str")))
191 @end lisp
192
193 What can you do with it? Here's a short interface document:
194
195 @itemize
196 @item
197 Creating and destroying objects:
198 @itemize
199 @item
200 Function @code{(allocate-mystruct)} - allocates an object of type @code{mystruct}and
201 returns a system area pointer to it.
202 @item
203 Function @code{(free-mystruct var)} - frees the alien object pointed to by
204 @var{var}.
205 @item
206 Macro @code{(with-mystruct var ((member init) [...]) &body body)} -
207 allocates an object of type @code{mystruct} that is valid in
208 @var{body}. If @var{body} terminates or control unwinds out of
209 @var{body}, the object pointed to by @var{var} will be deallocated.
210 @end itemize
211
212 @item
213 Accessing structure members:
214 @itemize
215 @item
216 @code{(mystruct-myint var)} and @code{(mystruct-mystring var)} return
217 the value of the respective fields in @code{mystruct}.
218 @item
219 @code{(setf (mystruct-myint var) new-val)} and
220 @code{(setf (mystruct-mystring var) new-val)} sets the value of the respective
221 structure member to the value of @var{new-val}. Notice that in
222 @code{(setf (mystruct-mystring var) new-val)}'s case, new-val is a lisp
223 string.
224 @end itemize
225 @end itemize
226
227 @subsubsection Traps and Pitfalls
228 Basically, you can treat functions and data structure definitions that
229 sb-grovel spits out as if they were alien routines and types. This has
230 a few implications that might not be immediately obvious (especially
231 if you have programmed in a previous version of sb-grovel that didn't
232 use alien types):
233
234 @itemize
235 @item
236 You must take care of grovel-allocated structures yourself. They are
237 alien types, so the garbage collector will not collect them when you
238 drop the last reference.
239
240 @item
241 If you use the @code{with-mystruct} macro, be sure that no references
242 to the variable thus allocated leaks out. It will be deallocated when
243 the block exits.
244 @end itemize