3 .\" Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights reserved.
5 .\" This man page created by Oracle to provide a reference to the
6 .\" Info format documentation for guile provided with the distribution.
8 .TH guile-snarf 1 "26 May 2008"
10 guile-snarf \- a tool designed to help guile users to collect subr
11 information from distributed c files
13 /usr/bin/guile-snarf [-o outfile] [cpp-args ...]
15 When writing C code for use with Guile, you typically define a set of
16 C functions, and then make some of them visible to the Scheme world by
17 calling the scm_c_define_gsubr function; a C function published in this
18 way is called a subr. If you have many subrs to publish, it can sometimes
19 be annoying to keep the list of calls to scm_c_define_gsubr in sync with
20 the list of function definitions. Frequently, a programmer will define
21 a new subr in C, recompile the application, and then discover that the
22 Scheme interpreter cannot see the subr, because of a missed call to
25 Guile provides the guile-snarf command to manage this problem. Using this
26 tool, you can keep all the information needed to define the subr alongside
27 the function definition itself; guile-snarf will extract this information
28 from your source code, and automatically generate a file of calls to
29 scm_c_define_gsubr which you can #include into an initialization function.
31 The guile-snarf program will extract initialization actions to outfile or
32 to standard output when no outfile has been specified or when outfile
33 is -. The C preprocessor is called with cpp-args (which usually include
34 an input file) and the output is filtered to extract the initialization
37 If there are errors during processing, outfile is deleted and the program
38 exits with non-zero status.
40 During snarfing, the pre-processor macro SCM_MAGIC_SNARFER is defined.
41 You could use this to avoid including snarfer output files that don't yet
42 exist by writing code like this:
44 #ifndef SCM_MAGIC_SNARFER
48 If the environment variable CPP is set, use its value instead of the C
49 pre-processor determined at Guile configure-time.
51 For example, here is how you might define a new subr called clear-image,
52 implemented by the C function clear_image:
56 SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
60 #define FUNC_NAME s_clear_image
62 /* C code to clear the image in image_smob... */
70 #include "image-type.x"
73 The SCM_DEFINE declaration says that the C function clear_image implements
74 a Scheme subr called clear-image, which takes one required argument (of
75 type SCM and named image_smob), no optional arguments, and no rest argument.
76 See Doc Snarfing, for info on the docstring.
78 This works in concert with FUNC_NAME to also define a static array of
79 characters named s_clear_image, initialized to the string "clear-image".
80 The body of clear_image may use the array in error messages, instead of
81 writing out the literal string; this may save string space on some systems.
83 Assuming the text above lives in a file named image-type.c, you will need
84 to execute the following command to prepare this file for compilation:
86 .I guile-snarf -o image-type.x image-type.c
88 This scans image-type.c for SCM_DEFINE declarations, and writes to
89 image-type.x the output:
91 scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
93 When compiled normally, SCM_DEFINE is a macro which expands to a
94 declaration of the s_clear_image string and the function header for
97 Note that the output file name matches the #include from the input file.
98 Also, you still need to provide all the same information you would if you
99 were using scm_c_define_gsubr yourself, but you can place the information
100 near the function definition itself, so it is less likely to become
101 incorrect or out-of-date.
103 If you have many files that guile-snarf must process, you should consider
104 using a fragment like the following in your Makefile:
106 snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
109 guile-snarf -o $ $< $(snarfcppopts)
111 This tells make to run guile-snarf to produce each needed .x file from the
112 corresponding .c file.
114 The program guile-snarf passes its command-line arguments directly to the
115 C preprocessor, which it uses to extract the information it needs from
116 the source code. this means you can pass normal compilation flags to
117 guile-snarf to define preprocessor symbols, add header file directories,