[bpt/guile.git] / scripts / README

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]
Commit	Line	Data
28c31342 TTN	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')'
8c914f6b	68	exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@"
28c31342 TTN	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]