diff options
Diffstat (limited to 'doc/ref/tools.texi')
-rw-r--r-- | doc/ref/tools.texi | 386 |
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 |