mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-06-12 14:50:19 +02:00
(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".
This commit is contained in:
Thien-Thi Nguyen
parent
e07983b4b4
commit
fc17ed5b72
1 changed files with 257 additions and 10 deletions
|
|
@ -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 <libguile.h>
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue