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