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