Commit | Line | Data |
---|---|---|
3229f68b MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
c60e6ed4 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2012 |
3229f68b MV |
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 | ||
72b3aa56 | 24 | The snarfing mechanism works for many kind of initialization actions, |
3229f68b MV |
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 | ||
c60e6ed4 AW |
85 | @code{SCM_DEFINE} macro also defines a static array of characters |
86 | initialized to the Scheme name of the function. In this case, | |
87 | @code{s_clear_image} is set to the C string, "clear-image". You might | |
88 | want to use this symbol when generating error messages. | |
3229f68b MV |
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. |