Next: , Previous: sb-aclrepl, Up: Contributed Modules


16.2 sb-grovel

The sb-grovel module helps in generation of foreign function interfaces. It aids in extracting constants' values from the C compiler and in generating SB-ALIEN structure and union types, see Defining Foreign Types.

The ASDF(http://www.cliki.net/ASDF) component type GROVEL-CONSTANTS-FILE has its PERFORM operation defined to write out a C source file, compile it, and run it. The output from this program is Lisp, which is then itself compiled and loaded.

sb-grovel is used in a few contributed modules, and it is currently compatible only to SBCL. However, if you want to use it, here are a few directions.

16.2.1 Using sb-grovel in your own ASDF system

  1. Create a Lisp package for the foreign constants/functions to go into.
  2. Make your system depend on the 'sb-grovel system.
  3. Create a grovel-constants data file - for an example, see example-constants.lisp in the contrib/sb-grovel/ directory in the SBCL source distribution.
  4. Add it as a component in your system. e.g.
              (eval-when (:compile-toplevel :load-toplevel :execute)
                (require :sb-grovel))
              
              (defpackage :example-package.system
                          (:use :cl :asdf :sb-grovel :sb-alien))
              
              (in-package :example-package.system)
              
              (defsystem example-system
                  :depends-on (sb-grovel)
                  :components
                  ((:module "sbcl"
                            :components
                            ((:file "defpackage")
                             (grovel-constants-file "example-constants"
                                                    :package :example-package)))))
    

    Make sure to specify the package you chose in step 1

  5. Build stuff.

16.2.2 Contents of a grovel-constants-file

The grovel-constants-file, typically named constants.lisp, comprises lisp expressions describing the foreign things that you want to grovel for. A constants.lisp file contains two sections:

There are two types of things that sb-grovel can sensibly extract from the C compiler: constant integers and structure layouts. It is also possible to define foreign functions in the constants.lisp file, but these definitions don't use any information from the C program; they expand directly to sb-alien:define-alien-routine (see The define-alien-routine Macro) forms.

Here's how to use the grovel clauses:

16.2.3 Programming with sb-grovel's structure types

Let us assume that you have a grovelled structure definition:

      (:structure mystruct ("struct my_structure"
                            (integer myint "int" "st_int")
                            (c-string mystring "char[]" "st_str")))

What can you do with it? Here's a short interface document:

16.2.3.1 Traps and Pitfalls

Basically, you can treat functions and data structure definitions that sb-grovel spits out as if they were alien routines and types. This has a few implications that might not be immediately obvious (especially if you have programmed in a previous version of sb-grovel that didn't use alien types):