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