From fc17ed5b72633016a14be2f3d026992ea0a197cb Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Fri, 8 Mar 2002 21:20:31 +0000 Subject: [PATCH] (Miscellaneous Tools): New node/chapter. (Snarfing, Init Snarfing with guile-snarf, How guile-snarf works, Macros guile-snarf recognizes, Doc Snarfing): New nodes/(sub)sections. (Executable Modules): Now a section under "Miscellaneous Tools". --- doc/ref/tools.texi | 267 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 257 insertions(+), 10 deletions(-) diff --git a/doc/ref/tools.texi b/doc/ref/tools.texi index 3629b93b1..18448bfd8 100644 --- a/doc/ref/tools.texi +++ b/doc/ref/tools.texi @@ -1,6 +1,251 @@ @page +@node Miscellaneous Tools +@chapter Miscellaneous Tools + +Programming is more fun with a good tools. This chapter describes snarfing +tools, and the @code{guile-tools} program which can be used to invoke the rest +of the tools (which are self-documenting). Some of these are used in Guile +development, too. Imagine that! + +@menu +* Snarfing:: Grepping the source in various ways. +* Executable Modules:: Modules callable via guile-tools. +@end menu + +@c --------------------------------------------------------------------------- +@node Snarfing +@section Snarfing +@cindex snarfing + +Because it's easier to maintain documentation, code, and other metainfo in one +source file than in many files, there have evolved many methods for grepping +source to lift and separate these kinds of info, in the process generating +docs or fragments of source or what have you. This is known generally as +@dfn{snarfing}, which comes from the verb ``to snarf'', here meaning ``to +unceremoniously extract information from a somewhat unwilling source.'' + +This section documents the installed program @code{guile-snarf} which does +@dfn{init snarfing}, and also touches upon guile's doc snarfing process which +is not yet finalized (i.e., doc snarfing programs are not installed at this +time). + +@menu +* Init Snarfing with guile-snarf:: Exposing C subrs and friends to Scheme. +* Doc Snarfing:: Generating GDFv2 or texi from source. +@end menu + +@c --------------------------------------------------------------------------- +@node Init Snarfing with guile-snarf +@subsection Init Snarfing with guile-snarf +@c NOTE: This node and two subnodes are adapted from ../sources/snarf.texi. +@cindex snarfing, init +@cindex primitive functions +@cindex subrs, defining + +When writing C code for use with Guile, you typically define a set of C +functions, and then make some of them visible to the Scheme world by +calling the @code{scm_c_define_gsubr} function; a C function published in +this way is called a @dfn{subr}. If you have many subrs to publish, it +can sometimes be annoying to keep the list of calls to +@code{scm_c_define_gsubr} in sync with the list of function definitions. +Frequently, a programmer will define a new subr in C, recompile the +application, and then discover that the Scheme interpreter cannot see +the subr, because of a missed call to @code{scm_c_define_gsubr}. + +Guile provides the @code{guile-snarf} command to manage this problem. +Using this tool, you can keep all the information needed to define the +subr alongside the function definition itself; @code{guile-snarf} will +extract this information from your source code, and automatically +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}. +@end menu + +@c --------------------------------------------------------------------------- +@node How guile-snarf works +@subsubsection How guile-snarf works +@cindex guile-snarf invocation +@cindex guile-snarf example + +Usage: @code{guile-snarf} [CPP-OPTIONS ...] SOURCE.c + +@code{guile-snarf} uses cpp to process SOURCE.c, writing C language +initialization calls to standard output, based on special (some would say +magic) cpp macros found in the input (@pxref{Macros guile-snarf recognizes}). + +For example, here is how you might define a new subr called +@code{clear-image}, implemented by the C function @code{clear_image}: + +@example +@group +#include + +SCM_DEFINE (clear_image, "clear-image", 1, 0, 0, + (SCM image_smob), + "Clear the image.") +#define FUNC_NAME s_clear_image +@{ + /* C code to clear the image... */ +@} +#undef FUNC_NAME + +void +init_image_type () +@{ +#include "image-type.x" +@} +@end group +@end example + +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. +@xref{Doc Snarfing}, for info on the docstring. + +This works in concert with @code{FUNC_NAME} to also define a static +array of characters named @code{s_clear_image}, initialized to the +string "clear-image". The body of @code{clear_image} may use the array +in error messages, instead of writing out the literal string; this may +save string space on some systems. + +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 > image-type.x +@end example + +This scans @file{image-type.c} for @code{SCM_DEFINE} +declarations, and writes to @file{image-type.x} the output: + +@example +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. + +Note that the output file name matches the @code{#include} from the +input file. Also, you still need to provide all the same information +you would if you were using @code{scm_c_define_gsubr} yourself, but you +can place the information near the function definition itself, so it is +less likely to become incorrect or out-of-date. + +If you have many files that @code{guile-snarf} must process, you should +consider using a rule like the following in your Makefile: + +@example +.SUFFIXES: .x +.c.x: + guile-snarf $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) $< > $@@ +@end example + +This tells make to run @code{guile-snarf} to produce each needed +@file{.x} file from the corresponding @file{.c} file. + +@code{guile-snarf} passes all 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 +@subsubsection Macros guile-snarf recognizes +@cindex guile-snarf recognized macros + +Here are the macros you can use in your source code from which +@code{guile-snarf} can construct initialization code: + +@example +/* procedures */ +SCM_DEFINE (FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING) + +SCM_PROC (RANAME, STR, REQ, OPT, VAR, CFN) +SCM_REGISTER_PROC (RANAME, STR, REQ, OPT, VAR, CFN) + +SCM_GPROC (RANAME, STR, REQ, OPT, VAR, CFN, GF) + +/* everything else */ +SCM_SYMBOL (c_name, scheme_name) +SCM_GLOBAL_SYMBOL (c_name, scheme_name) + +SCM_KEYWORD (c_name, scheme_name) +SCM_GLOBAL_KEYWORD (c_name, scheme_name) + +SCM_VARIABLE (c_name, scheme_name) +SCM_GLOBAL_VARIABLE (c_name, scheme_name) + +SCM_VARIABLE_INIT (c_name, scheme_name, init_val) +SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, init_val) +@end example + +@c i like things dense, but maybe someone else will reformat this +@c into an easier-to-read list. also, all-upcase to me is a form +@c of quoting, so @var{} is not necessary there. --ttn +REQ and OPT are numbers indicating required and optional argument +counts, respectively; VAR is a number that, if non-zero, means the +function will accept any remaining arguments as a list; DOCSTRING is a +string (use @code{\n\} at eol for multi-line); FNAME is a C-language +identifier, CFN and GF and @var{c_name} likewise; PRIMNAME is a string +denoting the name available to Scheme code, STR and @var{scheme_name} +likewise; RANAME is the name of the static string (must match that +declared by the associated definition of cpp macro @var{FUNC_NAME}); +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}. + +For everything else, use the appropriate macro (@code{SCM_SYMBOL} for +symbols, and so on). The "_GLOBAL_" variants omit @code{static} +declaration. + +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}. + +@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 Doc Snarfing +@subsection Doc Snarfing + +In addition to init snarfing (@pxref{Init Snarfing with guile-snarf}), +the libguile sources are also subject to doc snarfing, by programs that +are included in the distribution (but not installed at this time). The +output is the file @file{guile-procedures.txt} which is installed, and +subsequently used by module @code{(ice-9 documentation)}. + +Here is a list of what does what according to @file{libguile/Makefile.am}: + +@itemize +@item guile-snarf-docs runs cpp defining SCM_MAGIC_SNARF_DOCS +@item guile_filter_doc_snarfage parses guile-snarf-docs output to produce .doc +@item ../scripts/snarf-check-and-output-texi makes guile.texi +@item ../scripts/snarf-check-and-output-texi makes guile-procedures.txt +@item guile-func-name-check checks source snarf-syntax integrity (optional?) +@item guile-doc-snarf calls guile-snarf-docs (to make .doc) and guile-snarf +@end itemize + +Note that for guile-1.4, a completely different approach was used! All this +is rather byzantine, so for now @emph{NO} doc snarfing programs are installed. + +[fixme: Document further once doc snarfing is tamed somewhat. --ttn] + +@c --------------------------------------------------------------------------- @node Executable Modules -@chapter Executable Modules +@section Executable Modules @cindex guile-tools @cindex modules, executable @cindex executable modules @@ -13,6 +258,8 @@ that it can be called as a program in its own right, from the shell. For this reason, we sometimes use the term @dfn{script} in this context to mean the same thing. +@c wow look at this hole^! variable-width font users eat your heart out. + As a convenience, the @code{guile-tools} wrapper program is installed along w/ @code{guile}; it knows where a particular module is installed and calls it passing its args to the program. The result is that you need not augment your @@ -38,10 +285,10 @@ guile-tools display-commentary '(scripts lint)' guile-tools --source lint @end example -The rest of this chapter describes the packaging that goes into creating an +The rest of this section describes the packaging that goes into creating an executable module. Feel free to skip to the next chapter. -@section Writing Executable Modules +@subsection Writing Executable Modules @c adapted from scripts/README @@ -63,8 +310,8 @@ signature "(PROGRAM . args)" must be exported. Basically, use some variant of the form: @example - (define-module (scripts PROGRAM) - :export (PROGRAM)) +(define-module (scripts PROGRAM) + :export (PROGRAM)) @end example Feel free to export other definitions useful in the module context. @@ -73,7 +320,7 @@ Feel free to export other definitions useful in the module context. There must be the alias: @example - (define main PROGRAM) +(define main PROGRAM) @end example However, `main' must NOT be exported. @@ -82,10 +329,10 @@ However, `main' must NOT be exported. The beginning of the file must use the following invocation sequence: @example - #!/bin/sh - main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')' - exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@" - !# +#!/bin/sh +main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')' +exec $@{GUILE-guile@} -l $0 -c "(apply $main (cdr (command-line)))" "$@@" +!# @end example @end itemize