7 System Utilities

A number of different functions, variables and files provide system support for CM.

help &optional string &key :type :browser :domain [Function]

Displays help documentation matching string. If string matches more than one entry the list of matching topics is displayed. If string is not specified the entire help index is displayed according to :type and :browser. :type is the type of help to display, and defaults to all. Other possible types are class, function, macro, menu and variable. :browser is the browser to display documentation with and defaults to *html-browser*. domain is the help domain to access and defaults to :cm.

*html-browser* [Variable]

:netscape on Linux and to :explorer on Mac and Windows. Other possible browsers are: :lynx, :cyberdog, and :ICab.

cm-version [Function]

Returns Common Music's version number. Be sure to include this information in bug reports!.

date-string [Function]

Returns the date and time as a formatted string: "21-Nov-2001 13:05:57".

shell format &rest values [Function]

Concatenates values using format string and passes the result to the operating system.

set-cm-host-dir &rest translations [Function]

Resets the specified translations of the logical host cm. Useful for moving a Common Music image to a different file system than the one it was built on. Adding a call to set-cm-host-dir to the "cminit.lisp" file located in the application's start-up directory redirects the system to look for files using the new translation set.

The cm logical host points to Common Music's system files and directories on the current host. By default cm is set to the parent directory of the directory containing the build script "cm:src;cm.lisp".

The cm logical host supports the following directories:

cm:src;*.*

The directory where system source files are located.

cm:bin;*.*

The directory where compiled files are located.

cm:etc;*.*

A directory containing an assortment of useful examples and scripts.

cm:etc;cminit.lisp

Common Music's site initialization file. The system attempts to load "cm:etc;cminit.lisp" each time it starts up. If the file is not found the system next looks in the application directory (the directory containing the Common Music image file) loads it if the file is found. The default "cminit.lisp" file contains an instruction to load the user's personal initialization file, if one exists. On Windows and Macintosh the file is named "cminit.lisp" and must be located in whatever directory the Lisp function user-homedir-pathname returns as its value. On Unix the file is called "~/.cminit.lisp".

cm:doc;*.*

The directory where CM documentation is kept.

cm:help;*.*

The directory where CM help files are located.

cm:tmp;*.*

The directory where CM temporary files are located. Defaults to "/tmp" on Unix.

cm:examples;*.*

The directory where CM examples are kept.

cm:contrib;*.*

The directory where CM contributions and utilities are kept. Defaults to "cm:etc;contrib;"

cm:scripts;*.*

The directory where CM scripts are kept.

cm:patches;*.*

The directory where CM patches are kept.

Example 7-1

;; Reset all translations for CM logical host to a new root directory:
? (set-cm-host-dir "**;*.*" "/home/hkt/**/*.*")

;; Reset "cm:tmp;" and "cm:scripts;" directories:
? (set-cm-host-dir "tmp;*.*" "/zap/*.*" "scripts;*.*" "/lib/*.*")

cload file &key :output-file :force-recompile :verbose :source-types [Function]

Conditionally compiles and loads file. A binary version of file is compiled if there is currently no binary version, the binary version is out of date, or :force-recompile is t. If file does not include an extension cload searches for a version with an extension specified in the list :source-types. By default cload searches for files ending in .lisp, .ins and .cm in that order. The name of the compiled output file can be specified by :output-file. By default the output file has the same name and directory as the source file and an implementation specific extension supplied by cload.

cload returns two values, the true pathname of the loaded file and the source file if it was compiled.

Example 7-2

? (cload "macintosh hd:lisp:cm-2.0:src:pkg")
;Compiling "Macintosh HD:Lisp:cm-2.0:src:pkg.lisp"...
;Loading #P"Macintosh HD:Lisp:cm-2.0:src:pkg.pfsl"...
#P"Macintosh HD:Lisp:cm-2.0:src:pkg.pfsl"
#P"Macintosh HD:Lisp:cm-2.0:src:pkg.lisp"

? (cload "macintosh hd:lisp:cm-2.0:src:pkg")
;Loading #P"Macintosh HD:Lisp:cm-2.0:src:pkg.pfsl"...
#P"Macintosh HD:Lisp:cm-2.0:src:pkg.pfsl"
NIL

? (cload "macintosh hd:lisp:cm-2.0:src:pkg.pfsl" :verbose nil)
#P"Macintosh HD:Lisp:cm-2.0:src:pkg.pfsl"