/[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.4 by ttn, Thu Mar 14 04:04:32 2002 UTC revision 1.5 by ttn, Fri Mar 15 14:22:07 2002 UTC
# Line 62  generate a file of calls to @code{scm_c_ Line 62  generate a file of calls to @code{scm_c_
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}.
 * guile-1.4 guile-snarf::          The old way, and how handle it.  
65  @end menu  @end menu
66    
67  @c ---------------------------------------------------------------------------  @c ---------------------------------------------------------------------------
# Line 71  generate a file of calls to @code{scm_c_ Line 70  generate a file of calls to @code{scm_c_
70  @cindex guile-snarf invocation  @cindex guile-snarf invocation
71  @cindex guile-snarf example  @cindex guile-snarf example
72    
73  Usage: guile-snarf [--compat=1.4] [-o OUTFILE] INFILE [CPP-OPTIONS ...]  Usage: guile-snarf [-d | -D] [-o OUTFILE] INFILE [CPP-OPTIONS ...]
74    
75  What @code{guile-snarf} does:  What @code{guile-snarf} does:
76    
# Line 87  lines from the input matching grep(1) re Line 86  lines from the input matching grep(1) re
86  If there are errors during processing, delete OUTFILE and exit with  If there are errors during processing, delete OUTFILE and exit with
87  non-zero status.  non-zero status.
88    
89  Optional arg "--compat=1.4" means emulate guile-1.4 guile-snarf.  Optional arg "-d" means grep INFILE for deprecated macros and
90  This option is not fully tested (@pxref{guile-1.4 guile-snarf}).  issue a warning if any are found.  Alternatively, "-D" means
91    do the same thing but signal error and exit with non-zero status.
92    
93  If env var CPP is set, use its value instead of the C pre-processor  If env var CPP is set, use its value instead of the C pre-processor
94  determined at Guile configure-time.  determined at Guile configure-time.
95    
96  @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
97  say magic) cpp macros you can use.  say magic) cpp macros you can use, including the list of deprecated macros.
98    
99  For example, here is how you might define a new subr called  For example, here is how you might define a new subr called
100  @code{clear-image}, implemented by the C function @code{clear_image}:  @code{clear-image}, implemented by the C function @code{clear_image}:
# Line 178  add header file directories, and so on. Line 178  add header file directories, and so on.
178  @node Macros guile-snarf recognizes  @node Macros guile-snarf recognizes
179  @subsubsection Macros guile-snarf recognizes  @subsubsection Macros guile-snarf recognizes
180  @cindex guile-snarf recognized macros  @cindex guile-snarf recognized macros
181    @cindex guile-snarf deprecated macros
182    
183  Here are the macros you can use in your source code from which  Here are the macros you can use in your source code from which
184  @code{guile-snarf} can construct initialization code:  @code{guile-snarf} can construct initialization code:
# Line 234  Also, it's a good idea to define @var{FU Line 235  Also, it's a good idea to define @var{FU
235  @code{SCM_DEFINE} (and similar), and then the function body, and then  @code{SCM_DEFINE} (and similar), and then the function body, and then
236  @code{#undef FUNC_NAME}.  @code{#undef FUNC_NAME}.
237    
238  @xref{How guile-snarf works}, and also libguile source, for examples.  Here is the list of deprecated macros:
 @xref{Subrs}, for details on argument passing and how to write C  
 functions.  
   
 @xref{guile-1.4 guile-snarf}, if you have code that relies on the guile-snarf  
 shipped with guile-1.4 (guile-snarf shipped with guile-1.6 is different).  
   
 @c ---------------------------------------------------------------------------  
 @node guile-1.4 guile-snarf  
 @subsubsection guile-1.4 guile-snarf  
 @cindex guile-1.4 guile-snarf  
 @cindex guile-snarf, guile-1.4  
   
 The @code{guile-snarf} included with guile-1.4 differs in behavior and usage  
 from that included with guile-1.6 and later.  This page explains the four  
 kinds of modifications code written with guile-1.4 guile-snarf in mind need to  
 undergo, in order to be completely compatible with guile-1.6 init snarfing  
 practice; and explains how to use @code{guile-snarf --compat=1.4}.  
   
 @itemize  
   
 @item Some of the recognized macro names have changed.  
   
 Specifically, you need to rename:  
   
 @itemize  
 @item SCM_VCELL to SCM_VARIABLE  
 @item SCM_GLOBAL_VCELL to SCM_GLOBAL_VARIABLE  
 @item SCM_VCELL_INIT to SCM_VARIABLE_INIT  
 @item SCM_GLOBAL_VCELL_INIT to SCM_GLOBAL_VARIABLE_INIT  
 @end itemize  
   
 @item The macro SCM_CONST_LONG is no longer recognized.  
   
 Proabably you can use SCM_GLOBAL_VARIABLE_INIT where you would have  
 formerly used SCM_CONST_LONG.  [fixme: needs verification]  
   
 @item guile-snarf is no longer usable in a pipe.  
   
 With guile-1.4 guile-snarf you had capture its output to a file, check  
 the exit value of the guile-snarf process, and delete the file if that  
 value was false.  These operations are now handled internally to  
 guile-snarf, providing you either specify the output file explicitly, or  
 use an input file name that ends in @code{.c} (in which case the output  
 filename is computed from the input filename by replacing @code{.c} with  
 @code{.x}).  
   
 @end itemize  
   
 If you have code that uses the old snarf macros (for example,  
 SCM_VCELL), but have installed the new guile-snarf, you can arrange for  
 the old macros to be still recognized by using the @code{--compat=1.4}  
 option.  With this option, old macros are translated to their new  
 variants on input to the modern snarfing process.  This means the .x  
 files produced will make use of @code{scm_c_define_gsubr} and friends,  
 which are ready to be compiled against the new libguile.  
   
 Thus, @code{--compat=1.4} does not provide @emph{full} emulation, only  
 input emulation.  (The thinking is: If you have a new guile-snarf  
 installed, probably you have a new libguile installed, too, and would  
 prefer to get your old code to work with the new libguile.)  
   
 The makefile fragment to use would look something like:  
239    
240    @c reminder: sync w/ libguile/guile-snarf.in var `deprecated_list'
241  @example  @example
242  .c.x:   SCM_CONST_LONG
243          guile-snarf --compat=1.4 -o $@ $<   SCM_VCELL
244     SCM_VCELL_INIT
245     SCM_GLOBAL_VCELL
246     SCM_GLOBAL_VCELL_INIT
247  @end example  @end example
248    
249  After you've done a global search and replace on SCM_VCELL and friends,  Some versions of guile (and guile-snarf) will continue to recognize them but
250  you can remove @code{--compat=1.4} altogether (@pxref{How guile-snarf  at some point they will no longer work.  You can pass either @code{-d} or
251  works}).  @code{-D} option to have guile-snarf warn or signal error, respectively, if
252    any of these are found in the input file.
253    
254    @xref{How guile-snarf works}, and also libguile source, for examples.
255    @xref{Subrs}, for details on argument passing and how to write C
256    functions.
257    
258  @c ---------------------------------------------------------------------------  @c ---------------------------------------------------------------------------
259  @node Doc Snarfing  @node Doc Snarfing

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

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