Improve docs on symbols.

[bpt/guile.git] / doc / sources / libguile-tools.texi

@node Tools to automate adding libraries
@chapter Tools to automate adding libraries

You want to ...

The chapters @ref{Libguile -- high level interface} and @ref{Libguile --
SCM interface} showed how to make C libraries available from Scheme.
Here I will describe some automated tools that the Guile team has made
available.  Some have been written especially for Guile (the Guile Magic
Snarfer), and some are also in use with other languages (Python, Perl,
...)

@menu
* By hand with gh_::            
* By hand with Guile Magic Snarfer::  
* Automatically using libtool::  
* Automatically using SWIG::    
@end menu

@node By hand with gh_
@section By hand with gh_

@node By hand with Guile Magic Snarfer
@section By hand with Guile Magic Snarfer

When writing C code for use with Guile, you typically define a set of C
functions, and then make some of them visible to the Scheme world by
calling the @code{scm_make_gsubr} function; a C functions published in
this way is called a @dfn{subr}.  If you have many subrs to publish, it
can sometimes be annoying to keep the list of calls to
@code{scm_make_gsubr} in sync with the list of function definitions.
Frequently, a programmer will define a new subr in C, recompile his
application, and then discover that the Scheme interpreter cannot see
the subr, because he forgot to call @code{scm_make_gsubr}.

Guile provides the @code{guile-snarf} command to manage this problem.
Using this tool, you can keep all the information needed to define the
subr alongside the function definition itself; @code{guile-snarf} will
extract this information from your source code, and automatically
generate a file of calls to @code{scm_make_gsubr} which you can
@code{#include} into an initialization function.  (The command name
comes from the verb ``to snarf'', here meaning ``to unceremoniously
extract information from a somewhat unwilling source.'')

@menu
* How guile-snarf works::       Using the @code{guile-snarf} command.
* Macros guile-snarf recognizes::  How to mark up code for @code{guile-snarf}.
@end menu

@node How guile-snarf works
@subsection How @code{guile-snarf} works

For example, here is how you might define a new subr called
@code{clear-image}, implemented by the C function @code{clear_image}:

@example
@group
#include <libguile.h>

@dots{}

SCM_PROC (s_clear_image, "clear-image", 1, 0, 0, clear_image);

SCM
clear_image (SCM image_smob)
@{
  @dots{}
@}

@dots{}

void
init_image_type ()
@{
#include "image-type.x"
@}
@end group
@end example

The @code{SCM_PROC} declaration says that the C function
@code{clear_image} implements a Scheme subr called @code{clear-image},
which takes one required argument, no optional arguments, and no tail
argument.  @code{SCM_PROC} also declares a static array of characters
named @code{s_clear_image}, initialized to the string
@code{"clear-image"}.  The body of @code{clear_image} may use the array
in error messages, instead of writing out the literal string; this may
save string space on some systems.

Assuming the text above lives in a file named @file{image-type.c}, you will
need to execute the following command to compile this file:
@example
guile-snarf image-type.c > image-type.x
@end example
@noindent This scans @file{image-type.c} for @code{SCM_PROC}
declarations, and sends the following output to the file
@file{image-type.x}:
@example
scm_make_gsubr (s_clear_image, 1, 0, 0, clear_image);
@end example
When compiled normally, @code{SCM_PROC} is a macro which expands to a
declaration of the @code{s_clear_image} string.

In other words, @code{guile-snarf} scans source code looking for uses of
the @code{SCM_PROC} macro, and generates C code to define the
appropriate subrs.  You need to provide all the same information you
would if you were using @code{scm_make_gsubr} yourself, but you can
place the information near the function definition itself, so it is less
likely to become incorrect or out-of-date.

If you have many files that @code{guile-snarf} must process, you should
consider using a rule like the following in your Makefile:
@example
.SUFFIXES: .x
.c.x:
	./guile-snarf $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) $< > $@
@end example
This tells make to run @code{guile-snarf} to produce each needed
@file{.x} file from the corresponding @file{.c} file.

@code{guile-snarf} passes all its command-line arguments directly to the
C preprocessor, which it uses to extract the information it needs from
the source code. this means you can pass normal compilation flags to
@code{guile-snarf} to define preprocessor symbols, add header file
directories, and so on.



@node Macros guile-snarf recognizes
@subsection Macros @code{guile-snarf} recognizes

Here are the macros you can use in your source code from which
@code{guile-snarf} can construct initialization code:


@defmac SCM_PROC (@var{namestr}, @var{name}, @var{req}, @var{opt}, @var{tail}, @var{c_func})
Declare a new Scheme primitive function, or @dfn{subr}.  The new subr
will be named @var{name} in Scheme code, and be implemented by the C
function @var{c_func}.  The subr will take @var{req} required arguments
and @var{opt} optional arguments.  If @var{tail} is non-zero, the
function will accept any remaining arguments as a list.

Use this macro outside all function bodies, preferably above the
definition of @var{c_func} itself.  When compiled, the @code{SCM_PROC}
declaration will expand to a definition for the @var{namestr} array,
initialized to @var{name}.  The @code{guile-snarf} command uses this
declaration to automatically generate initialization code to create the
subr and bind it in the top-level environment.  @xref{How guile-snarf
works}, for more info.

@xref{Subrs}, for details on argument passing and how to write
@var{c_func}.
@end defmac


@defmac SCM_GLOBAL (@var{var}, @var{scheme_name})
Declare a global Scheme variable named @var{scheme_name}, and a static C
variable named @var{var} to point to it.  The value of the Scheme
variable lives in the @sc{cdr} of the cell @var{var} points to.
Initialize the variable to @code{#f}.

Use this macro outside all function bodies.  When compiled, the
@code{SCM_GLOBAL} macro will expand to a definition for the variable
@var{var}, initialized to an innocuous value.  The @code{guile-snarf}
command will use this declaration to automatically generate code to
create a global variable named @var{scheme_name}, and store a pointer to
its cell in @var{var}.
@end defmac


@defmac SCM_CONST_LONG (@var{var}, @var{scheme_name}, @var{value})
Like @code{SCM_GLOBAL}, but initialize the variable to @var{value},
which must be an integer.
@end defmac


@defmac SCM_SYMBOL (@var{var}, @var{name})
Declare a C variable of type @code{SCM} named @var{var}, and initialize
it to the Scheme symbol object whose name is @var{name}.

Use this macro outside all function bodies.  When compiled, the
@code{SCM_SYMBOL} macro will expand to a definition for the variable
@var{var}, initialized to an innocuous value.  The @code{guile-snarf}
command will use this declaration to automatically generate code to
create a symbol named @var{name}, and store it in @var{var}.
@end defmac

@node Automatically using libtool
@section Automatically using libtool

@node Automatically using SWIG
@section Automatically using SWIG