SWIG and Chicken

# 24 SWIG and Chicken

- Preliminaries
  - Running SWIG in C mode
  - Running SWIG in C++ mode
- Code Generation
  - Naming Conventions
  - Modules and Prefixes
  - Constants and Variables
  - Functions
- TinyCLOS
- Compilation
- Linkage
  - Customized Interpreter
- Typemaps
- Pointers
- Unsupported features

This chapter describes SWIG's support of CHICKEN. CHICKEN is a Scheme-to-C compiler supporting most of the language features as defined in the Revised^5 Report on Scheme. Its main attributes are that it

1. generates portable C code
2. includes a customizable interpreter
3. links to C libraries with a simple Foreign Function Interface
4. supports full tail-recursion and first-class continuations

When confronted with a large C library, CHICKEN users can use SWIG to generate CHICKEN wrappers for the C library. However, the real advantages of using SWIG with CHICKEN are its support for C++ -- object-oriented code is difficult to wrap by hand in CHICKEN -- and its typed pointer representation, essential for C and C++ libraries involving structures or classes.

## 24.1 Preliminaries

CHICKEN support was introduced to SWIG in version 1.3.18. SWIG relies on some recent additions to CHICKEN, which are only present in releases of CHICKEN with version number greater than or equal to `1.0`.
CHICKEN can be downloaded from http://www.call-with-current-continuation.org/chicken.html You may want to look at any of the examples in Examples/chicken/ or Examples/GIFPlot/Chicken for the basic steps to run SWIG CHICKEN. We will generically refer to the wrapper as the generated files.

### 24.1.1 Running SWIG in C mode

To run SWIG CHICKEN in C mode, use the -chicken option.

>     % swig -chicken example.i

To allow the wrapper to take advantage of future CHICKEN code generation improvements, part of the wrapper is direct CHICKEN function calls (`example_wrap.c`) and part is CHICKEN Scheme (`example.scm`). The basic Scheme code must be compiled to C using your system's CHICKEN compiler.

>     % chicken example.scm -output-file oexample.c

So for the C mode of SWIG CHICKEN, `example_wrap.c` and `oexample.c` are the files that must be compiled to object files and linked into your project.

### 24.1.2 Running SWIG in C++ mode

To run SWIG CHICKEN in C++ mode, use the -chicken -c++ option.

>     % swig -chicken -c++ example.i

This will generate `example_wrap.cxx`, `example.scm`, `example-generic.scm` and `example-clos.scm`. The basic Scheme code must be compiled to C using your system's CHICKEN compiler.

>     % chicken example.scm -output-file oexample.c

So for the C++ mode of SWIG CHICKEN, `example_wrap.cxx` and `oexample.c` are the files that must be compiled to object files and linked into your project.

## 24.2 Code Generation

### 24.2.1 Naming Conventions

Given a C variable, function or constant declaration named `Foo_Bar_to_Foo_Baz`, the declaration will be available in CHICKEN as an identifier ending with `foo-bar->foo-baz`. That is, an underscore is converted to a dash, '_to_' is converted to an arro, and all characters are sent to lowercase.
Additionally, there is a mixed mode that can be specified with the `-mixed` option on the SWIG command line. In this mode, the above rules apply with the addition that changes in case are indications to SWIG CHICKEN to place a dash in the CHICKEN identifier. For example, a C declartaion named `someDeclaration_xyz` will be available as the CHICKEN identifier ending with `some-declaration-xyz`.
You may control what the CHICKEN identifier will be by using the `%rename` SWIG directive in the SWIG interface file.

### 24.2.2 Modules and Prefixes

SWIG CHICKEN does not use the standard CHICKEN module system (which has been deprecated); instead, it uses a prefix system. Specifying the module name as 'example' in SWIG CHICKEN can be done using either of:

- Placing `%module example` in the SWIG interface file.
- Using `-module example` on the SWIG command line.

CHICKEN will be able to access the module using the `(declare (uses modulename))` CHICKEN Scheme form.
Normally, for a C declaration `Foo_Bar` with a module name of 'example', the corresponding CHICKEN identifier will be `example:foo-bar`. The module name and a colon is prefixed to the CHICKEN identifier (following normal naming conventions).
You may explicitly override the prefix with the SWIG command line option `-prefix whateverprefix`, or you may remove the prefix with the option `-noprefix`.

### 24.2.3 Constants and Variables

Constants may be created using any of the four constructs in the interface file:

1. `#define MYCONSTANT1 ...`
2. `%constant int MYCONSTANT2 = ...`
3. `const int MYCONSTANT3 = ...`
4. `enum { MYCONSTANT4 = ... };`

In all cases, the constants may be accessed from with CHICKEN using the form `(myconstant1)`; that is, the constants may be accessed using the read-only parameter form.

Variables are accessed using the full parameter form. For example, to set the C variable "int my_variable;", use the Scheme form `(my-variable 2345)`. To get the C variable, use `(my-variable)`.

### 24.2.4 Functions

C functions declared in the SWIG interface file will have corresponding CHICKEN Scheme procedures. For example, the C function "int sqrt(double x);" will be available using the Scheme form `(sqrt 2345.0)`. A `void` return value will give C_SCHEME_UNDEFINED as a result.

A function may return more than one value by using the `OUTPUT` specifier (see Lib/chicken/typemaps.i). They will be returned as a Scheme list if there is more than one result (that is, a non-void return value and at least one argout parameter, or a void return value and at least two argout parameters).

## 24.3 TinyCLOS

The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as:

> Tiny CLOS is a Scheme implementation of a `kernelized' CLOS, with a metaobject protocol. The implementation is even simpler than the simple CLOS found in `The Art of the Metaobject Protocol,' weighing in at around 850 lines of code, including (some) comments and documentation.

Almost all good Scheme books describe how to use metaobjects and generic procedures to implement an object-oriented Scheme system. Please consult a Scheme book if you are unfamiliar with the concept.
CHICKEN has a modified version of TinyCLOS, which SWIG CHICKEN uses in C++ mode. SWIG CHICKEN generates a `xxx-generic.scm` and a `xxx-clos.scm` file, which contain TinyCLOS macros. When using these macros, you will need to `(include "xxx-generic")` all the generic macros your program needs, and then `(include "xxx-clos")` all the metaobject (class) macros your program needs.
SWIG CHICKEN will call the destructor for all TinyCLOS objects that are garbage-collected by CHICKEN. It also allows access to the underlying low-level Scheme procedures with (de)-marshaling of any TinyCLOS parameters. It is best to learn the TinyCLOS system by running the `Examples/chicken/class/` example.

## 24.4 Compilation

Please refer to CHICKEN - A practical and portable Scheme system - User's manual for detailed help on how to compile C code for use in a CHICKEN program. Briefly, to compile C code, be sure to add ``chicken-config -cflags`` or ``chicken-config -shared -cflags`` to your compiler options. Use the `-shared` option if you want to create a dynamically loadable module. You might also want to use the much simpler `csc` or `csc.bat`.

## 24.5 Linkage

Please refer to CHICKEN - A practical and portable Scheme system - User's manual for detailed help on how to link object files to create a CHICKEN Scheme program. Briefly, to link object files, be sure to add ``chicken-config -extra-libs -libs`` or ``chicken-config -shared -extra-libs -libs``to your linker options. Use the `-shared` option if you want to create a dynamically loadable module.

All the following examples assume that the module is named 'example' and the following occurs when run:

>     % chicken-config -home
>     CHICKEN_HOME=/usr/local/share/chicken

Substitute `/usr/local/share/chicken` as appropriate for your platform.

### 24.5.1 Customized Interpreter

We will assume your files are in a directory `/home/jonah/examples`. Make a file as follows:

    ;; precsi.scm
    (declare (unit precsi))
    (declare (uses example))

    ;; any other code you want run before the main interpreter is executed

Run SWIG on your interface file as usual, create the 2 wrapper object files, and then either

>     % cd /usr/local/share/chicken
>     % chicken /usr/local/share/chicken/src/csi.scm -optimize-level 3 -quiet \
>             -include-path /usr/local/share/chicken/src \
>             -prologue /usr/local/share/chicken/src/build.scm \
>             -prelude "(declare (uses posix precsi))" \
>             -output-file /home/jonah/examples/csi-example.c
>     % cd /home/jonah/examples
>     % chicken precsi.scm -optimize-level 3 --explicit-use \
>             -output-file precsi.c
>     % gcc precsi.c csi.c wrapper_object_files \
>             `chicken-config -libs` `chicken-config -extra-libs` -o csi-example

or

>     % extend-csi precsi -output-file csi-example

## 24.6 Typemaps

The Chicken module handles all types via typemaps. This information is read from `Lib/chicken/typemaps.i` and `Lib/chicken/chicken.swg`.
Two Chicken-specific typemaps are supported: `clos_in` and `clos_out`. They are for converting TinyCLOS to and from low-level CHICKEN SWIG. Here is a quick example:

>     /* Let "Shape" objects be converted back and forth from TinyCLOS into
>        low-level CHICKEN SWIG procedures */

>     %typemap(clos_in) Shape * = SIMPLE_CLOS_OBJECT *;
>     %typemap(clos_out) Shape * = SIMPLE_CLOS_OBJECT *;

The `SIMPLE_CLOS_OBJECT` will generally be all that is needed ... the definition of this is as follows:

>     /* TinyCLOS <--> Low-level CHICKEN */

>     %typemap("clos_in") SIMPLE_CLOS_OBJECT * "(slot-ref $input (quote this))"
>     %typemap("clos_out") SIMPLE_CLOS_OBJECT * "(make $class (quote this) $1)"

Now, in the example using "Shape" objects, all objects instantiated from Shape or any of its subclasses fully known to SWIG will have correct TinyCLOS representations based on `SIMPLE_CLOS_OBJECT`. SWIG "knows" the classes that are exposed in the SWIG interface file; it "fully knows" only those classes that are not forward declarations.
A real-world example of the "fully knows" problem is found in the VTK visualization library. All VTK classes are derived from vtkObject.

>        /* FILE: vtkObject.h */
>        class vtkObject {
>           // ...
>        };

>        /* FILE: vtkWindow.h */
>        #include "vtkObject.h"

>        class vtkWindow : public vtkObject {
>           // ...
>        };

>        /* FILE: vtkViewport.h */
>        #include "vtkViewport.h"

>        class vtkViewport : public vtkObject {
>           // ...
>        };

>        /* FILE: vtkRenderWindow.h */
>        #include "vtkWindow.h"

>        class vtkRenderer;
>        class vtkRenderWindow : public vtkWindow {
>           // ...
>           virtual void AddRenderer (vtkRenderer *rendererArg);
>           // ...
>        };

>        /* FILE: vtkRenderer.h */
>        #include "vtkViewport.h"

>        class vtkRenderWindow;
>        class vtkRenderer : public vtkViewport {
>           // ...
>           void SetRenderWindow(vtkRenderWindow *);
>           // ...
>        };

>        /* FILE: vtk.i; SWIG interface file */
>        %typemap(clos_in) vtkObject * = SIMPLE_CLOS_OBJECT *;
>        %typemap(clos_out) vtkObject * = SIMPLE_CLOS_OBJECT *;
>        %include "vtkObject.h"
>        %include "vtkWindow.h"
>        %include "vtkViewport.h"
>        %include "vtkRenderWindow.h"
>        %include "vtkRenderer.h"

After SWIG processes `vtkObject.h` (from the `%include "vtkObject.h"` line), SWIG will have the complete definition of the `vtkObject` class because `vtkObject` does not contain any references to any other classes. As it reads `vtkWindow.h` and `vtkViewport.h`, it will already have the definition of `vtkObject`, so it will not need a `clos_in` or `clos_out` typemap for the `vtkWindow` or `vtkViewport` subclasses of `vtkObject`. However, by the time SWIG gets to `%include "vtkRenderWindow.h"`, it will not have the definition for the `vtkRenderer` class, even though it is used by `vtkRenderWindow`. We therefore must put in `clos_in/clos_out` typemaps for `vtkRenderer`.

## 24.7 Pointers

For pointer types, SWIG uses CHICKEN tagged pointers. A tagged pointer is an ordinary CHICKEN pointer with an extra slot for an arbitrary Scheme object. With SWIG CHICKEN, this Scheme object is a reference to a type-info structure. So each pointer used as input or output from the SWIG-generated CHICKEN wrappers will have type information attached to it. This will let the wrappers correctly determine which method should be called according to the object type hierarchy exposed in the SWIG interface files.

To construct a Scheme object from a C pointer, the wrapper code calls the function `swig_new_pointer_obj()`, passing stack allocation space of size SWIG_ALLOCSZ_POINTER (see definition in Lib/chicken/chickenrun.swg and also `C_alloc()` in the CHICKEN documentation) and a pointer to a struct representing the pointer type.

To get the pointer represented by a CHICKEN tagged pointer, the wrapper code calls the function `swig_convert_ptr()`, passing a pointer to a struct representing the expected pointer type. If the Scheme object passed was not a tagged pointer representing a compatible pointer, a non-zero value is returned.

Warning: The Chicken typechecking code seems to be broken (Bug #782468), so that type errors may not be reported.

## 24.8 Unsupported features

- No exception handling.