(guile.info.gz) How guile-snarf works

Info Catalog

(guile.info.gz) Init Snarfing with guile-snarf

(guile.info.gz) Macros guile-snarf recognizes

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

Info Catalog

(guile.info.gz) Init Snarfing with guile-snarf

(guile.info.gz) Macros guile-snarf recognizes