module/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 use guild to invoke a program from the shell, or alternatively,
   8 load its file as a Guile Scheme module, and use its exported procedure(s)
   9 from Scheme code.  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 If you want to try the programs before installing Guile, you will probably
  26 need to set environment variable GUILE_LOAD_PATH to be the parent directory.
  27 This can be done in Bourne-compatible shells like so:
  28
  29   GUILE_LOAD_PATH=`(cd .. ; pwd)`
  30   export GUILE_LOAD_PATH
  31
  32 [FIXME: Can someone supply the csh-compatible equivalent?]
  33
  34
  35
  36 How to Contribute
  37 -----------------
  38
  39 See template file PROGRAM for a quick start.
  40
  41 Programs must follow the "guild" convention, documented here:
  42
  43 - The module name must be "(scripts PROGRAM)".  A procedure named PROGRAM w/
  44   signature "(PROGRAM . args)" must be exported.  Basically, use some variant
  45   of the form:
  46
  47   (define-module (scripts PROGRAM)
  48     :export (PROGRAM))
  49
  50   Feel free to export other definitions useful in the module context.
  51
  52 - There must be the alias:
  53
  54   (define main PROGRAM)
  55
  56   However, `main' must NOT be exported.
  57
  58 Following these conventions allows the program file to be used as module
  59 (scripts PROGRAM) in addition to being invoked by guild.  Please also
  60 include a helpful Commentary section w/ some usage info.
  61
  62
  63 [README ends here]