* C Stub Generator for Scheme                           -*- outline -*-

This is the Stubber, a generator of C stubs for Scheme, whose purpose
is to enable Scheme programmers to describe to Scheme how C programmers
would invoke C libraries, so that they can be invoked from Scheme.

### WARNING ###

This is woefully incomplete and currently runs only in Scheme48 1.3.
If you find a public copy of this, it is strictly for the purposes of
discussion and entertainment only.

Porting this to other versions of Scheme48 should not be not hard.
Porting this to other Scheme systems is non-trivial, but in theory
should not require changing any programs that use the stubber: that is,
the stubber language is portable, even if the implementation is not.

There is a collection of notes and the beginning of a manual in the
`doc/' subdirectory.  The Scheme source code is located in `scheme/'
and the supporting C source code in `c/'.  There are examples of the
stubber's use in the `examples/' subdirectory.

The files named *-syntax.scm in the `scheme/' subdirectory are
unbelievably messy.  Don't look at them unless you believe you must.  I
will not be held responsible for any psychological distress caused by
looking at them.

Quick synopsis of how the stubber works:  You write a program using a
collection of hairy macros such as DEFINE-C, starting with BEGIN-C-STUB
and ending with END-C-STUB.  Expanding these macros causes a C source
file to be generated containing all the necessary stub code.  Expanding
the END-C-STUB macro causes this C source file to be compiled and
linked into a dynamically loadable library, which is loaded by the
Scheme code to which END-C-STUB expands.  Macros such as DEFINE-C
expand to Scheme code defining procedures that call the C stubs.

** How to use it

1. Create subdirectories `src/', `obj/', and `lib/' of the stubber
   directory.  These will be used to hold the source code, object code,
   and library code for any stubs generated.  (Yes, this is nonsense,
   but it is expedient nonsense.)

2. Compile c/s48-stubber.o with an incantation such as this:

     gcc -g -Wall -I/usr/local/include/scheme48-1.3 -c c/s48-stubber.c
       -o c/s48-stubber.o

3. Fix the compiler and linker flags in scheme/s48-codegen.scm as
   appropriate for your system.  Currently it is set up for Mac OS X
   10.5.  (Yes, this, too, is nonsense.)

4. Make sure that the subdirectory `external/' is populated.

5. Load the stubber into Scheme48 by typing the following at the
   command processor:

     ,exec ,load /path/to/stubber/scheme/s48-make.scm
     ,exec (load-stubber-configuration "/path/to/stubber/")

6. Emulate what you find in the `examples/' subdirectory, probably by
   starting from `examples/s48-packages.scm'.  Or try out something
   already there, such as

     > ,config ,load examples/s48-interfaces.scm
     > ,config ,load examples/s48-packages.scm
     > ,open bsd-sockets bsd-socket-addresses   ;This takes some time.
     > (define the-socket
         (create-socket (socket-domain internet)
                        (socket-type stream)
                        default-socket-protocol))
     ; no values returned
     > the-socket
     #{File-descriptor 4}
     > (socket.type the-socket)
     #{Socket-type stream}
     > (socket.address the-socket)
     #{Internet-socket-address}
     > ,open unix-file-descriptors
     > (close-file-descriptor the-socket)
     ; no values returned
     > the-socket
     #{Closed-file-descriptor}

** Debugging information in Scheme48

Loading the stubber (specifically, LOAD-STUBBER-CONFIGURATION from
scheme/s48-make.scm) will make Scheme48 cease to record the source of
code it later compiles for debugging purposes.  This is because the way
that the stubber works would create enormous source records that
quickly exhaust Scheme48's memory.  If you want to re-enable recording
of source, type

,keep source

but be careful to disable it with

,flush source

any time you load code that uses the stubber.

** Copying

Copyright (c) 2009, Taylor R. Campbell.

Verbatim copying and distribution of this entire article are permitted
worldwide, without royalty, in any medium, provided this notice, and
the copyright notice, are preserved.