Running Common Music in Emacs


  1. Introduction
  2. Recommended Emacs Distributions
  3. Installing and Configuring SLIME
  4. Running Common Music
  5. Emacs Command Summary
  6. More Emacs Information


The Emacs and XEmacs program editors (jointly referred to as Emacs in this document) can connect to a running Common Music image using an add-on package called SLIME, which stands for Superior Lisp Interaction Mode for Emacs. SLIME provides a full-featured, Lisp REPL (interpreter) with its own command history, remote evaluation services from Emacs Lisp-mode buffers, and a host of useful Lisp development tools.

Note that if you are on OS X and have Aquamacs Emacs or Carbon Emacs installed (see below), you can simply download the latest CM application bundle and double-click it to start using CM with all the bundled Lisp systems without having to perform any of the installation steps described here or in the document Installing Common Music.

Recommended Emacs Distributions

For best results install one of these Emacs distributions:

Installing and Configuring SLIME

Follow the download directions on the SLIME homepage to install the sources on your machine. SLIME is under active development so it would be best to use their CVS installation method.

In order to work with Common Music using SLIME you must first add a few customizations to your personal emacs initialization file. Every time Emacs starts it reads your initialization file to set up the editing environment exactly the way you want it to be. Emacs names this init file ~/.emacs, that is, the file named .emacs in your home directory. XEmacs uses ~/.xemacs/init.el, that is, the file named init.el in the .xemacs/ subdirectory of your home folder. Note that pathnames that start with a dot (like .emacs and .xemacs/) are invisible files on OS X and Linux so you cannot see them in the Finder window or in a normal directory listing.

How to configure Emacs for SLIME and CM:

  1. Start Emacs and use the keyboard command C-x C-f ~/.emacs to create or edit your initialization file. (See the section Emacs Command Summary for more information about Emacs keyboard commands.)

  2. Add the following code to your init file, replacing the pathname strings "/path/to/slime", "/path/to/cm/ with the correct paths to the slime/ and cm/ installation directories on your machine.

    (add-to-list 'load-path "/path/to/slime/")
    (add-to-list 'load-path "/path/to/cm/")
    (load "etc/xemacs/cm.el")

    See Lisp Editing and Remote Evaluation to learn more about the effects of enable-cm-commands. If you do not want to use the extra features that CM provides simply comment the line out.

  3. Save the file (C-x C-s) and quit Emacs (C-x C-c). Your changes will take effect the next time you start Emacs.

Running Common Music

To run Common Music in SLIME start Emacs and type the keyboard command:

M-x cm

Watch as a new window opens and Common Music is loaded in the Slime REPL. Once the REPL is fully loaded you should see the Common Music logo in the REPL:

; SLIME 2006-03-24

----/\\\------- Common Music 2.8.0
 /      \\\/  

; No value
CM> |

To kill the current Common Music session type the command:

M-x kill-cm

Basic REPL Interaction

The term REPL stands for Read Eval Print loop. Lisp expressions are typed at the insertion point located just to the right of the latest input prompt. When the <return> key is pressed, Lisp first reads the input, then evaluates it and finally prints the results back in the REPL on the next line. Any previous input can be copied to the insertion point by placing the cursor inside the input expression and then typing <return>. The copied expression can then be edited at the listening point using regular Emacs editing commands. Press the <return> key again to enter it into Lisp. The Listener records each input expression in its input history list. Previous input expressions can be recalled from the history list using C-↑ to move backward and C-↓ to move forward through the list. Use <return> to reenter the desired input.

To summarize:

Lisp Editing and Remote Evaluation

The real power of SLIME only become apparent when you start editing Lisp code inside an Emacs editing buffer. SLIME's Lisp editing commands are installed in the SLIME menu visible in the Emacs menubar whenever you select a Lisp buffer. The SLIME menu has many fancy commands that help you edit Lisp code and develop programs; here are a few of the most commonly used items:

Common Music documentation is installed in the SLIME menu under SLIME>Documentation>Common Music. The Lookup... menu item will display the dictionary entry of the CM function or variable at point in your web browser's window.

If you add (enable-cm-commands) to your .emacs file then the following commands are activated:

SLIME Editing Tips

Finally, here are a few tips for beginning SLIME users:

Emacs Command Summary

Although Emacs supports point-and-click editing operations just like any word processor, its real power lies in its keyboard commands — short keystroke combinations that invoke the powerful editing, formatting and cursor motion capabilities of the editor. Emacs keyboard commands are formed by holding down the control and/or meta keys while typing a keystroke that identified the command. The control key is located in the lower left-hand corner of the keyboard. The location of the meta key varies with computers; it is usually found either to the left of the spacebar (Windows) or just to the right of the control key (Aquamacs).

Emacs documentation refer to the control and meta keys using shorthand names C- and M- respectively. In this documentation, underlines indicate keystrokes that are typed with the control and/or meta keys depressed. For example:

Cursor Motion Commands

Command Meaning
C-f forward one character
C-b back one character
C-p previous line
C-n next line
C-a beginning of line
C-e end of the line
M-f forward one word
M-b back one word
C-M-f forward one expression
C-M-b back one expression

Scrolling Commands

Command Meaning
C-v down one screenfull
M-v up one screenfull
M-> beginning of file
M-< end of file

Editing Commands

Command Meaning
C-g abort current command
C-d delete character
M-d delete word
C-M-d delete expression
C-k kill (cut) to end of line, keep in pasteboard
C-spacebar set the mark, the starting position of a region.
C-w cut from mark to here, keep in pasteboard
M-w copy from mark to here, keep in pasteboard
C-y yank back last thing in pasteboard
C-s interactive text search
M-% interactive search and replace
C-] abort recursive editing mode

File Commands

Command Meaning
C-x C-f open file (new or existing)
C-x C-s save buffer changes
C-x C-w write buffer to new name
M-x revert-buffer throw away buffer changes and reload file
C-x C-c exit emacs

Buffer and Window Commands

Command Meaning
C-x k kill current buffer
C-x b switch to buffer
C-x C-b list all buffers
C-x 1 only one window
C-x 2 two windows
C-x o other window

Help Commands

Command Meaning
C-h ? list help commands
C-h b list all keyboard commands
C-h b describe a key command
C-h t online tutorial
C-h a apropos word

Directory Editing

Command Meaning
M-x dired start up directory editor
return edit file or enter directory
d mark file for deletion
u un-mark file for deletion
x Really expunge files marked for deletion

FuN CoMmAnDs

Command Meaning
M-x doctor find out why nobody likes you
M-x life Game Of Life (cellular automaton)
M-x yow words of wisdom from Zippy the Pinhead
M-x dunnet text-based adventure game
M-x spook scary CIA anarchistic somebody shoot me!

More Emacs Information

In order to become an efficient Emacs Lisp user you should spend several hours familiarizing yourself with Emacs and its keyboard commands. Here are some places you can start: