diff options
Diffstat (limited to 'module/scripts/README')
-rw-r--r-- | module/scripts/README | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/module/scripts/README b/module/scripts/README new file mode 100644 index 000000000..56dd286fb --- /dev/null +++ b/module/scripts/README @@ -0,0 +1,76 @@ +Overview and Usage +------------------ + +This directory contains Scheme programs, some useful in maintaining Guile. +On "make install", these programs are copied to PKGDATADIR/VERSION/scripts. + +You can invoke a program from the shell, or alternatively, load its file +as a Guile Scheme module, and use its exported procedure(s) from Scheme code. +Typically for any PROGRAM: + + (use-modules (scripts PROGRAM)) + (PROGRAM ARG1 ARG2 ...) + +For programs that write to stdout, you might try, instead: + + (use-modules (scripts PROGRAM)) + (with-output-to-string (lambda () (PROGRAM ARG1 ARG2 ...))) + +Note that all args must be strings. + +To see PROGRAM's commentary, which may or may not be helpful: + + (help (scripts PROGRAM)) + +To see all commentaries and module dependencies, try: "make overview". + +If you want to try the programs before installing Guile, you will probably +need to set environment variable GUILE_LOAD_PATH to be the parent directory. +This can be done in Bourne-compatible shells like so: + + GUILE_LOAD_PATH=`(cd .. ; pwd)` + export GUILE_LOAD_PATH + +[FIXME: Can someone supply the csh-compatible equivalent?] + + + +How to Contribute +----------------- + +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. + + +[README ends here] |