From a3c51cc8299da7c69f8a4c2a6f2d65608be63c67 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Wed, 6 Mar 2002 02:45:26 +0000 Subject: [PATCH 1/5] (ice9_sources): Add ftw.scm. --- ice-9/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ice-9/Makefile.am b/ice-9/Makefile.am index 721d08200..236ca62c6 100644 --- a/ice-9/Makefile.am +++ b/ice-9/Makefile.am @@ -32,7 +32,7 @@ ice9_sources = \ safe-r5rs.scm safe.scm session.scm slib.scm stack-catch.scm \ streams.scm string-fun.scm syncase.scm threads.scm \ buffered-input.scm time.scm history.scm channel.scm \ - pretty-print.scm + pretty-print.scm ftw.scm subpkgdatadir = $(pkgdatadir)/$(VERSION)/ice-9 subpkgdata_DATA = $(ice9_sources) From 6c5b8521d00b84c3347af5c4662a0c319e34d850 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Wed, 6 Mar 2002 02:46:28 +0000 Subject: [PATCH 2/5] *** empty log message *** --- ice-9/ChangeLog | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ice-9/ChangeLog b/ice-9/ChangeLog index ce38693c6..4aea4cab3 100644 --- a/ice-9/ChangeLog +++ b/ice-9/ChangeLog @@ -1,3 +1,9 @@ +2002-03-05 Thien-Thi Nguyen + + * ftw.scm: New file. + + * Makefile.am (ice9_sources): Add ftw.scm. + 2002-02-26 Thien-Thi Nguyen * Makefile.am: Update path to pre-inst-guile automake frag. From d902b02a5dcec410b30cce259b023c6b28a1ed82 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Wed, 6 Mar 2002 20:46:41 +0000 Subject: [PATCH 3/5] Handle "--source" option. --- guile-tools.in | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/guile-tools.in b/guile-tools.in index aaa5309cc..8b32ba648 100644 --- a/guile-tools.in +++ b/guile-tools.in @@ -36,6 +36,7 @@ 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 Default scripts dir: $default_scriptsdir EOF @@ -89,6 +90,17 @@ if [ x"$1" = x -o x"$1" = xlist ] ; then exit 0 fi +if [ x"$1" = x--source ] ; then + if [ x"$2" = x ] ; then echo $0: need to specify program ; exit 1 ; fi + if [ -x $scriptsdir/$2 ] ; then + cat $scriptsdir/$2 + exit 0 + else + echo $0: no such program: $2 + exit 1 + fi +fi + program=$scriptsdir/$1 shift From 9b398b673091473b08a76a665b86a934eafee246 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Wed, 6 Mar 2002 20:47:26 +0000 Subject: [PATCH 4/5] *** empty log message *** --- ChangeLog | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/ChangeLog b/ChangeLog index 03334c934..b68846df5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2002-03-06 Thien-Thi Nguyen + + * guile-tools.in: Handle "--source" option. + 2002-03-04 Thien-Thi Nguyen * configure.in (top_srcdir_absolute): New AC_SUBST var. From abae30146f66bfb822b43cfdb96603ea0b40375a Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Wed, 6 Mar 2002 20:54:27 +0000 Subject: [PATCH 5/5] Initial revision --- doc/ref/tools.texi | 97 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 doc/ref/tools.texi diff --git a/doc/ref/tools.texi b/doc/ref/tools.texi new file mode 100644 index 000000000..3629b93b1 --- /dev/null +++ b/doc/ref/tools.texi @@ -0,0 +1,97 @@ +@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