@code{#include} into an initialization function.
@menu
-* How guile-snarf works:: Using @code{guile-snarf}, with example.
-* Macros guile-snarf recognizes:: How to mark up code for @code{guile-snarf}.
+* How guile-snarf works:: Using @code{guile-snarf}, with example.
+* Macros guile-snarf recognizes:: How to mark up code for @code{guile-snarf}.
+* Writing your own snarfing macros:: How to define new things to snarf.
@end menu
@c ---------------------------------------------------------------------------
@cindex guile-snarf invocation
@cindex guile-snarf example
-Usage: guile-snarf [-d | -D] [-o OUTFILE] INFILE [CPP-OPTIONS ...]
+Usage: guile-snarf [-o @var{outfile}] [@var{cpp-args} ...]
-What @code{guile-snarf} does:
+The @code{guile-snarf} program will extract initialization actions to
+@var{outfile} or to standard output when no @var{outfile} has been
+specified or when @var{outfile} is @code{-}. The C preprocessor is
+called with @var{cpp-args} (which usually include an input file) and
+the output is filtered to extract the initialization actions.
-Process INFILE using the C pre-processor and some other programs.
-Write output to a file named OUTFILE or to the standard output when no
-OUTFILE has been specified or when OUTFILE is @code{-}. When writing
-to a file, ignore lines from the input matching the following grep(1)
-regular expression:
+If there are errors during processing, @var{outfile} is deleted and the
+program exits with non-zero status.
-@example
- ^#include ".*OUTFILE"
-@end example
-
-If there are errors during processing, delete OUTFILE and exit with
-non-zero status.
+During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is
+defined. You could use this to avoid including snarfer output files
+that don't yet exist by writing code like this:
-Optional arg "-d" means grep INFILE for deprecated macros and
-issue a warning if any are found. Alternatively, "-D" means
-do the same thing but signal error and exit with non-zero status.
+@smallexample
+#ifndef SCM_MAGIC_SNARFER
+#include "foo.x"
+#endif
+@end smallexample
-If env var CPP is set, use its value instead of the C pre-processor
-determined at Guile configure-time.
-
-During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is
-defined.
+If the environment variable @code{CPP} is set, use its value instead of the
+C pre-processor determined at Guile configure-time.
@xref{Macros guile-snarf recognizes}, for a list of the special (some would
say magic) cpp macros you can use, including the list of deprecated macros.
"Clear the image.")
#define FUNC_NAME s_clear_image
@{
- /* C code to clear the image... */
+ /* C code to clear the image in @code{image_smob}... */
@}
#undef FUNC_NAME
The @code{SCM_DEFINE} declaration says that the C function
@code{clear_image} implements a Scheme subr called @code{clear-image},
-which takes one required argument (type @code{SCM} named
-@code{image_smob}), no optional arguments, and no tail argument.
+which takes one required argument (of type @code{SCM} and named
+@code{image_smob}), no optional arguments, and no rest argument.
@xref{Doc Snarfing}, for info on the docstring.
This works in concert with @code{FUNC_NAME} to also define a static
need to execute the following command to prepare this file for compilation:
@example
-guile-snarf image-type.c
+guile-snarf -o image-type.x image-type.c
@end example
This scans @file{image-type.c} for @code{SCM_DEFINE}
scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
@end example
-When compiled normally, @code{SCM_DEFINE} is a macro which expands to a
-declaration of the @code{s_clear_image} string.
+When compiled normally, @code{SCM_DEFINE} is a macro which expands to
+a declaration of the @code{s_clear_image} string and the function
+header for @code{clear_image}.
Note that the output file name matches the @code{#include} from the
input file. Also, you still need to provide all the same information
This tells make to run @code{guile-snarf} to produce each needed
@file{.x} file from the corresponding @file{.c} file.
-Aside from the required argument INFILE, @code{guile-snarf} passes its
-command-line arguments directly to the C preprocessor, which it uses to
-extract the information it needs from the source code. this means you can pass
-normal compilation flags to @code{guile-snarf} to define preprocessor symbols,
-add header file directories, and so on.
+The program @code{guile-snarf} passes its command-line arguments
+directly to the C preprocessor, which it uses to extract the
+information it needs from the source code. this means you can pass
+normal compilation flags to @code{guile-snarf} to define preprocessor
+symbols, add header file directories, and so on.
@c ---------------------------------------------------------------------------
@node Macros guile-snarf recognizes
is a expression suitable for initializing a new variable.
For procedures, you can use @code{SCM_DEFINE} for most purposes. Use
-@code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't want
-to be bothered with docstrings. Use @code{SCM_GPROC} for generic
-functions (@pxref{GOOPS,,,goops}). All procedures are declared
-@code{static} with return type @code{SCM}.
+@code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't
+want to be bothered with docstrings. Use @code{SCM_GPROC} for generic
+functions (@pxref{GOOPS,,,goops}). All procedures are declared with
+return type @code{SCM}.
For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
-symbols, and so on). The "_GLOBAL_" variants omit @code{static}
-declaration.
+symbols, and so on). Without "_GLOBAL_", the declarations are
+@code{static}.
All these macros should be used at top-level, outside function bodies.
Also, it's a good idea to define @var{FUNC_NAME} immediately after using
@code{SCM_DEFINE} (and similar), and then the function body, and then
@code{#undef FUNC_NAME}.
-Here is the list of deprecated macros:
+@xref{How guile-snarf works}, and also libguile source, for examples.
+@xref{Subrs}, for details on argument passing and how to write C
+functions.
+
+@c ---------------------------------------------------------------------------
+@node Writing your own snarfing macros
+@subsubsection Writing your own snarfing macros
+
+When you want to use the general snarfing machanism, but none of the
+provided macros fits your need, you can use the macro
+@code{SCM_SNARF_INIT}.
+
+For example, the @code{SCM_SYMBOL} macro can be defined like this:
-@c reminder: sync w/ libguile/guile-snarf.in var `deprecated_list'
@example
- SCM_CONST_LONG
- SCM_VCELL
- SCM_VCELL_INIT
- SCM_GLOBAL_VCELL
- SCM_GLOBAL_VCELL_INIT
+#define SCM_SYMBOL(c_name, scheme_name) \
+static SCM c_name \
+SCM_SNARF_INIT(c_name = scm_permanent_object (scm_str2symbol (scheme_name)))
@end example
-Some versions of guile (and guile-snarf) will continue to recognize them but
-at some point they will no longer work. You can pass either @code{-d} or
-@code{-D} option to have guile-snarf warn or signal error, respectively, if
-any of these are found in the input file.
-
-@xref{How guile-snarf works}, and also libguile source, for examples.
-@xref{Subrs}, for details on argument passing and how to write C
-functions.
+@defmac SCM_SNARF_INIT (code)
+When processed normally, @code{SCM_SNARF_INIT} expands to nothing;
+when processed by the snarfer, it causes @var{code} to be included in
+the initialization action file, followed by a semicolon.
+@end defmac
@c ---------------------------------------------------------------------------
@node Doc Snarfing
HCoop / bpt / guile.git / commitdiff