13.3 Executable Modules

With very few exceptions, the programs described in this chapter are implemented as executable modules, each a regular Scheme module with some stylized packaging that additionally enables the code to be invoked from the shell, as a program in its own right. In this way, we bring together two modularity paradigms: pipes and plain text streams (the Unix way); and Scheme modules and objects (the Guile way).

(Do not be afraid of the word “paradigm”, especially since we are not attempting to “shift” anything, except perhaps ignorance and sloth.)

This section describes the characteristics of an executable module so that you may easily write some for your own fun and profit. The observant reader (of code) will also note that the programs that comprise the guile-tools set share additional features described in the next section (see HVQC-MAIN).

For a quick start, see the template PROGRAM program (see guile-tools PROGRAM). You can look at its source code with the shell command:

     guile-tools --source PROGRAM

For the following examples, we use PROGRAM literally, my-prog to indicate your program, (my modules my-prog) to indicate the module name of your program, and my-entry to indicate the entry point.

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 (list of symbols) can be anything, even unrelated to the filename, but it's usually a good idea to make the last element of the module name the same as the filename in the event that you want to install the module in a place where the module system can resolve a reference to it.

  For example, if you install my-prog as DIR/my/modules/my-prog and DIR is in %load-path, your module will be accessible using (use-modules (my modules my-prog)).

  Tip: During early development, keep the module name simple (one symbol matching the filename) since typically both the PATH env var and the %load-path Scheme var include ., the current working directory.

• There must be an entry point, a procedure that takes a single list of arguments from the shell, args, the same list that would be returned by the procedure command-line. The exit value of this procedure is the exit value of the program.

  The entry point is conventionally named main, but that is not required. However, be aware that some tools may expect this name and furthermore expect that it be exported as well.

  Here is a simple definition for my-entry that displays the args and exits successfully:

            (define (my-entry args)
              (simple-format #t "args: ~S~%" args)
              #t)
  

• The beginning of the file must use a reasonable variant of this invocation sequence:

            #!/bin/sh
            exec ${GUILE-guile} -e '(my modules my-prog) my-entry' -s $0 "$@"
            !#
  

  Note that the entire argument to the -e switch is quoted to protect against shell misinterpretation. Also, there is a space between the module name and the entry point. If you name the entry point main, you can omit its specification, i.e., (my modules my-prog) is sufficient.

  The ${GUILE-guile} construct allows runtime selection of the guile interpreter either by setting the env var GUILE to the absolute filename of the interpreter; or if that is not set, by arranging the env var PATH such that the desired interpreter is found first. You can reduce this variability by substituting the absolute pathname for the guile portion of the construct, or even replacing the construct entirely. Two examples:

            exec ${GUILE-/usr/local/bin/guile} ...
            exec /usr/local/bin/guile ...
  

  In the latter case you may be able to use the meta-switch to avoid one level of program invocation (see The Meta Switch). Also, See guile-tools edit-script-header.