X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/033aa07c016786b1b2a2b52cb7bc9ec85b4ccee4..cb62d8e55681e37c5f64d31626561361720fdcda:/doc/ref/tools.texi diff --git a/doc/ref/tools.texi b/doc/ref/tools.texi index 061e34477..f2116dd71 100644 --- a/doc/ref/tools.texi +++ b/doc/ref/tools.texi @@ -1,3 +1,9 @@ +@c -*-texinfo-*- +@c This is part of the GNU Guile Reference Manual. +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 +@c Free Software Foundation, Inc. +@c See the file guile.texi for copying conditions. + @page @node Miscellaneous Tools @chapter Miscellaneous Tools @@ -60,8 +66,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,32 +77,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 [-d | -D] [-o OUTFILE] INFILE [CPP-OPTIONS ...] - -What @code{guile-snarf} does: - -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: +Usage: guile-snarf [-o @var{outfile}] [@var{cpp-args} ...] -@example - ^#include ".*OUTFILE" -@end example +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. -If there are errors during processing, delete OUTFILE and exit with -non-zero status. +If there are errors during processing, @var{outfile} is deleted and the +program exits with non-zero status. -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. +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: -If env var CPP is set, use its value instead of the C pre-processor -determined at Guile configure-time. +@smallexample +#ifndef SCM_MAGIC_SNARFER +#include "foo.x" +#endif +@end smallexample -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. @@ -112,7 +116,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 @@ -126,8 +130,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 @@ -140,7 +144,7 @@ Assuming the text above lives in a file named @file{image-type.c}, you will 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} @@ -150,8 +154,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 @@ -166,17 +171,17 @@ consider using a fragment like the following in your Makefile: snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) .SUFFIXES: .x .c.x: - guile-snarf -o $@ $< $(snarfcppopts) + guile-snarf -o $@@ $< $(snarfcppopts) @end example 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 @@ -225,39 +230,45 @@ 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{Creating Generic Functions,,, 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