scripts/README

   1 Overview and Usage
   2 ------------------
   3
   4 This directory contains Scheme programs, some useful in maintaining Guile.
   5 On "make install", these programs are copied to PKGDATADIR/VERSION/scripts.
   6
   7 You can invoke a program from the shell, or alternatively, load its file
   8 as a Guile Scheme module, and use its exported procedure(s) from Scheme code.
   9 Typically for any PROGRAM:
  10
  11   (use-modules (scripts PROGRAM))
  12   (PROGRAM ARG1 ARG2 ...)
  13
  14 For programs that write to stdout, you might try, instead:
  15
  16   (use-modules (scripts PROGRAM))
  17   (with-output-to-string (lambda () (PROGRAM ARG1 ARG2 ...)))
  18
  19 Note that all args must be strings.
  20
  21 To see PROGRAM's commentary, which may or may not be helpful:
  22
  23   (help (scripts PROGRAM))
  24
  25 To see all commentaries and module dependencies, try: "make overview".
  26
  27 If you want to try the programs before installing Guile, you will probably
  28 need to set environment variable GUILE_LOAD_PATH to be the parent directory.
  29 This can be done in Bourne-compatible shells like so:
  30
  31   GUILE_LOAD_PATH=`(cd .. ; pwd)`
  32   export GUILE_LOAD_PATH
  33
  34 [FIXME: Can someone supply the csh-compatible equivalent?]
  35
  36
  37
  38 How to Contribute
  39 -----------------
  40
  41 See template file PROGRAM for a quick start.
  42
  43 Programs must follow the "executable module" convention, documented here:
  44
  45 - The file name must not end in ".scm".
  46
  47 - The file must be executable (chmod +x).
  48
  49 - The module name must be "(scripts PROGRAM)".  A procedure named PROGRAM w/
  50   signature "(PROGRAM . args)" must be exported.  Basically, use some variant
  51   of the form:
  52
  53   (define-module (scripts PROGRAM)
  54     :export (PROGRAM))
  55
  56   Feel free to export other definitions useful in the module context.
  57
  58 - There must be the alias:
  59
  60   (define main PROGRAM)
  61
  62   However, `main' must NOT be exported.
  63
  64 - The beginning of the file must use the following invocation sequence:
  65
  66   #!/bin/sh
  67   main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')'
  68   exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@"
  69   !#
  70
  71 Following these conventions allows the program file to be used as module
  72 (scripts PROGRAM) in addition to as a standalone executable.  Please also
  73 include a helpful Commentary section w/ some usage info.
  74
  75
  76 [README ends here]