guile-snarf - a tool designed to help guile users to collect subr information from distributed c files
/usr/bin/guile-snarf [-o outfile] [cpp-args ...]
guile-snarf(1) General Commands Manual guile-snarf(1)
NAME
guile-snarf - a tool designed to help guile users to collect subr
information from distributed c files
SYNOPSIS
/usr/bin/guile-snarf [-o outfile] [cpp-args ...]
DESCRIPTION
When writing C code for use with Guile, you typically define a set of C
functions, and then make some of them visible to the Scheme world by
calling the scm_c_define_gsubr function; a C function published in this
way is called a subr. If you have many subrs to publish, it can some-
times be annoying to keep the list of calls to scm_c_define_gsubr in
sync with the list of function definitions. Frequently, a programmer
will define a new subr in C, recompile the application, and then dis-
cover that the Scheme interpreter cannot see the subr, because of a
missed call to scm_c_define_gsubr.
Guile provides the guile-snarf command to manage this problem. Using
this tool, you can keep all the information needed to define the subr
alongside the function definition itself; guile-snarf will extract this
information from your source code, and automatically generate a file of
calls to scm_c_define_gsubr which you can #include into an initializa-
tion function.
The guile-snarf program will extract initialization actions to outfile
or to standard output when no outfile has been specified or when out-
file is -. The C preprocessor is called with cpp-args (which usually
include an input file) and the output is filtered to extract the ini-
tialization actions.
If there are errors during processing, outfile is deleted and the pro-
gram exits with non-zero status.
During snarfing, the pre-processor macro SCM_MAGIC_SNARFER is defined.
You could use this to avoid including snarfer output files that don't
yet exist by writing code like this:
#ifndef SCM_MAGIC_SNARFER
#include "foo.x"
#endif
If the environment variable CPP is set, use its value instead of the C
pre-processor determined at Guile configure-time.
EXAMPLES
For example, here is how you might define a new subr called clear-
image, implemented by the C function clear_image:
#include <libguile.h>
SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
(SCM image_smob),
"Clear the image.")
#define FUNC_NAME s_clear_image
{
/* C code to clear the image in image_smob... */
}
#undef FUNC_NAME
void
init_image_type ()
{
#include "image-type.x"
}
The SCM_DEFINE declaration says that the C function clear_image imple-
ments a Scheme subr called clear-image, which takes one required argu-
ment (of type SCM and named image_smob), no optional arguments, and no
rest argument. See Doc Snarfing, for info on the docstring.
This works in concert with FUNC_NAME to also define a static array of
characters named s_clear_image, initialized to the string "clear-
image". The body of clear_image may use the array in error messages,
instead of writing out the literal string; this may save string space
on some systems.
Assuming the text above lives in a file named image-type.c, you will
need to execute the following command to prepare this file for compila-
tion:
guile-snarf -o image-type.x image-type.c
This scans image-type.c for SCM_DEFINE declarations, and writes to
image-type.x the output:
scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
When compiled normally, SCM_DEFINE is a macro which expands to a decla-
ration of the s_clear_image string and the function header for
clear_image.
Note that the output file name matches the #include from the input
file. Also, you still need to provide all the same information you
would if you were using scm_c_define_gsubr yourself, but you can place
the information near the function definition itself, so it is less
likely to become incorrect or out-of-date.
If you have many files that guile-snarf must process, you should con-
sider using a fragment like the following in your Makefile:
snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
.SUFFIXES: .x
.c.x:
guile-snarf -o $ $< $(snarfcppopts)
This tells make to run guile-snarf to produce each needed .x file from
the corresponding .c file.
The program guile-snarf passes its command-line arguments directly to
the C preprocessor, which it uses to extract the information it needs
from the source code. this means you can pass normal compilation flags
to guile-snarf to define preprocessor symbols, add header file directo-
ries, and so on.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | library/guile |
+---------------+------------------+
|Stability | Uncommitted |
+---------------+------------------+
NOTES
This software was built from source available at
https://java.net/projects/solaris-userland. The original community
source was downloaded from
http://ftp.gnu.org/pub/gnu/guile/guile-1.8.6.tar.gz
Further information about this software can be found on the open source
community website at http://www.gnu.org/software/guile/.
26 May 2008 guile-snarf(1)