mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-22 20:40:29 +02:00
Code Activity

(How guile-snarf works): Updated.

Browse source 
(Writing your own snarfing macros): New.
This commit is contained in:
Marius Vollmer 2002-10-03 15:31:50 +00:00
parent 2c3431d622
commit fda4544f10
1 changed files with 59 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

109
doc/ref/tools.texi
View file

@ -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