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)