components/library/guile/files/guile-snarf.1

   1 '\" t
   2 .\"
   3 .\" Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights reserved.
   4 .\"
   5 .\" This man page created by Oracle to provide a reference to the
   6 .\" Info format documentation for guile provided with the distribution.
   7 .\"
   8 .TH guile-snarf 1 "26 May 2008"
   9 .SH NAME
  10 guile-snarf \- a tool designed to help guile users to collect subr
  11 information from distributed c files
  12 .SH SYNOPSIS
  13 /usr/bin/guile-snarf [-o outfile] [cpp-args ...]
  14 .SH DESCRIPTION
  15 When writing C code for use with Guile, you typically define a set of
  16 C functions, and then make some of them visible to the Scheme world by
  17 calling the scm_c_define_gsubr function; a C function published in this
  18 way is called a subr. If you have many subrs to publish, it can sometimes
  19 be annoying to keep the list of calls to scm_c_define_gsubr in sync with
  20 the list of function definitions. Frequently, a programmer will define
  21 a new subr in C, recompile the application, and then discover that the
  22 Scheme interpreter cannot see the subr, because of a missed call to
  23 scm_c_define_gsubr.
  24 .LP
  25 Guile provides the guile-snarf command to manage this problem. Using this
  26 tool, you can keep all the information needed to define the subr alongside
  27 the function definition itself; guile-snarf will extract this information
  28 from your source code, and automatically generate a file of calls to
  29 scm_c_define_gsubr which you can #include into an initialization function.
  30 .LP
  31 The guile-snarf program will extract initialization actions to outfile or
  32 to standard output when no outfile has been specified or when outfile
  33 is -. The C preprocessor is called with cpp-args (which usually include
  34 an input file) and the output is filtered to extract the initialization
  35 actions.
  36 .LP
  37 If there are errors during processing, outfile is deleted and the program
  38 exits with non-zero status.
  39 .LP
  40 During snarfing, the pre-processor macro SCM_MAGIC_SNARFER is defined.
  41 You could use this to avoid including snarfer output files that don't yet
  42 exist by writing code like this:
  43 .LP
  44     #ifndef SCM_MAGIC_SNARFER
  45     #include "foo.x"
  46     #endif
  47 .LP
  48 If the environment variable CPP is set, use its value instead of the C
  49 pre-processor determined at Guile configure-time.
  50 .SH EXAMPLES
  51 For example, here is how you might define a new subr called clear-image,
  52 implemented by the C function clear_image:
  53 .LP
  54  #include <libguile.h>
  55
  56  SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
  57             (SCM image_smob),
  58             "Clear the image.")
  59
  60  #define FUNC_NAME s_clear_image
  61  {
  62    /* C code to clear the image in image_smob... */
  63
  64  }
  65  #undef FUNC_NAME
  66
  67  void
  68  init_image_type ()
  69  {
  70      #include "image-type.x"
  71  }
  72 .LP
  73 The SCM_DEFINE declaration says that the C function clear_image implements
  74 a Scheme subr called clear-image, which takes one required argument (of
  75 type SCM and named image_smob), no optional arguments, and no rest argument.
  76 See Doc Snarfing, for info on the docstring.
  77 .LP
  78 This works in concert with FUNC_NAME to also define a static array of
  79 characters named s_clear_image, initialized to the string "clear-image".
  80 The body of clear_image may use the array in error messages, instead of
  81 writing out the literal string; this may save string space on some systems.
  82 .LP
  83 Assuming the text above lives in a file named image-type.c, you will need
  84 to execute the following command to prepare this file for compilation:
  85
  86 .I guile-snarf -o image-type.x image-type.c
  87 .LP
  88 This scans image-type.c for SCM_DEFINE declarations, and writes to
  89 image-type.x the output:
  90 .LP
  91 scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
  92 .LP
  93 When compiled normally, SCM_DEFINE is a macro which expands to a
  94 declaration of the s_clear_image string and the function header for
  95 clear_image.
  96 .LP
  97 Note that the output file name matches the #include from the input file.
  98 Also, you still need to provide all the same information you would if you
  99 were using scm_c_define_gsubr yourself, but you can place the information
 100 near the function definition itself, so it is less likely to become
 101 incorrect or out-of-date.
 102 .LP
 103 If you have many files that guile-snarf must process, you should consider
 104 using a fragment like the following in your Makefile:
 105
 106  snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
 107  .SUFFIXES: .x
 108  .c.x:
 109         guile-snarf -o $ $< $(snarfcppopts)
 110 .LP
 111 This tells make to run guile-snarf to produce each needed .x file from the
 112 corresponding .c file.
 113 .LP
 114 The program guile-snarf passes its command-line arguments directly to the
 115 C preprocessor, which it uses to extract the information it needs from
 116 the source code. this means you can pass normal compilation flags to
 117 guile-snarf to define preprocessor symbols, add header file directories,
 118 and so on.