summaryrefslogtreecommitdiff
path: root/doc/ref/tools.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/tools.texi')
-rw-r--r--doc/ref/tools.texi386
1 files changed, 0 insertions, 386 deletions
diff --git a/doc/ref/tools.texi b/doc/ref/tools.texi
deleted file mode 100644
index 061e34477..000000000
--- a/doc/ref/tools.texi
+++ /dev/null
@@ -1,386 +0,0 @@
-@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: guile-snarf [-d | -D] [-o OUTFILE] INFILE [CPP-OPTIONS ...]
-
-What @code{guile-snarf} does:
-
-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{-}. When writing
-to a file, ignore lines from the input matching the following grep(1)
-regular expression:
-
-@example
- ^#include ".*OUTFILE"
-@end example
-
-If there are errors during processing, delete OUTFILE and exit with
-non-zero status.
-
-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.
-
-If env var CPP is set, use its value instead of the C pre-processor
-determined at Guile configure-time.
-
-During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is
-defined.
-
-@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.
-
-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
-@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 fragment like the following in your Makefile:
-
-@example
-snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
-.SUFFIXES: .x
-.c.x:
- 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.
-
-@c ---------------------------------------------------------------------------
-@node Macros guile-snarf recognizes
-@subsubsection Macros guile-snarf recognizes
-@cindex guile-snarf recognized macros
-@cindex guile-snarf deprecated 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}.
-
-Here is the list of deprecated macros:
-
-@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
-@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.
-
-@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
-@section Executable Modules
-@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.
-
-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
-PATH. Usage is straightforward:
-
-@example
-guile-tools --help
-guile-tools --version
-guile-tools [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):
- --scriptsdir DIR -- Look in DIR for scripts
- --guileversion VERS -- Look in $pkgdatadir/VERS/scripts for scripts
- --source -- Display PROGRAM source (ignore ARGS) to stdout
-@end example
-
-The modules are self-documenting. For example, to see the documentation for
-@code{lint}, use one (or both) of the shell commands:
-
-@example
-guile-tools display-commentary '(scripts lint)'
-guile-tools --source lint
-@end example
-
-The rest of this section describes the packaging that goes into creating an
-executable module. Feel free to skip to the next chapter.
-
-@subsection Writing Executable Modules
-
-@c adapted from scripts/README
-
-See template file @code{PROGRAM} for a quick start.
-
-Programs must follow the @dfn{executable module} 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
-of the form:
-
-@example
-(define-module (scripts PROGRAM)
- :export (PROGRAM))
-@end example
-
-Feel free to export other definitions useful in the module context.
-
-@item
-There must be the alias:
-
-@example
-(define main PROGRAM)
-@end example
-
-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
-also include a helpful Commentary section w/ some usage info.
-
-@c tools.texi ends here