man pages section 1: User Commands

Exit Print View

Updated: July 2014

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


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

     Guile  provides the guile-snarf command to manage this prob-
     lem. 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  initial-
     ization function.

     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"

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

     For  example, here is how you might define a new subr called
     clear-image, implemented by the C function clear_image:

SunOS 5.11           Last change: 26 May 2008                   1

User Commands                                      guile-snarf(1)

      #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  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 (*)() )

     When compiled normally, SCM_DEFINE is a macro which  expands
     to  a  declaration of the s_clear_image string and the func-
     tion 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 func-
     tion definition itself, so  it  is  less  likely  to  become

SunOS 5.11           Last change: 26 May 2008                   2

User Commands                                      guile-snarf(1)

     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

      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  directories,  and  so

     See   attributes(5)   for   descriptions  of  the  following

     |Availability   | library/guile    |
     |Stability      | Uncommitted      |
     This  software  was   built   from   source   available   at    The  original
     community       source       was       downloaded       from

     Further  information about this software can be found on the
     open source community  website  at

SunOS 5.11           Last change: 26 May 2008                   3