/[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.1.2.2 by ttn, Fri Mar 8 21:30:20 2002 UTC revision 1.1.2.3 by ttn, Thu Mar 14 05:30:42 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}.
65    * guile-1.4 guile-snarf::          The old way, and how handle it.
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: @code{guile-snarf} [CPP-OPTIONS ...] SOURCE.c  Usage: guile-snarf [--compat=1.4] [-o OUTFILE] INFILE [CPP-OPTIONS ...]
75    
76  @code{guile-snarf} uses cpp to process SOURCE.c, writing C language  What @code{guile-snarf} does:
77  initialization calls to standard output, based on special (some would say  
78  magic) cpp macros found in the input (@pxref{Macros guile-snarf recognizes}).  Process INFILE using the C pre-processor and some other programs.
79    Write output to a file, named OUTFILE if specified, or STEM.x if
80    INFILE looks like STEM.c and no OUTFILE is specified.  Ignore
81    lines from the input matching grep(1) regular expression:
82    
83    @example
84          ^#include ".*OUTFILE"
85    @end example
86    
87    If there are errors during processing, delete OUTFILE and exit with
88    non-zero status.
89    
90    Optional arg "--compat=1.4" means emulate guile-1.4 guile-snarf.
91    This option is not fully tested (@pxref{guile-1.4 guile-snarf}).
92    
93    If env var CPP is set, use its value instead of the C pre-processor
94    determined at Guile configure-time.
95    
96    @xref{Macros guile-snarf recognizes}, for a list of the special (some would
97    say magic) cpp macros you can use.
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 116  Assuming the text above lives in a file Line 136  Assuming the text above lives in a file
136  need to execute the following command to prepare this file for compilation:  need to execute the following command to prepare this file for compilation:
137    
138  @example  @example
139  guile-snarf image-type.c > image-type.x  guile-snarf image-type.c
140  @end example  @end example
141    
142  This scans @file{image-type.c} for @code{SCM_DEFINE}  This scans @file{image-type.c} for @code{SCM_DEFINE}
# Line 136  can place the information near the funct Line 156  can place the information near the funct
156  less likely to become incorrect or out-of-date.  less likely to become incorrect or out-of-date.
157    
158  If you have many files that @code{guile-snarf} must process, you should  If you have many files that @code{guile-snarf} must process, you should
159  consider using a rule like the following in your Makefile:  consider using a fragment like the following in your Makefile:
160    
161  @example  @example
162    snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
163  .SUFFIXES: .x  .SUFFIXES: .x
164  .c.x:  .c.x:
165          guile-snarf $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) $< > $@@          guile-snarf -o $@ $< $(snarfcppopts)
166  @end example  @end example
167    
168  This tells make to run @code{guile-snarf} to produce each needed  This tells make to run @code{guile-snarf} to produce each needed
169  @file{.x} file from the corresponding @file{.c} file.  @file{.x} file from the corresponding @file{.c} file.
170    
171  @code{guile-snarf} passes all its command-line arguments directly to the  Aside from the required argument INFILE, @code{guile-snarf} passes its
172  C preprocessor, which it uses to extract the information it needs from  command-line arguments directly to the C preprocessor, which it uses to
173  the source code. this means you can pass normal compilation flags to  extract the information it needs from the source code. this means you can pass
174  @code{guile-snarf} to define preprocessor symbols, add header file  normal compilation flags to @code{guile-snarf} to define preprocessor symbols,
175  directories, and so on.  add header file directories, and so on.
176    
177  @c ---------------------------------------------------------------------------  @c ---------------------------------------------------------------------------
178  @node Macros guile-snarf recognizes  @node Macros guile-snarf recognizes
# Line 217  Also, it's a good idea to define @var{FU Line 238  Also, it's a good idea to define @var{FU
238  @xref{Subrs}, for details on argument passing and how to write C  @xref{Subrs}, for details on argument passing and how to write C
239  functions.  functions.
240    
241    @xref{guile-1.4 guile-snarf}, if you have code that relies on the guile-snarf
242    shipped with guile-1.4 (guile-snarf shipped with guile-1.6 is different).
243    
244    @c ---------------------------------------------------------------------------
245    @node guile-1.4 guile-snarf
246    @subsubsection guile-1.4 guile-snarf
247    @cindex guile-1.4 guile-snarf
248    @cindex guile-snarf, guile-1.4
249    
250    The @code{guile-snarf} included with guile-1.4 differs in behavior and usage
251    from that included with guile-1.6 and later.  This page explains the four
252    kinds of modifications code written with guile-1.4 guile-snarf in mind need to
253    undergo, in order to be completely compatible with guile-1.6 init snarfing
254    practice; and explains how to use @code{guile-snarf --compat=1.4}.
255    
256    @itemize
257    
258    @item Some of the recognized macro names have changed.
259    
260    Specifically, you need to rename:
261    
262    @itemize
263    @item SCM_VCELL to SCM_VARIABLE
264    @item SCM_GLOBAL_VCELL to SCM_GLOBAL_VARIABLE
265    @item SCM_VCELL_INIT to SCM_VARIABLE_INIT
266    @item SCM_GLOBAL_VCELL_INIT to SCM_GLOBAL_VARIABLE_INIT
267    @end itemize
268    
269    @item The macro SCM_CONST_LONG is no longer recognized.
270    
271    Proabably you can use SCM_GLOBAL_VARIABLE_INIT where you would have
272    formerly used SCM_CONST_LONG.  [fixme: needs verification]
273    
274    @item guile-snarf is no longer usable in a pipe.
275    
276    With guile-1.4 guile-snarf you had capture its output to a file, check
277    the exit value of the guile-snarf process, and delete the file if that
278    value was false.  These operations are now handled internally to
279    guile-snarf, providing you either specify the output file explicitly, or
280    use an input file name that ends in @code{.c} (in which case the output
281    filename is computed from the input filename by replacing @code{.c} with
282    @code{.x}).
283    
284    @end itemize
285    
286    If you have code that uses the old snarf macros (for example,
287    SCM_VCELL), but have installed the new guile-snarf, you can arrange for
288    the old macros to be still recognized by using the @code{--compat=1.4}
289    option.  With this option, old macros are translated to their new
290    variants on input to the modern snarfing process.  This means the .x
291    files produced will make use of @code{scm_c_define_gsubr} and friends,
292    which are ready to be compiled against the new libguile.
293    
294    Thus, @code{--compat=1.4} does not provide @emph{full} emulation, only
295    input emulation.  (The thinking is: If you have a new guile-snarf
296    installed, probably you have a new libguile installed, too, and would
297    prefer to get your old code to work with the new libguile.)
298    
299    The makefile fragment to use would look something like:
300    
301    @example
302    .c.x:
303            guile-snarf --compat=1.4 -o $@ $<
304    @end example
305    
306    After you've done a global search and replace on SCM_VCELL and friends,
307    you can remove @code{--compat=1.4} altogether (@pxref{How guile-snarf
308    works}).
309    
310  @c ---------------------------------------------------------------------------  @c ---------------------------------------------------------------------------
311  @node Doc Snarfing  @node Doc Snarfing
312  @subsection Doc Snarfing  @subsection Doc Snarfing

Legend:
Removed from v.1.1.2.2  
changed lines
  Added in v.1.1.2.3

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