[Bash script]
cm.sh [-qnv] [-e editor] [-l lisp] [-s sys] [-P prefs] [-O os] [-A arch] [-F lisp-flavor] [-V version] [-R cmroot]

Starts Common Music (cm) either by loading it into a fresh Lisp or Scheme session or by launching an existing Lisp image that has been built with Common Music pre-loaded. Additionally, this process can be run stand-alone in a terminal or as a subprocess of an Emacs-compatible editor such as xemacs(1), emacs(1), or gnuclient(1).

Since the script is designed to autodetect all required parameters at runtime, it should in virtually all cases suffice to call it without any arguments. This autodetection however may be customized or overridden via the following options and environment variables:

-h
Print this help.
-q
Don't run cm, only echo platform as 'os-arch' string.
-n
Dry run.
-v
Be verbose.
-e {editor}
Run under this editor. The value should be a command on your path that starts an Emacs-compatible editor (emacs, xemacs, gnuclient) or a path to the executable. On OS X you can specify 'Emacs' to invoke an Emacs application installed as /Applications/Emacs.app. Default is '<none>'.
-l {lisp}
Run this Lisp/Scheme. The value should be a command on your path or a path to the Lisp executable. Default value is '<unset>'.
-s {system}
Load system using use-system. The value of system should be a non-keyword symbol. This option can be specified multiple times, systems will be loaded in left-to-right order.
-P {prefs}
Preferred runtimes for autodetecting Lisp commands. Default is 'openmcl cmucl acl clisp guile'.
-O {os}
OS in case autodetection fails.
-A {arch}
Machine architecture in case autodetection fails.
-F {lisp-flavor}
Lisp flavor in case autodetection fails.
-V {version}
Lisp version in case autodetection fails.
-R {cmroot}
Common Music root directory in case autodetection fails.

Environment variables:

CM_EDITOR
Name or path of an Emacs-compatible editor under which to run cm, e.g. 'xemacs' or '/usr/bin/gnuclient'. Same as -e option.
CM_RUNTIME
Name or path of a Lisp or Scheme system to execute, e.g. 'clisp' or '/usr/bin/openmcl'. Same as -l option.
CM_RUNTIME_PREFS
List of CM_RUNTIME_FLAVORs to try during autodetection, in order of preference. Same as -r option.
CM_OS
Symbolic name of host OS, e.g. 'linux' or 'darwin'. Same as -O option.
CM_ARCH
Symbolic name of host architecture, e.g. 'i386' or 'powerpc'. Same as -A option.
CM_RUNTIME_FLAVOR
Symbolic name of the Lisp/Scheme flavor to run, e.g. 'clisp' or 'cmucl'. Useful in conjunction with CM_RUNTIME or the -l option if the flavor can't be derived from the command name or path. Same as -F option.
CM_RUNTIME_VERSION
Version of the Lisp/Scheme to run. Useful in conjunction with CM_RUNTIME or the -l option if the version can't be derived from the command name or path. Same as -V option.
CM_ROOT_DIR
Absolute path of the Common Music root directory in case autodetection fails. Same as -R option.

For autodetection to work, it is important that the script be not moved from its location inside the Common Music directory tree. A 'cm' (or similar) command in a standard binary location can be easily provided either by creating a symlink (Example 1) or by creating a wrapper shell script (Example 2).

Examples:

Example 1. Linking a system-wide command to cm.sh

% ln -s /path/to/cm/bin/cm.sh /usr/local/bin/cm

Example 2. Wrapper shell script to start cm.sh

#!/bin/sh
exec /path/to/cm/bin/cm.sh 
# chmod 755 /usr/local/bin/cm

Requirements: bash(1), cat(1), cut(1), echo(1), head(1), sed(1), sort(1), tr(1), uname(1), which(1); getopts and ls; a working installation of a Lisp or Scheme runtime; the '-repl' option if clisp is used (clisp 2.31 or higher).

See Also: