'\" 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.