+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@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.
+
@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
+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 ---------------------------------------------------------------------------
@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 ---------------------------------------------------------------------------
@cindex guile-snarf invocation
@cindex guile-snarf example
-Usage: guile-snarf [-d | -D] [-o OUTFILE] INFILE [CPP-OPTIONS ...]
-
-What @code{guile-snarf} does:
+Usage: guile-snarf [-o @var{outfile}] [@var{cpp-args} ...]
-Process INFILE using the C pre-processor and some other programs.
-Write output to a file, named OUTFILE if specified, or STEM.x if
-INFILE looks like STEM.c and no OUTFILE is specified. Ignore
-lines from the input matching grep(1) regular expression:
+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.
-@example
- ^#include ".*OUTFILE"
-@end example
+If there are errors during processing, @var{outfile} is deleted and the
+program exits with non-zero status.
-If there are errors during processing, delete OUTFILE 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:
-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.
+@smallexample
+#ifndef SCM_MAGIC_SNARFER
+#include "foo.x"
+#endif
+@end smallexample
-If env var CPP is set, use its value instead of the C pre-processor
-determined at Guile configure-time.
+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.
#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... */
+ /* 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 (type @code{SCM} named
-@code{image_smob}), no optional arguments, and no tail argument.
-@xref{Doc Snarfing}, for info on the docstring.
+which takes one required argument (of type @code{SCM} and named
+@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
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}
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
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
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}). 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 mechanism, 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
@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.
-
-@c wow look at this hole^! variable-width font users eat your heart out.
+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.
-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