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 --------------------------------------------------------------------------- |
71 |
@cindex guile-snarf invocation |
@cindex guile-snarf invocation |
72 |
@cindex guile-snarf example |
@cindex guile-snarf example |
73 |
|
|
74 |
Usage: guile-snarf [-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{-}. |
|
|
|
|
|
If there are errors during processing, delete OUTFILE and exit with |
|
|
non-zero status. |
|
|
|
|
|
If env var CPP is set, use its value instead of the C pre-processor |
|
|
determined at Guile configure-time. |
|
84 |
|
|
85 |
During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is |
During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is |
86 |
defined. You can use this to avoid including snarfer output files |
defined. You could use this to avoid including snarfer output files |
87 |
that don't yet exist by writing code like this: |
that don't yet exist by writing code like this: |
88 |
@example |
|
89 |
#ifndef SCM_MAGIC_SNARFER |
@smallexample |
90 |
#include "foo.x" |
#ifndef SCM_MAGIC_SNARFER |
91 |
|
#include "foo.x" |
92 |
#endif |
#endif |
93 |
@end example |
@end smallexample |
94 |
|
|
95 |
|
If the environment variable @code{CPP} is set, use its value instead of the |
96 |
|
C pre-processor determined at Guile configure-time. |
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. |
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 |
|
|
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 |
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 |
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 |
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 |
|
|
|
@c Here is the list of deprecated macros: |
|
|
|
|
|
@c @c reminder: sync w/ libguile/guile-snarf.in var `deprecated_list' |
|
|
@c @example |
|
|
@c SCM_CONST_LONG |
|
|
@c SCM_VCELL |
|
|
@c SCM_VCELL_INIT |
|
|
@c SCM_GLOBAL_VCELL |
|
|
@c SCM_GLOBAL_VCELL_INIT |
|
|
@c @end example |
|
|
|
|
|
@c Some versions of guile (and guile-snarf) will continue to recognize them but |
|
|
@c at some point they will no longer work. You can pass either @code{-d} or |
|
|
@c @code{-D} option to have guile-snarf warn or signal error, respectively, if |
|
|
@c any of these are found in the input file. |
|
|
|
|
241 |
@xref{How guile-snarf works}, and also libguile source, for examples. |
@xref{How guile-snarf works}, and also libguile source, for examples. |
242 |
@xref{Subrs}, for details on argument passing and how to write C |
@xref{Subrs}, for details on argument passing and how to write C |
243 |
functions. |
functions. |
244 |
|
|
245 |
@c --------------------------------------------------------------------------- |
@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 |
|
|
255 |
|
@example |
256 |
|
#define SCM_SYMBOL(c_name, scheme_name) \ |
257 |
|
static SCM c_name \ |
258 |
|
SCM_SNARF_INIT(c_name = scm_permanent_object (scm_str2symbol (scheme_name))) |
259 |
|
@end example |
260 |
|
|
261 |
|
@defmac SCM_SNARF_INIT (code) |
262 |
|
When processed normally, @code{SCM_SNARF_INIT} expands to nothing; |
263 |
|
when processed by the snarfer, it causes @var{code} to be included in |
264 |
|
the initialization action file, followed by a semicolon. |
265 |
|
@end defmac |
266 |
|
|
267 |
|
@c --------------------------------------------------------------------------- |
268 |
@node Doc Snarfing |
@node Doc Snarfing |
269 |
@subsection Doc Snarfing |
@subsection Doc Snarfing |
270 |
|
|