Miscellaneous Tools
*******************

Programming is more fun with a good tools.  This chapter describes snarfing tools, and the 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!

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 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 guile-snarf which does 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).

Init Snarfing with guile-snarf
------------------------------

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 scm_c_define_gsubr function; a C function published in this way is called a subr.  If you have many subrs to publish, it can sometimes be annoying to keep the list of calls to 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 scm_c_define_gsubr.

Guile provides the 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; guile-snarf will extract this information from your source code, and automatically generate a file of calls to scm_c_define_gsubr which you can #include into an initialization function.

How guile-snarf works
.....................

Usage: guile-snarf [-o OUTFILE] [CPP-ARGS ...]

The guile-snarf program will extract initialization actions to OUTFILE or to standard output when no OUTFILE has been specified or when OUTFILE is -.  The C preprocessor is called with CPP-ARGS (which usually include an input file) and the output is filtered to extract the initialization actions.

If there are errors during processing, OUTFILE is deleted and the program exits with non-zero status.

During snarfing, the pre-processor macro 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:

     #ifndef SCM_MAGIC_SNARFER
     #include "foo.x"
     #endif

If the environment variable CPP is set, use its value instead of the C pre-processor determined at Guile configure-time.

See 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 clear-image, implemented by the C function clear_image:

     #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 in image_smob... */
     }
     #undef FUNC_NAME

     void
     init_image_type ()
     {
     #include "image-type.x"
     }

The SCM_DEFINE declaration says that the C function clear_image implements a Scheme subr called clear-image, which takes one required argument (of type SCM and named image_smob), no optional arguments, and no rest argument. See Doc Snarfing, for info on the docstring.

This works in concert with FUNC_NAME to also define a static array of characters named s_clear_image, initialized to the string "clear-image".  The body of 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 image-type.c, you will need to execute the following command to prepare this file for compilation:

     guile-snarf -o image-type.x image-type.c

This scans image-type.c for SCM_DEFINE declarations, and writes to image-type.x the output:

     scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);

When compiled normally, SCM_DEFINE is a macro which expands to a declaration of the s_clear_image string and the function header for clear_image.

Note that the output file name matches the #include from the input file.  Also, you still need to provide all the same information you would if you were using 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 guile-snarf must process, you should consider using a fragment like the following in your Makefile:

     snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
     .SUFFIXES: .x
     .c.x:
     	guile-snarf -o $@ $< $(snarfcppopts)

This tells make to run guile-snarf to produce each needed .x file from the corresponding .c file.

The program 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 guile-snarf to define preprocessor symbols, add header file directories, and so on.

Macros guile-snarf recognizes
.............................

Here are the macros you can use in your source code from which guile-snarf can construct initialization code:

     /* 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)

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 \n\ at eol for multi-line); FNAME is a C-language identifier, CFN and GF and C_NAME likewise; PRIMNAME is a string denoting the name available to Scheme code, STR and SCHEME_NAME likewise; RANAME is the name of the static string (must match that declared by the associated definition of cpp macro FUNC_NAME); ARGLIST is an argument list (in parentheses); and lastly, INIT_VAL is a expression suitable for initializing a new variable.

For procedures, you can use SCM_DEFINE for most purposes.  Use SCM_PROC along with SCM_REGISTER_PROC when you don't want to be bothered with docstrings.  Use SCM_GPROC for generic functions (see Creating Generic Functions).  All procedures are declared with return type SCM.

For everything else, use the appropriate macro (SCM_SYMBOL for symbols, and so on).  Without "_GLOBAL_", the declarations are static.

All these macros should be used at top-level, outside function bodies. Also, it's a good idea to define FUNC_NAME immediately after using SCM_DEFINE (and similar), and then the function body, and then #undef FUNC_NAME.

See How guile-snarf works, and also libguile source, for examples. See Subrs, for details on argument passing and how to write C functions.

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 SCM_SNARF_INIT.

For example, the SCM_SYMBOL macro can be defined like this:

     #define SCM_SYMBOL(c_name, scheme_name) \
     static SCM c_name \
     SCM_SNARF_INIT(c_name = scm_permanent_object (scm_str2symbol (scheme_name)))

 -- Macro: SCM_SNARF_INIT (code)
     When processed normally, SCM_SNARF_INIT expands to nothing; when processed by the snarfer, it causes CODE to be included in the initialization action file, followed by a semicolon.

Doc Snarfing
------------

In addition to init snarfing (see 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 guile-procedures.txt which is installed, and subsequently used by module (ice-9 documentation).

Here is a list of what does what according to libguile/Makefile.am:

  * guile-snarf-docs runs cpp defining SCM_MAGIC_SNARF_DOCS

  * guile_filter_doc_snarfage parses guile-snarf-docs output to produce .doc

  * ../scripts/snarf-check-and-output-texi makes guile.texi

  * ../scripts/snarf-check-and-output-texi makes guile-procedures.txt

  * guile-func-name-check checks source snarf-syntax integrity (optional?)

Note that for guile-1.4, a completely different approach was used!  All this is rather byzantine, so for now NO doc snarfing programs are installed.

[fixme: Document further once doc snarfing is tamed somewhat. --ttn]

Executable Modules
==================

When Guile is installed, in addition to the (ice-9 FOO) modules, a set of guild modules (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 script in this context to mean the same thing.

As a convenience, the guild wrapper program is installed along w/ 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:

     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):
      --scriptsdir DIR    -- Look in DIR for scripts
      --guileversion VERS -- Look in $pkgdatadir/VERS/scripts for scripts
      --source            -- Display PROGRAM source (ignore ARGS) to stdout

The modules are self-documenting.  For example, to see the documentation for lint, use one (or both) of the shell commands:

     guild display-commentary '(scripts lint)'
     guild --source lint

The rest of this section describes the packaging that goes into creating an executable module.  Feel free to skip to the next chapter.

Writing Executable Modules
--------------------------

See template file PROGRAM for a quick start.

Programs must follow the guild convention, documented here:

  * 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:

          (define-module (scripts PROGRAM)
            #:export (PROGRAM))

     Feel free to export other definitions useful in the module context.

  * There must be the alias:

          (define main PROGRAM)

     However, `main' must NOT be exported.

Following these conventions allows the program file to be used as module (scripts PROGRAM) in addition to being invoked by guild.  Please also include a helpful Commentary section w/ some usage info.