0
|
1 |
'\" t
|
|
2 |
.\"
|
11
|
3 |
.\" Copyright 2010 Sun Microsystems, Inc. All rights reserved.
|
0
|
4 |
.\" Use is subject to license terms.
|
|
5 |
.\"
|
11
|
6 |
.\" ident "@(#)guile-snarf.1 1.2 10/03/16 SMI"
|
0
|
7 |
.\"
|
|
8 |
.\" This man page created by Sun to provide a reference to the
|
|
9 |
.\" Info format documentation for guile provided with the distribution.
|
|
10 |
.\"
|
|
11 |
.TH guile-snarf 1 "26 May 2008"
|
|
12 |
.SH NAME
|
|
13 |
guile-snarf \- a tool designed to help guile users to collect subr
|
|
14 |
information from distributed c files
|
|
15 |
.SH SYNOPSIS
|
|
16 |
/usr/bin/guile-snarf [-o outfile] [cpp-args ...]
|
|
17 |
.SH DESCRIPTION
|
|
18 |
When writing C code for use with Guile, you typically define a set of
|
|
19 |
C functions, and then make some of them visible to the Scheme world by
|
|
20 |
calling the scm_c_define_gsubr function; a C function published in this
|
|
21 |
way is called a subr. If you have many subrs to publish, it can sometimes
|
|
22 |
be annoying to keep the list of calls to scm_c_define_gsubr in sync with
|
|
23 |
the list of function definitions. Frequently, a programmer will define
|
|
24 |
a new subr in C, recompile the application, and then discover that the
|
|
25 |
Scheme interpreter cannot see the subr, because of a missed call to
|
|
26 |
scm_c_define_gsubr.
|
|
27 |
.LP
|
|
28 |
Guile provides the guile-snarf command to manage this problem. Using this
|
|
29 |
tool, you can keep all the information needed to define the subr alongside
|
|
30 |
the function definition itself; guile-snarf will extract this information
|
|
31 |
from your source code, and automatically generate a file of calls to
|
|
32 |
scm_c_define_gsubr which you can #include into an initialization function.
|
|
33 |
.LP
|
|
34 |
The guile-snarf program will extract initialization actions to outfile or
|
|
35 |
to standard output when no outfile has been specified or when outfile
|
|
36 |
is -. The C preprocessor is called with cpp-args (which usually include
|
|
37 |
an input file) and the output is filtered to extract the initialization
|
|
38 |
actions.
|
|
39 |
.LP
|
|
40 |
If there are errors during processing, outfile is deleted and the program
|
|
41 |
exits with non-zero status.
|
|
42 |
.LP
|
|
43 |
During snarfing, the pre-processor macro SCM_MAGIC_SNARFER is defined.
|
|
44 |
You could use this to avoid including snarfer output files that don't yet
|
|
45 |
exist by writing code like this:
|
|
46 |
.LP
|
|
47 |
#ifndef SCM_MAGIC_SNARFER
|
|
48 |
#include "foo.x"
|
|
49 |
#endif
|
|
50 |
.LP
|
|
51 |
If the environment variable CPP is set, use its value instead of the C
|
|
52 |
pre-processor determined at Guile configure-time.
|
|
53 |
.SH EXAMPLES
|
|
54 |
For example, here is how you might define a new subr called clear-image,
|
|
55 |
implemented by the C function clear_image:
|
|
56 |
.LP
|
|
57 |
#include <libguile.h>
|
|
58 |
|
|
59 |
SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
|
|
60 |
(SCM image_smob),
|
|
61 |
"Clear the image.")
|
|
62 |
|
|
63 |
#define FUNC_NAME s_clear_image
|
|
64 |
{
|
|
65 |
/* C code to clear the image in image_smob... */
|
|
66 |
|
|
67 |
}
|
|
68 |
#undef FUNC_NAME
|
|
69 |
|
|
70 |
void
|
|
71 |
init_image_type ()
|
|
72 |
{
|
|
73 |
#include "image-type.x"
|
|
74 |
}
|
|
75 |
.LP
|
|
76 |
The SCM_DEFINE declaration says that the C function clear_image implements
|
|
77 |
a Scheme subr called clear-image, which takes one required argument (of
|
|
78 |
type SCM and named image_smob), no optional arguments, and no rest argument.
|
|
79 |
See Doc Snarfing, for info on the docstring.
|
|
80 |
.LP
|
|
81 |
This works in concert with FUNC_NAME to also define a static array of
|
|
82 |
characters named s_clear_image, initialized to the string "clear-image".
|
|
83 |
The body of clear_image may use the array in error messages, instead of
|
|
84 |
writing out the literal string; this may save string space on some systems.
|
|
85 |
.LP
|
|
86 |
Assuming the text above lives in a file named image-type.c, you will need
|
|
87 |
to execute the following command to prepare this file for compilation:
|
|
88 |
|
|
89 |
.I guile-snarf -o image-type.x image-type.c
|
|
90 |
.LP
|
|
91 |
This scans image-type.c for SCM_DEFINE declarations, and writes to
|
|
92 |
image-type.x the output:
|
|
93 |
.LP
|
|
94 |
scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
|
|
95 |
.LP
|
|
96 |
When compiled normally, SCM_DEFINE is a macro which expands to a
|
|
97 |
declaration of the s_clear_image string and the function header for
|
|
98 |
clear_image.
|
|
99 |
.LP
|
|
100 |
Note that the output file name matches the #include from the input file.
|
|
101 |
Also, you still need to provide all the same information you would if you
|
|
102 |
were using scm_c_define_gsubr yourself, but you can place the information
|
|
103 |
near the function definition itself, so it is less likely to become
|
|
104 |
incorrect or out-of-date.
|
|
105 |
.LP
|
|
106 |
If you have many files that guile-snarf must process, you should consider
|
|
107 |
using a fragment like the following in your Makefile:
|
|
108 |
|
|
109 |
snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
|
|
110 |
.SUFFIXES: .x
|
|
111 |
.c.x:
|
|
112 |
guile-snarf -o $ $< $(snarfcppopts)
|
|
113 |
.LP
|
|
114 |
This tells make to run guile-snarf to produce each needed .x file from the
|
|
115 |
corresponding .c file.
|
|
116 |
.LP
|
|
117 |
The program guile-snarf passes its command-line arguments directly to the
|
|
118 |
C preprocessor, which it uses to extract the information it needs from
|
|
119 |
the source code. this means you can pass normal compilation flags to
|
|
120 |
guile-snarf to define preprocessor symbols, add header file directories,
|
|
121 |
and so on.
|
|
122 |
.SH ATTRIBUTES
|
|
123 |
See
|
|
124 |
.BR attributes (5)
|
|
125 |
for descriptions of the following attributes:
|
|
126 |
.sp
|
|
127 |
.TS
|
|
128 |
box;
|
|
129 |
cbp-1 | cbp-1
|
|
130 |
l | l .
|
|
131 |
ATTRIBUTE TYPE ATTRIBUTE VALUE
|
|
132 |
=
|
11
|
133 |
Availability library/guile
|
0
|
134 |
=
|
|
135 |
Interface Stability Uncommitted
|
|
136 |
.TE
|
|
137 |
.SH NOTES
|
|
138 |
Source for guile is available on http://opensolaris.org.
|