guile18/doc/ref/libguile-snarf.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @node Function Snarfing
   8 @section Function Snarfing
   9
  10 When writing C code for use with Guile, you typically define a set of
  11 C functions, and then make some of them visible to the Scheme world by
  12 calling @code{scm_c_define_gsubr} or related functions.  If you have
  13 many functions to publish, it can sometimes be annoying to keep the
  14 list of calls to @code{scm_c_define_gsubr} in sync with the list of
  15 function definitions.
  16
  17 Guile provides the @code{guile-snarf} program to manage this problem.
  18 Using this tool, you can keep all the information needed to define the
  19 function alongside the function definition itself; @code{guile-snarf}
  20 will extract this information from your source code, and automatically
  21 generate a file of calls to @code{scm_c_define_gsubr} which you can
  22 @code{#include} into an initialization function.
  23
  24 The snarfing mechanism works for many kind of initialiation actions,
  25 not just for collecting calls to @code{scm_c_define_gsubr}.  For a
  26 full list of what can be done, @xref{Snarfing Macros}.
  27
  28 @cindex guile-snarf invocation
  29 @cindex guile-snarf example
  30
  31 The @code{guile-snarf} program is invoked like this:
  32
  33 @smallexample
  34 guile-snarf [-o @var{outfile}] [@var{cpp-args} ...]
  35 @end smallexample
  36
  37 This command will extract initialization actions to @var{outfile}.
  38 When no @var{outfile} has been specified or when @var{outfile} is
  39 @code{-}, standard output will be used.  The C preprocessor is called
  40 with @var{cpp-args} (which usually include an input file) and the
  41 output is filtered to extract the initialization actions.
  42
  43 If there are errors during processing, @var{outfile} is deleted and the
  44 program exits with non-zero status.
  45
  46 During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is
  47 defined.  You could use this to avoid including snarfer output files
  48 that don't yet exist by writing code like this:
  49
  50 @smallexample
  51 #ifndef SCM_MAGIC_SNARFER
  52 #include "foo.x"
  53 #endif
  54 @end smallexample
  55
  56 Here is how you might define the Scheme function @code{clear-image},
  57 implemented by the C function @code{clear_image}:
  58
  59 @example
  60 @group
  61 #include <libguile.h>
  62
  63 SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
  64             (SCM image_smob),
  65             "Clear the image.")
  66 @{
  67   /* C code to clear the image in @code{image_smob}... */
  68 @}
  69
  70 void
  71 init_image_type ()
  72 @{
  73 #include "image-type.x"
  74 @}
  75 @end group
  76 @end example
  77
  78 The @code{SCM_DEFINE} declaration says that the C function
  79 @code{clear_image} implements a Scheme function called
  80 @code{clear-image}, which takes one required argument (of type
  81 @code{SCM} and named @code{image_smob}), no optional arguments, and no
  82 rest argument.  The string @code{"Clear the image."} provides a short
  83 help text for the function, it is called a @dfn{docstring}.
  84
  85 For historical reasons, the @code{SCM_DEFINE} macro also defines a
  86 static array of characters named @code{s_clear_image}, initialized to
  87 the string "clear-image".  You shouldn't use this array, but you might
  88 need to be aware that it exists.
  89
  90 Assuming the text above lives in a file named @file{image-type.c}, you
  91 will need to execute the following command to prepare this file for
  92 compilation:
  93
  94 @example
  95 guile-snarf -o image-type.x image-type.c
  96 @end example
  97
  98 This scans @file{image-type.c} for @code{SCM_DEFINE}
  99 declarations, and writes to @file{image-type.x} the output:
 100
 101 @example
 102 scm_c_define_gsubr ("clear-image", 1, 0, 0, (SCM (*)() ) clear_image);
 103 @end example
 104
 105 When compiled normally, @code{SCM_DEFINE} is a macro which expands to
 106 the function header for @code{clear_image}.
 107
 108 Note that the output file name matches the @code{#include} from the
 109 input file.  Also, you still need to provide all the same information
 110 you would if you were using @code{scm_c_define_gsubr} yourself, but you
 111 can place the information near the function definition itself, so it is
 112 less likely to become incorrect or out-of-date.
 113
 114 If you have many files that @code{guile-snarf} must process, you should
 115 consider using a fragment like the following in your Makefile:
 116
 117 @example
 118 snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
 119 .SUFFIXES: .x
 120 .c.x:
 121         guile-snarf -o $@@ $< $(snarfcppopts)
 122 @end example
 123
 124 This tells make to run @code{guile-snarf} to produce each needed
 125 @file{.x} file from the corresponding @file{.c} file.
 126
 127 The program @code{guile-snarf} passes its command-line arguments
 128 directly to the C preprocessor, which it uses to extract the
 129 information it needs from the source code. this means you can pass
 130 normal compilation flags to @code{guile-snarf} to define preprocessor
 131 symbols, add header file directories, and so on.