Go to main content

man pages section 1: User Commands

Exit Print View

Updated: July 2017

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


guile-snarf(1)              General Commands Manual             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 ...]

       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"

       If the environment variable CPP is set, use its value instead of the  C
       pre-processor determined at Guile configure-time.

       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

        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-

       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

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

       See attributes(5) for descriptions of the following attributes:

       |Availability   | library/guile    |
       |Stability      | Uncommitted      |
       This    software    was    built    from    source     available     at
       https://java.net/projects/solaris-userland.    The  original  community
       source                was                downloaded                from

       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)