(guile.info.gz) Executable Modules

Info Catalog

(guile.info.gz) Snarfing

(guile.info.gz) 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.
 

Info Catalog

(guile.info.gz) Snarfing

(guile.info.gz) Miscellaneous Tools