GNU Info

(g-wrap.info)Overview

---

Next: Why Create a Wrapper Generator? Prev: Caveats Up: Introduction

---

Enter node , (file) or (file)node

Overview
========

Given a definition of the types and prototypes for a given C interface,
G-wrap will automatically generate the C code that provides access to
that interface and its types from the Scheme level.

To use g-wrap, you must make sure it knows how to handle all of the C
types that the functions you will be calling take as arguments and
return as values, and you must also tell g-wrap about the C prototypes
of these functions.  Since g-wrap already knows about quite a few of the
common C types you may not need to add any type specifications for many
straightforward interfaces.

G-wrap is implemented as a Guile module, and so its interface is a
programmatic one.  You tell g-wrap about your functions and types, and
ask it to generate wrappers for you by calling the functions exported
from the g-wrap module.

As a simple example, if you wanted to wrap a C API that contained only
one function with a prototype like this

       int frob(int x, double y);

a complete g-wrap specification would look like this:

       (let ((mod (gw:new-module "my-g-wrap-module")))
         (gw:module-depends-on mod "gw-runtime")
         (gw:wrap-function
          mod
          'frob
          '<gw:int> "frob" '((<gw:int> x) (<gw:double> y))
          "Return the result of frobbing x and y.")

Once g-wrap has seen this specification, the code for the wrappers can
be generated with this call:

       (gw:generate-module "my-g-wrap-module")

This will produce C code that when either compiled into a static Guile
executable, or built as a shared library and dynamically loaded from
Guile will define a Scheme function named `frob' which you can call as
expected:

       (frob 4 2.3)

When it comes to defining how C types should be handled, g-wrap is very
flexible.  G-wrap provides a fairly generic underlying infrastructure
which can then be customized for particular purposes by teaching it how
to generate code for a given type or wrapper module.  You can take
explicit control over what code is generated in the wrapper module(1)
to handle arguments and return values of a given type (both for their
initialization and cleanup), what code is generated to handle the
wrapper module's global initialization, and what code is generated to
provide global declarations.  G-wrap can also spit out a fully
functional, dynamically-loadable Guile module if you like (so
technically, (use-modules (g-wrapped ncurses)) is now possible, and
(with a minor tweak to re-enable some code) g-wrap can generate html
docs for the wrapper interface.

At the lowest level, there is a "most generic wrapper type" from which
all other wrapper types are derived, and g-wrap comes with a few of
these more specialized wrapper types pre-defined.  This set should cover
most of the common cases, but you can extend this set if needed.  The
wrapper types currently available by default include:

`normal (native)'
     a wrapper type to handle C types which can be represented most
     appropriately on the Scheme side by a conversion directly to a
     native Scheme type.

`non-native'
     a wrapper type to handle "non-native" objects, that is, C types
     which can not, or should not be represented on the Scheme side by
     a conversion to a native Scheme representation, or types for which
     preserving the C-side pointer equivalency is important.  Instances
     of this wrapper type are represented at runtime by a Guile SMOB
     containing the actual C pointer.

`enumeration'
     a wrapper type to handle C enumerations which automatically grabs
     the right C-side values at runtime.

Further, g-wrap now has a first pass at an implementation that should
allow you to define types in one wrapper module that can then be used by
other wrapper modules.  So as an example, you should be able to define a
glib wrapper module that provides wrapper specifications for GList*'s
that other wrapper modules can then import and use in their own wrapper
function prototypes for argument and result types.  The goal is for this
to allow different wrapper modules to be able to safely exchange data
among their wrapped functions when they share common wrapped types.

As mentioned, g-wrap itself is now implemented as a purely Scheme-code
Guile module, and no longer uses globals.  This means that you you can
now wrap functions for multiple modules on the fly from any invocation
of guile.

---------- Footnotes ----------

(1) The term "wrapper module" will always be used to indicate the
collection of C code that is generated as the wrapper for a given C
API.  It may or may not have any correlation to a Guile module.  When a
Guile module is meant, the term Guile module will be used explicitly.