mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-05-03 13:20:26 +02:00
97 lines
2.8 KiB
Text
97 lines
2.8 KiB
Text
@page
|
|
@node Executable Modules
|
|
@chapter Executable Modules
|
|
@cindex guile-tools
|
|
@cindex modules, executable
|
|
@cindex executable modules
|
|
@cindex scripts
|
|
|
|
When Guile is installed, in addition to the @code{(ice-9 FOO)} modules,
|
|
a set of @dfn{executable modules} @code{(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 @dfn{script} in this context to mean the
|
|
same thing.
|
|
|
|
As a convenience, the @code{guile-tools} wrapper program is installed along w/
|
|
@code{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:
|
|
|
|
@example
|
|
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
|
|
@end example
|
|
|
|
The modules are self-documenting. For example, to see the documentation for
|
|
@code{lint}, use one (or both) of the shell commands:
|
|
|
|
@example
|
|
guile-tools display-commentary '(scripts lint)'
|
|
guile-tools --source lint
|
|
@end example
|
|
|
|
The rest of this chapter describes the packaging that goes into creating an
|
|
executable module. Feel free to skip to the next chapter.
|
|
|
|
@section Writing Executable Modules
|
|
|
|
@c adapted from scripts/README
|
|
|
|
See template file @code{PROGRAM} for a quick start.
|
|
|
|
Programs must follow the @dfn{executable module} convention, documented here:
|
|
|
|
@itemize
|
|
|
|
@item
|
|
The file name must not end in ".scm".
|
|
|
|
@item
|
|
The file must be executable (chmod +x).
|
|
|
|
@item
|
|
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:
|
|
|
|
@example
|
|
(define-module (scripts PROGRAM)
|
|
:export (PROGRAM))
|
|
@end example
|
|
|
|
Feel free to export other definitions useful in the module context.
|
|
|
|
@item
|
|
There must be the alias:
|
|
|
|
@example
|
|
(define main PROGRAM)
|
|
@end example
|
|
|
|
However, `main' must NOT be exported.
|
|
|
|
@item
|
|
The beginning of the file must use the following invocation sequence:
|
|
|
|
@example
|
|
#!/bin/sh
|
|
main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')'
|
|
exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@"
|
|
!#
|
|
@end example
|
|
|
|
@end itemize
|
|
|
|
Following these conventions allows the program file to be used as module
|
|
@code{(scripts PROGRAM)} in addition to as a standalone executable. Please
|
|
also include a helpful Commentary section w/ some usage info.
|
|
|
|
@c tools.texi ends here
|