• Home Page
• Dictionary

Running Common Music in Emacs

Contents

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

Introduction

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:

• Linux: XEmacs
• OS X: Aquamacs Emacs (a very Mac-like Emacs) or Carbon Emacs
• Windows XP: XEmacs for Windows. Download using their net install method with this setup.exe. (Cygwin install available on the same page.)

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")
   (enable-cm-commands)
   

   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
---/--\\\------
--/----\\\-----
 /      \\\/  

CL-USER>
; 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:

• Type M-x cm to start the CM application.

• Type expressions just after the Lisp prompt and press <return> to enter them.
• Copy visible input expressions to the insertion point by clicking on them and typing <return>.
• Use C-↑ to cycle backward through your input history until you find an expression, then type <return> to enter it. The command C-↓ goes forward through the input history.
• To abort from an error break type q in the error window.
• You can type M-<return> to automatically close all open parenthesis and evaluate a function call expression.
• To kill the Common Music session, type M-x kill-cm

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:

• C-x C-e evaluates the Lisp expression before point. Results of the evaluation appear in the mini-buffer, not in the REPL.
• The <tab> key indents lines according to Lisp syntax. It also performs symbol completion. For example, type (ampli<tab> to autocomplete: (amplitude
• The first space typed after a function name in a function call will display the arguments to the function in the minibuffer. For example, type (rhythm<space> to see the arguments to Common Music's rhythm function.
• The command M-. edits the definition of the lisp function or variable at point (under the cursor) if SLIME can find it.

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:

• C-x C-e (and Apple-e on OS X) evaluates expressions at point, before point, around point or in the selected region.
• <f8> (function key 8) toggles between the REPL and the last Lisp buffer you were editing.
• <tab> indents lines and whole regions according Lisp rules.
• C-c C-d c displays CM dictionary documentation about the CM symbol at point.

SLIME Editing Tips

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

• The very first form in your Lisp file or buffer should be (in-package :cm) or else SLIME will not evaluate expressions in the CM package, even if the REPL package is set to CM. It is good Lisp practice to put an in-package declaration at the top of every source file.
• When you evaluate an expression in a Lisp editing buffer the return value is printed in the mini-buffer at the bottom of the edit window, not in the REPL.
• In order to eval CM expressions the status line at the bottom of the edit window should say (Slime:cm) and the SLIME menu should be visible in the menubar.
• The command M-x lisp-mode will force any Emacs buffer into a Lisp editing buffer, even if the buffer does not contain Lisp code.

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:

• C-h means to hold down the control key while you type the h key.
• C-x C-s means to hold down the control key as you type the x key, hold control down while you type the s key.
• M-x means to hold down the meta key while you type x.
• C-M-f means to hold down both control and meta while you type f.
• C-h t means to first type C-h, then release the control key and type just the t key.
• M-x lisp-mode means to hold down meta while you type x, then release both keys and type the word lisp-mode.

Cursor Motion Commands

Scrolling Commands

Editing Commands

File Commands

Buffer and Window Commands

Help Commands

Directory Editing

FuN CoMmAnDs

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:

• Perform the interactive Emacs Tutorial, available from the Help menu or by typing the command C-h t
• Getting Started With XEmacs
• The Emacs Manual
• The GNU Emacs Lisp Reference Manual