Node:How guile-snarf works, Next:Macros guile-snarf recognizes, Up:Init Snarfing with guile-snarf

13.1.1.1 How guile-snarf works

Usage: guile-snarf [-o outfile] [cpp-args ...]

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 configure-time.

See Macros guile-snarf recognizes, for a list of the special (some would say magic) cpp macros you can use, including the list of deprecated macros.

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 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 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 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.