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 --------------------------------------------------------------------------- |
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}: |
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} |
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 |
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 |