Executable Modules
******************

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

As a convenience, the guile-tools 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:

     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

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

     guile-tools display-commentary '(scripts lint)'
     guile-tools --source lint

The rest of this chapter 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 executable module convention, documented here:

  * The file name must not end in ".scm".

  * The file must be executable (chmod +x).

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

  * The beginning of the file must use the following invocation sequence:

            #!/bin/sh
            main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')'
            exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$
            !#

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