/[guile]/guile/guile-core/doc/ref/tools.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/tools.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.6 by mvo, Sun Mar 24 14:12:07 2002 UTC revision 1.7 by mvo, Thu Oct 3 15:25:04 2002 UTC
# Line 60  generate a file of calls to @code{scm_c_ Line 60  generate a file of calls to @code{scm_c_
60  @code{#include} into an initialization function.  @code{#include} into an initialization function.
61    
62  @menu  @menu
63  * How guile-snarf works::          Using @code{guile-snarf}, with example.  * How guile-snarf works::           Using @code{guile-snarf}, with example.
64  * Macros guile-snarf recognizes::  How to mark up code for @code{guile-snarf}.  * Macros guile-snarf recognizes::   How to mark up code for @code{guile-snarf}.
65    * Writing your own snarfing macros:: How to define new things to snarf.
66  @end menu  @end menu
67    
68  @c ---------------------------------------------------------------------------  @c ---------------------------------------------------------------------------
# Line 70  generate a file of calls to @code{scm_c_ Line 71  generate a file of calls to @code{scm_c_
71  @cindex guile-snarf invocation  @cindex guile-snarf invocation
72  @cindex guile-snarf example  @cindex guile-snarf example
73    
74  Usage: guile-snarf [-d | -D] [-o OUTFILE] INFILE [CPP-OPTIONS ...]  Usage: guile-snarf [-o @var{outfile}] [@var{cpp-args} ...]
75    
76  What @code{guile-snarf} does:  The @code{guile-snarf} program will extract initialization actions to
77    @var{outfile} or to standard output when no @var{outfile} has been
78    specified or when @var{outfile} is @code{-}.  The C preprocessor is
79    called with @var{cpp-args} (which usually include an input file) and
80    the output is filtered to extract the initialization actions.
81    
82  Process INFILE using the C pre-processor and some other programs.  If there are errors during processing, @var{outfile} is deleted and the
83  Write output to a file named OUTFILE or to the standard output when no  program exits with non-zero status.
 OUTFILE has been specified or when OUTFILE is @code{-}.  When writing  
 to a file, ignore lines from the input matching the following grep(1)  
 regular expression:  
84    
85  @example  During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is
86        ^#include ".*OUTFILE"  defined.  You could use this to avoid including snarfer output files
87  @end example  that don't yet exist by writing code like this:
   
 If there are errors during processing, delete OUTFILE and exit with  
 non-zero status.  
88    
89  Optional arg "-d" means grep INFILE for deprecated macros and  @smallexample
90  issue a warning if any are found.  Alternatively, "-D" means  #ifndef SCM_MAGIC_SNARFER
91  do the same thing but signal error and exit with non-zero status.  #include "foo.x"
92    #endif
93    @end smallexample
94    
95  If env var CPP is set, use its value instead of the C pre-processor  If the environment variable @code{CPP} is set, use its value instead of the
96  determined at Guile configure-time.  C pre-processor determined at Guile configure-time.
   
 During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is  
 defined.  
97    
98  @xref{Macros guile-snarf recognizes}, for a list of the special (some would  @xref{Macros guile-snarf recognizes}, for a list of the special (some would
99  say magic) cpp macros you can use, including the list of deprecated macros.  say magic) cpp macros you can use, including the list of deprecated macros.
# Line 112  SCM_DEFINE (clear_image, "clear-image", Line 110  SCM_DEFINE (clear_image, "clear-image",
110              "Clear the image.")              "Clear the image.")
111  #define FUNC_NAME s_clear_image  #define FUNC_NAME s_clear_image
112  @{  @{
113    /* C code to clear the image... */    /* C code to clear the image in @code{image_smob}... */
114  @}  @}
115  #undef FUNC_NAME  #undef FUNC_NAME
116    
# Line 126  init_image_type () Line 124  init_image_type ()
124    
125  The @code{SCM_DEFINE} declaration says that the C function  The @code{SCM_DEFINE} declaration says that the C function
126  @code{clear_image} implements a Scheme subr called @code{clear-image},  @code{clear_image} implements a Scheme subr called @code{clear-image},
127  which takes one required argument (type @code{SCM} named  which takes one required argument (of type @code{SCM} and named
128  @code{image_smob}), no optional arguments, and no tail argument.  @code{image_smob}), no optional arguments, and no rest argument.
129  @xref{Doc Snarfing}, for info on the docstring.  @xref{Doc Snarfing}, for info on the docstring.
130    
131  This works in concert with @code{FUNC_NAME} to also define a static  This works in concert with @code{FUNC_NAME} to also define a static
# Line 140  Assuming the text above lives in a file Line 138  Assuming the text above lives in a file
138  need to execute the following command to prepare this file for compilation:  need to execute the following command to prepare this file for compilation:
139    
140  @example  @example
141  guile-snarf image-type.c  guile-snarf -o image-type.x image-type.c
142  @end example  @end example
143    
144  This scans @file{image-type.c} for @code{SCM_DEFINE}  This scans @file{image-type.c} for @code{SCM_DEFINE}
# Line 150  declarations, and writes to @file{image- Line 148  declarations, and writes to @file{image-
148  scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);  scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
149  @end example  @end example
150    
151  When compiled normally, @code{SCM_DEFINE} is a macro which expands to a  When compiled normally, @code{SCM_DEFINE} is a macro which expands to
152  declaration of the @code{s_clear_image} string.  a declaration of the @code{s_clear_image} string and the function
153    header for @code{clear_image}.
154    
155  Note that the output file name matches the @code{#include} from the  Note that the output file name matches the @code{#include} from the
156  input file.  Also, you still need to provide all the same information  input file.  Also, you still need to provide all the same information
# Line 172  snarfcppopts = $(DEFS) $(INCLUDES) $(CPP Line 171  snarfcppopts = $(DEFS) $(INCLUDES) $(CPP
171  This tells make to run @code{guile-snarf} to produce each needed  This tells make to run @code{guile-snarf} to produce each needed
172  @file{.x} file from the corresponding @file{.c} file.  @file{.x} file from the corresponding @file{.c} file.
173    
174  Aside from the required argument INFILE, @code{guile-snarf} passes its  The program @code{guile-snarf} passes its command-line arguments
175  command-line arguments directly to the C preprocessor, which it uses to  directly to the C preprocessor, which it uses to extract the
176  extract the information it needs from the source code. this means you can pass  information it needs from the source code. this means you can pass
177  normal compilation flags to @code{guile-snarf} to define preprocessor symbols,  normal compilation flags to @code{guile-snarf} to define preprocessor
178  add header file directories, and so on.  symbols, add header file directories, and so on.
179    
180  @c ---------------------------------------------------------------------------  @c ---------------------------------------------------------------------------
181  @node Macros guile-snarf recognizes  @node Macros guile-snarf recognizes
# Line 225  ARGLIST is an argument list (in parenthe Line 224  ARGLIST is an argument list (in parenthe
224  is a expression suitable for initializing a new variable.  is a expression suitable for initializing a new variable.
225    
226  For procedures, you can use @code{SCM_DEFINE} for most purposes.  Use  For procedures, you can use @code{SCM_DEFINE} for most purposes.  Use
227  @code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't want  @code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't
228  to be bothered with docstrings.  Use @code{SCM_GPROC} for generic  want to be bothered with docstrings.  Use @code{SCM_GPROC} for generic
229  functions (@pxref{GOOPS,,,goops}).  All procedures are declared  functions (@pxref{GOOPS,,,goops}).  All procedures are declared with
230  @code{static} with return type @code{SCM}.  return type @code{SCM}.
231    
232  For everything else, use the appropriate macro (@code{SCM_SYMBOL} for  For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
233  symbols, and so on).  The "_GLOBAL_" variants omit @code{static}  symbols, and so on).  Without "_GLOBAL_", the declarations are
234  declaration.  @code{static}.
235    
236  All these macros should be used at top-level, outside function bodies.  All these macros should be used at top-level, outside function bodies.
237  Also, it's a good idea to define @var{FUNC_NAME} immediately after using  Also, it's a good idea to define @var{FUNC_NAME} immediately after using
238  @code{SCM_DEFINE} (and similar), and then the function body, and then  @code{SCM_DEFINE} (and similar), and then the function body, and then
239  @code{#undef FUNC_NAME}.  @code{#undef FUNC_NAME}.
240    
241  Here is the list of deprecated macros:  @xref{How guile-snarf works}, and also libguile source, for examples.
242    @xref{Subrs}, for details on argument passing and how to write C
243    functions.
244    
245    @c ---------------------------------------------------------------------------
246    @node Writing your own snarfing macros
247    @subsubsection Writing your own snarfing macros
248    
249    When you want to use the general snarfing machanism, but none of the
250    provided macros fits your need, you can use the macro
251    @code{SCM_SNARF_INIT}.
252    
253    For example, the @code{SCM_SYMBOL} macro can be defined like this:
254    
 @c reminder: sync w/ libguile/guile-snarf.in var `deprecated_list'  
255  @example  @example
256   SCM_CONST_LONG  #define SCM_SYMBOL(c_name, scheme_name) \
257   SCM_VCELL  static SCM c_name \
258   SCM_VCELL_INIT  SCM_SNARF_INIT(c_name = scm_permanent_object (scm_str2symbol (scheme_name)))
  SCM_GLOBAL_VCELL  
  SCM_GLOBAL_VCELL_INIT  
259  @end example  @end example
260    
261  Some versions of guile (and guile-snarf) will continue to recognize them but  @defmac SCM_SNARF_INIT (code)
262  at some point they will no longer work.  You can pass either @code{-d} or  When processed normally, @code{SCM_SNARF_INIT} expands to nothing;
263  @code{-D} option to have guile-snarf warn or signal error, respectively, if  when processed by the snarfer, it causes @var{code} to be included in
264  any of these are found in the input file.  the initialization action file, followed by a semicolon.
265    @end defmac
 @xref{How guile-snarf works}, and also libguile source, for examples.  
 @xref{Subrs}, for details on argument passing and how to write C  
 functions.  
266    
267  @c ---------------------------------------------------------------------------  @c ---------------------------------------------------------------------------
268  @node Doc Snarfing  @node Doc Snarfing

Legend:
Removed from v.1.6  
changed lines
  Added in v.1.7

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26