guile18/doc/sources/libguile-tools.texi

   1 @node Tools to automate adding libraries
   2 @chapter Tools to automate adding libraries
   3
   4 You want to ...
   5
   6 The chapters @ref{Libguile -- high level interface} and @ref{Libguile --
   7 SCM interface} showed how to make C libraries available from Scheme.
   8 Here I will describe some automated tools that the Guile team has made
   9 available.  Some have been written especially for Guile (the Guile Magic
  10 Snarfer), and some are also in use with other languages (Python, Perl,
  11 ...)
  12
  13 @menu
  14 * By hand with gh_::
  15 * By hand with Guile Magic Snarfer::
  16 * Automatically using libtool::
  17 * Automatically using SWIG::
  18 @end menu
  19
  20 @node By hand with gh_
  21 @section By hand with gh_
  22
  23 @node By hand with Guile Magic Snarfer
  24 @section By hand with Guile Magic Snarfer
  25
  26 When writing C code for use with Guile, you typically define a set of C
  27 functions, and then make some of them visible to the Scheme world by
  28 calling the @code{scm_make_gsubr} function; a C functions published in
  29 this way is called a @dfn{subr}.  If you have many subrs to publish, it
  30 can sometimes be annoying to keep the list of calls to
  31 @code{scm_make_gsubr} in sync with the list of function definitions.
  32 Frequently, a programmer will define a new subr in C, recompile his
  33 application, and then discover that the Scheme interpreter cannot see
  34 the subr, because he forgot to call @code{scm_make_gsubr}.
  35
  36 Guile provides the @code{guile-snarf} command to manage this problem.
  37 Using this tool, you can keep all the information needed to define the
  38 subr alongside the function definition itself; @code{guile-snarf} will
  39 extract this information from your source code, and automatically
  40 generate a file of calls to @code{scm_make_gsubr} which you can
  41 @code{#include} into an initialization function.  (The command name
  42 comes from the verb ``to snarf'', here meaning ``to unceremoniously
  43 extract information from a somewhat unwilling source.'')
  44
  45 @menu
  46 * How guile-snarf works::       Using the @code{guile-snarf} command.
  47 * Macros guile-snarf recognizes::  How to mark up code for @code{guile-snarf}.
  48 @end menu
  49
  50 @node How guile-snarf works
  51 @subsection How @code{guile-snarf} works
  52
  53 For example, here is how you might define a new subr called
  54 @code{clear-image}, implemented by the C function @code{clear_image}:
  55
  56 @example
  57 @group
  58 #include <libguile.h>
  59
  60 @dots{}
  61
  62 SCM_PROC (s_clear_image, "clear-image", 1, 0, 0, clear_image);
  63
  64 SCM
  65 clear_image (SCM image_smob)
  66 @{
  67   @dots{}
  68 @}
  69
  70 @dots{}
  71
  72 void
  73 init_image_type ()
  74 @{
  75 #include "image-type.x"
  76 @}
  77 @end group
  78 @end example
  79
  80 The @code{SCM_PROC} declaration says that the C function
  81 @code{clear_image} implements a Scheme subr called @code{clear-image},
  82 which takes one required argument, no optional arguments, and no tail
  83 argument.  @code{SCM_PROC} also declares a static array of characters
  84 named @code{s_clear_image}, initialized to the string
  85 @code{"clear-image"}.  The body of @code{clear_image} may use the array
  86 in error messages, instead of writing out the literal string; this may
  87 save string space on some systems.
  88
  89 Assuming the text above lives in a file named @file{image-type.c}, you will
  90 need to execute the following command to compile this file:
  91 @example
  92 guile-snarf image-type.c > image-type.x
  93 @end example
  94 @noindent This scans @file{image-type.c} for @code{SCM_PROC}
  95 declarations, and sends the following output to the file
  96 @file{image-type.x}:
  97 @example
  98 scm_make_gsubr (s_clear_image, 1, 0, 0, clear_image);
  99 @end example
 100 When compiled normally, @code{SCM_PROC} is a macro which expands to a
 101 declaration of the @code{s_clear_image} string.
 102
 103 In other words, @code{guile-snarf} scans source code looking for uses of
 104 the @code{SCM_PROC} macro, and generates C code to define the
 105 appropriate subrs.  You need to provide all the same information you
 106 would if you were using @code{scm_make_gsubr} yourself, but you can
 107 place the information near the function definition itself, so it is less
 108 likely to become incorrect or out-of-date.
 109
 110 If you have many files that @code{guile-snarf} must process, you should
 111 consider using a rule like the following in your Makefile:
 112 @example
 113 .SUFFIXES: .x
 114 .c.x:
 115         ./guile-snarf $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) $< > $@
 116 @end example
 117 This tells make to run @code{guile-snarf} to produce each needed
 118 @file{.x} file from the corresponding @file{.c} file.
 119
 120 @code{guile-snarf} passes all its command-line arguments directly to the
 121 C preprocessor, which it uses to extract the information it needs from
 122 the source code. this means you can pass normal compilation flags to
 123 @code{guile-snarf} to define preprocessor symbols, add header file
 124 directories, and so on.
 125
 126
 127
 128 @node Macros guile-snarf recognizes
 129 @subsection Macros @code{guile-snarf} recognizes
 130
 131 Here are the macros you can use in your source code from which
 132 @code{guile-snarf} can construct initialization code:
 133
 134
 135 @defmac SCM_PROC (@var{namestr}, @var{name}, @var{req}, @var{opt}, @var{tail}, @var{c_func})
 136 Declare a new Scheme primitive function, or @dfn{subr}.  The new subr
 137 will be named @var{name} in Scheme code, and be implemented by the C
 138 function @var{c_func}.  The subr will take @var{req} required arguments
 139 and @var{opt} optional arguments.  If @var{tail} is non-zero, the
 140 function will accept any remaining arguments as a list.
 141
 142 Use this macro outside all function bodies, preferably above the
 143 definition of @var{c_func} itself.  When compiled, the @code{SCM_PROC}
 144 declaration will expand to a definition for the @var{namestr} array,
 145 initialized to @var{name}.  The @code{guile-snarf} command uses this
 146 declaration to automatically generate initialization code to create the
 147 subr and bind it in the top-level environment.  @xref{How guile-snarf
 148 works}, for more info.
 149
 150 @xref{Subrs}, for details on argument passing and how to write
 151 @var{c_func}.
 152 @end defmac
 153
 154
 155 @defmac SCM_GLOBAL (@var{var}, @var{scheme_name})
 156 Declare a global Scheme variable named @var{scheme_name}, and a static C
 157 variable named @var{var} to point to it.  The value of the Scheme
 158 variable lives in the @sc{cdr} of the cell @var{var} points to.
 159 Initialize the variable to @code{#f}.
 160
 161 Use this macro outside all function bodies.  When compiled, the
 162 @code{SCM_GLOBAL} macro will expand to a definition for the variable
 163 @var{var}, initialized to an innocuous value.  The @code{guile-snarf}
 164 command will use this declaration to automatically generate code to
 165 create a global variable named @var{scheme_name}, and store a pointer to
 166 its cell in @var{var}.
 167 @end defmac
 168
 169
 170 @defmac SCM_CONST_LONG (@var{var}, @var{scheme_name}, @var{value})
 171 Like @code{SCM_GLOBAL}, but initialize the variable to @var{value},
 172 which must be an integer.
 173 @end defmac
 174
 175
 176 @defmac SCM_SYMBOL (@var{var}, @var{name})
 177 Declare a C variable of type @code{SCM} named @var{var}, and initialize
 178 it to the Scheme symbol object whose name is @var{name}.
 179
 180 Use this macro outside all function bodies.  When compiled, the
 181 @code{SCM_SYMBOL} macro will expand to a definition for the variable
 182 @var{var}, initialized to an innocuous value.  The @code{guile-snarf}
 183 command will use this declaration to automatically generate code to
 184 create a symbol named @var{name}, and store it in @var{var}.
 185 @end defmac
 186
 187 @node Automatically using libtool
 188 @section Automatically using libtool
 189
 190 @node Automatically using SWIG
 191 @section Automatically using SWIG