Node:Executable Modules, Previous:Snarfing, Up:Miscellaneous Tools

13.2 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 section describes the packaging that goes into creating an executable module. Feel free to skip to the next chapter.

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