@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011, 2014
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@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
+tools, and the @code{guild} 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.
+* Executable Modules:: Modules callable via guild.
@end menu
@c ---------------------------------------------------------------------------
#include <libguile.h>
SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
- (SCM image_smob),
+ (SCM image),
"Clear the image.")
#define FUNC_NAME s_clear_image
@{
- /* C code to clear the image in @code{image_smob}... */
+ /* C code to clear the image in @code{image}... */
@}
#undef FUNC_NAME
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 (of type @code{SCM} and named
-@code{image_smob}), no optional arguments, and no rest argument.
-@xref{Doc Snarfing}, for info on the docstring.
+@code{image}), 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
array of characters named @code{s_clear_image}, initialized to the
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{Creating Generic Functions,,, goops, GOOPS}). All
-procedures are declared with return type @code{SCM}.
+functions (@pxref{Creating Generic Functions}). All procedures are
+declared with return type @code{SCM}.
For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
symbols, and so on). Without "_GLOBAL_", the declarations are
@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
+When you want to use the general snarfing mechanism, but none of the
provided macros fits your need, you can use the macro
@code{SCM_SNARF_INIT}.
@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
@c ---------------------------------------------------------------------------
@node Executable Modules
@section Executable Modules
+@cindex guild
@cindex guile-tools
@cindex modules, executable
@cindex executable modules
@cindex scripts
-When Guile is installed, in addition to the @code{(ice-9 FOO)} modules,
-a set of @dfn{executable modules} @code{(scripts BAR)} is also installed.
-Each is a regular Scheme module that has some additional packaging so
-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.
+When Guile is installed, in addition to the @code{(ice-9 FOO)} modules, a set
+of @dfn{guild modules} @code{(scripts BAR)} is also installed. Each is
+a regular Scheme module that has some additional packaging so that it can be
+used by guild, 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/
+As a convenience, the @code{guild} wrapper program is installed along with
@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
-PATH. Usage is straightforward:
+@code{PATH}. Usage is straightforward:
@example
-guile-tools --help
-guile-tools --version
-guile-tools [OPTION] PROGRAM [ARGS ...]
+guild --help
+guild --version
+guild [OPTION] PROGRAM [ARGS ...]
If PROGRAM is "list" or omitted, display contents of scripts dir, otherwise
PROGRAM is run w/ ARGS. Options (only one of which may be used at a time):
@code{lint}, use one (or both) of the shell commands:
@example
-guile-tools display-commentary '(scripts lint)'
-guile-tools --source lint
+guild display-commentary '(scripts lint)'
+guild --source lint
@end example
The rest of this section describes the packaging that goes into creating an
See template file @code{PROGRAM} for a quick start.
-Programs must follow the @dfn{executable module} convention, documented here:
+Programs must follow the @dfn{guild} convention, documented here:
@itemize
-@item
-The file name must not end in ".scm".
-
-@item
-The file must be executable (chmod +x).
-
@item
The module name must be "(scripts PROGRAM)". A procedure named PROGRAM w/
signature "(PROGRAM . args)" must be exported. Basically, use some variant
@example
(define-module (scripts PROGRAM)
- :export (PROGRAM))
+ #:export (PROGRAM))
@end example
Feel free to export other definitions useful in the module context.
However, `main' must NOT be exported.
-@item
-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)))" "$@@"
-!#
-@end example
-
@end itemize
Following these conventions allows the program file to be used as module
-@code{(scripts PROGRAM)} in addition to as a standalone executable. Please
+@code{(scripts PROGRAM)} in addition to being invoked by guild. Please
also include a helpful Commentary section w/ some usage info.
@c tools.texi ends here
HCoop / bpt / guile.git / blobdiff