diff --git a/doc/ref/tools.texi b/doc/ref/tools.texi index 45ad1efb0..e3e588117 100644 --- a/doc/ref/tools.texi +++ b/doc/ref/tools.texi @@ -60,8 +60,9 @@ generate a file of calls to @code{scm_c_define_gsubr} which you can @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 --------------------------------------------------------------------------- @@ -70,28 +71,29 @@ generate a file of calls to @code{scm_c_define_gsubr} which you can @cindex guile-snarf invocation @cindex guile-snarf example -Usage: guile-snarf [-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{-}. - -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. +If there are errors during processing, @var{outfile} is deleted and the +program exits with non-zero status. During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is -defined. You can use this to avoid including snarfer output files +defined. You could use this to avoid including snarfer output files that don't yet exist by writing code like this: -@example -#ifndef SCM_MAGIC_SNARFER -#include "foo.x" + +@smallexample +#ifndef SCM_MAGIC_SNARFER +#include "foo.x" #endif -@end example +@end smallexample + +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. @@ -108,7 +110,7 @@ SCM_DEFINE (clear_image, "clear-image", 1, 0, 0, "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 @@ -122,8 +124,8 @@ init_image_type () 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 @@ -146,8 +148,9 @@ declarations, and writes to @file{image-type.x} the output: 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 @@ -168,11 +171,11 @@ snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) 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 @@ -221,40 +224,46 @@ ARGLIST is an argument list (in parentheses); and lastly, @var{init_val} 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}. -@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. - @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: + +@example +#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 + +@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 @subsection Doc Snarfing