'\" t
.\"
.\" Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights reserved.
.\"
.\" This man page created by Oracle to provide a reference to the
.\" Info format documentation for guile provided with the distribution.
.\"
.TH guile-snarf 1 "26 May 2008"
.SH NAME
guile-snarf \- a tool designed to help guile users to collect subr 
information from distributed c files
.SH SYNOPSIS
/usr/bin/guile-snarf [-o outfile] [cpp-args ...]
.SH 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.
.LP
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 initialization function. 
.LP
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.
.LP
If there are errors during processing, outfile is deleted and the program
exits with non-zero status.
.LP
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:
.LP
    #ifndef SCM_MAGIC_SNARFER
    #include "foo.x"
    #endif
.LP
If the environment variable CPP is set, use its value instead of the C 
pre-processor determined at Guile configure-time. 
.SH EXAMPLES
For example, here is how you might define a new subr called clear-image,
implemented by the C function clear_image:
.LP
 #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"
 }
.LP
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.
.LP
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.
.LP
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:

.I guile-snarf -o image-type.x image-type.c
.LP
This scans image-type.c for SCM_DEFINE declarations, and writes to
image-type.x the output:
.LP
scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
.LP
When compiled normally, SCM_DEFINE is a macro which expands to a 
declaration of the s_clear_image string and the function header for 
clear_image.
.LP
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.
.LP
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)
.LP
This tells make to run guile-snarf to produce each needed .x file from the
corresponding .c file.
.LP
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.