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.
7 @node Function Snarfing
8 @section Function Snarfing
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
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.
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}.
28 @cindex guile-snarf invocation
29 @cindex guile-snarf example
31 The @code{guile-snarf} program is invoked like this:
34 guile-snarf [-o @var{outfile}] [@var{cpp-args} ...]
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.
43 If there are errors during processing, @var{outfile} is deleted and the
44 program exits with non-zero status.
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:
51 #ifndef SCM_MAGIC_SNARFER
56 Here is how you might define the Scheme function @code{clear-image},
57 implemented by the C function @code{clear_image}:
63 SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
67 /* C code to clear the image in @code{image_smob}... */
73 #include "image-type.x"
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}.
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.
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
95 guile-snarf -o image-type.x image-type.c
98 This scans @file{image-type.c} for @code{SCM_DEFINE}
99 declarations, and writes to @file{image-type.x} the output:
102 scm_c_define_gsubr ("clear-image", 1, 0, 0, (SCM (*)() ) clear_image);
105 When compiled normally, @code{SCM_DEFINE} is a macro which expands to
106 the function header for @code{clear_image}.
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.
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:
118 snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
121 guile-snarf -o $@@ $< $(snarfcppopts)
124 This tells make to run @code{guile-snarf} to produce each needed
125 @file{.x} file from the corresponding @file{.c} file.
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.