guile-snarf
(1)
名前
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 ...]
説明
User Commands 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 sometimes 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 discover 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 prob-
lem. 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 initial-
ization function.
The guile-snarf program will extract initialization actions
to outfile or to standard output when no outfile has been
specified or when outfile is -. The C preprocessor is called
with cpp-args (which usually include an input file) and the
output is filtered to extract the initialization actions.
If there are errors during processing, outfile is deleted
and the program 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 config-
ure-time.
EXAMPLES
For example, here is how you might define a new subr called
clear-image, implemented by the C function clear_image:
SunOS 5.11 Last change: 26 May 2008 1
User Commands guile-snarf(1)
#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 implements a Scheme subr called clear-image,
which takes one required argument (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 compilation:
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 declaration of the s_clear_image string and the func-
tion 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 func-
tion definition itself, so it is less likely to become
SunOS 5.11 Last change: 26 May 2008 2
User Commands guile-snarf(1)
incorrect or out-of-date.
If you have many files that guile-snarf must process, you
should consider 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 directories, 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/soft-
ware/guile/.
SunOS 5.11 Last change: 26 May 2008 3