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{:enum}
 116 @lisp
 117  (:enum lisp-type-name ((lisp-enumerated-name c-enumerated-name) ...)))
 118 @end lisp
 119
 120 An @code{sb-alien:enum} type with name @code{lisp-type-name} will be defined.
 121 The symbols are the @code{lisp-enumerated-name}s, and the values
 122 are grovelled from the @code{c-enumerated-name}s.
 123
 124 @item
 125 @code{:structure} - alien structure definitions look like this:
 126 @lisp
 127  (:structure lisp-struct-name ("struct c_structure"
 128                                (type-designator lisp-element-name
 129                                 "c_element_type" "c_element_name"
 130                                 :distrust-length nil)
 131                                ; ...
 132                                ))
 133 @end lisp
 134
 135 @code{type-designator} is a reference to a type whose size (and type
 136 constraints) will be groveled for. sb-grovel accepts a form of type
 137 designator that doesn't quite conform to either lisp nor sb-alien's
 138 type specifiers. Here's a list of type designators that sb-grovel
 139 currently accepts:
 140 @itemize
 141 @item
 142 @code{integer} - a C integral type; sb-grovel will infer the exact
 143 type from size information extracted from the C program. All common C
 144 integer types can be grovelled for with this type designator, but it
 145 is not possible to grovel for bit fields yet.
 146
 147 @item
 148 @code{(unsigned n)} - an unsigned integer variable that is @code{n}
 149 bytes long. No size information from the C program will be used.
 150 @item
 151 @code{(signed n)} - an signed integer variable that is @code{n} bytes
 152 long. No size information from the C program will be used.
 153
 154 @item
 155 @code{c-string} - an array of @code{char} in the structure. sb-grovel
 156 will use the array's length from the C program, unless you pass it the
 157 @code{:distrust-length} keyword argument with non-@code{nil} value
 158 (this might be required for structures such as solaris's @code{struct
 159 dirent}).
 160
 161 @item
 162 @code{c-string-pointer} - a pointer to a C string, corresponding to
 163 the @code{sb-alien:c-string} type (@pxref{Foreign Type Specifiers}).
 164 @item
 165 @code{(array alien-type)} - An array of the previously-declared alien
 166 type. The array's size will be determined from the output of the C
 167 program and the alien type's size.
 168 @item
 169 @code{(array alien-type n)} - An array of the previously-declared alien
 170 type. The array's size will be assumed as being @code{n}.
 171 @end itemize
 172
 173
 174 Note that @code{c-string} and @code{c-string-pointer} do not have the
 175 same meaning. If you declare that an element is of type
 176 @code{c-string}, it will be treated as if the string is a part of the
 177 structure, whereas if you declare that the element is of type
 178 @code{c-string-pointer}, a @emph{pointer to a string} will be the
 179 structure member.
 180
 181 @item
 182 @code{:function} - alien function definitions are similar to
 183 @code{define-alien-routine} definitions, because they expand to such
 184 forms when the lisp program is loaded. @xref{Foreign Function Calls}.
 185
 186 @lisp
 187 (:function lisp-function-name ("alien_function_name" alien-return-type
 188                                                      (argument alien-type)
 189                                                      (argument2 alien-type)))
 190 @end lisp
 191 @end itemize
 192
 193
 194 @subsection Programming with sb-grovel's structure types
 195
 196 Let us assume that you have a grovelled structure definition:
 197 @lisp
 198  (:structure mystruct ("struct my_structure"
 199                        (integer myint "int" "st_int")
 200                        (c-string mystring "char[]" "st_str")))
 201 @end lisp
 202
 203 What can you do with it? Here's a short interface document:
 204
 205 @itemize
 206 @item
 207 Creating and destroying objects:
 208 @itemize
 209 @item
 210 Function @code{(allocate-mystruct)} - allocates an object of type @code{mystruct}and
 211 returns a system area pointer to it.
 212 @item
 213 Function @code{(free-mystruct var)} - frees the alien object pointed to by
 214 @var{var}.
 215 @item
 216 Macro @code{(with-mystruct var ((member init) [...]) &body body)} -
 217 allocates an object of type @code{mystruct} that is valid in
 218 @var{body}. If @var{body} terminates or control unwinds out of
 219 @var{body}, the object pointed to by @var{var} will be deallocated.
 220 @end itemize
 221
 222 @item
 223 Accessing structure members:
 224 @itemize
 225 @item
 226 @code{(mystruct-myint var)} and @code{(mystruct-mystring var)} return
 227 the value of the respective fields in @code{mystruct}.
 228 @item
 229 @code{(setf (mystruct-myint var) new-val)} and
 230 @code{(setf (mystruct-mystring var) new-val)} sets the value of the respective
 231 structure member to the value of @var{new-val}. Notice that in
 232 @code{(setf (mystruct-mystring var) new-val)}'s case, new-val is a lisp
 233 string.
 234 @end itemize
 235 @end itemize
 236
 237 @subsubsection Traps and Pitfalls
 238 Basically, you can treat functions and data structure definitions that
 239 sb-grovel spits out as if they were alien routines and types. This has
 240 a few implications that might not be immediately obvious (especially
 241 if you have programmed in a previous version of sb-grovel that didn't
 242 use alien types):
 243
 244 @itemize
 245 @item
 246 You must take care of grovel-allocated structures yourself. They are
 247 alien types, so the garbage collector will not collect them when you
 248 drop the last reference.
 249
 250 @item
 251 If you use the @code{with-mystruct} macro, be sure that no references
 252 to the variable thus allocated leaks out. It will be deallocated when
 253 the block exits.
 254 @end itemize