• Home Page
• Dictionary
• Examples

Running Common Music under X/Emacs

Contents

1. Introduction
2. Installing X/Emacs
   1. Downloading distributions
   2. Suggested binary distributions for running Common Music
   3. Customizing X/Emacs
   4. The X/Emacs initialization file
   5. Emacs keyboard commands
   6. Emacs command summary
3. Running Common Music under X/Emacs
   1. Quick-start (Linux, OS X, Cygwin)
   2. Running CM in X/Emacs under Windows
   3. Starting Common Music from inside X/Emacs
4. The X/Emacs Lisp Listener
   1. The Listener menu
   2. The Listener window
   3. The Listener menubar
   4. Entering input in the Listener
5. X/Emacs Tips
   1. Determining the version of X/Emacs
   2. Apple keyboard shortcuts for OSX X/Emacs
   3. Avoiding startup error message on OSX X/Emacs

1. Introduction

The Emacs and XEmacs editors (jointly referred to as X/Emacs in this document) support Lisp editing and evaluation within a single, consistent GUI environment. This tight integration between Lisp editing and evaluation lets the composer develop Lisp programs inside a powerful programming editor and interactively evaluate the Lisp code inside Common Music using simple editor commands. The Common Music application runs in its own dedicated Listener window as an inferior process (sub-process) of X/Emacs. This Listener window is a full-featured, interactive Lisp interpreter with its own command history and input editing features.

The whole point of running Common Music inside X/Emacs is to integrate Lisp editing and evaluation in a single, easy-to-use graphical environment. Some older installations of Emacs run the editor in what is called console mode, directly inside the command shell window without mouse support or a GUI. If your system already has an emacs command installed on it (see Tip 1), make sure that it starts a windowed, GUI version of the editor. If your installed X/Emacs is old (prior to the 21.3 branch) or doesn't support a GUI then don't bother using it, follow the links provided below to download and install a newer version for your system.

2. Installing X/Emacs

Which editor you choose to install and work with is really a matter of personal taste. Both editors are free, provide the same basic editing services, and run on practically every operating system available today. The primary difference between the two applications lies in their divergent GUI designs. Without commenting on which design is "better" (see: XEmacs vs. GNU Emacs), it is probably fair to say that the typical user will feel most comfortable in an editor whose "look and feel" matches the host operating system's native window manager. On Linux, Cygwin and Windows this is XEmacs, on OS X it is an Aqua Emacs.

2.1 Downloading distributions

Regardless of which editor you choose, install a recent (21.3.1 or later), stable, fully-configured distribution that includes all elisp sources. (X)Emacs distributions typically consist of several parts: the core editor, the Emacs Lisp (elisp) source files, and lots of add-on packages. The size of a fully configured distribution is very large, between 20 and 30 megabytes for a binary release depending on the editor and operating system involved. Even if downloading will require up to several hours (on a 56k modem, for example), you should take whatever time is necessary to install a fully configured X/Emacs including elisp sources; you will come to use more and more of X/Emacs' features and add-on packages as you gain familiarity with the editor.

2.2 Suggested binary distributions for running Common Music

Common Music has been tested in the most recent stable releases of the following distributions:

Linux:

XEmacs

OS X:

Emacs for OS X (Aqua)

Windows 2000/XP:

XEmacs for Windows
Download using the net install method with this setup.exe. (Cygwin install available on the same page.)

MacOS:

Fred in MCL is an acceptable Emacs substitute. (The name Fred stands for Fred Resembles Emacs Deliberately.)

2.3 Customizing X/Emacs

Once you have downloaded and installed X/Emacs you can customize it for working with Common Music and programming in Lisp by activating syntax highlighting to colorize Lisp code according to Lisp syntax rules.

• Start X/Emacs
• Select Syntax Highlighting from the Options menu at the top of the Emacs window. If Syntax Highlighting has a sub-menu, make sure that its Automatic feature is checked in the sub-menu.
• Set any other options you want and then select Save Options from the Options menu. X/Emacs then prompts you to confirm saving your changes in ~/.emacs or ~/.xemacs/init.el. Type 'y' to confirm.

2.4 The X/Emacs initialization file

Saving the customized options creates or updates a personal emacs initialization file that X/Emacs loads each time it starts. You can add your own Emacs commands (elisp expressions) to this file to set up the editor exactly the way you want. XEmacs normally saves the init file as ~/.xemacs/init.el, that is, the file init.el in the .xemacs/ subdirectory of your home folder. Emacs uses ~/.emacs, the file .emacs located in your home directory. On Unix-flavored machines (Linux, OS X, Cygwin, etc) the dotted names (.xemacs/ and .emacs) make the init files "invisible" in normal directory listings and file browsing windows.

2.5 Emacs keyboard commands

X/Emacs supports the mouse-oriented, point-and-click operations used in most word processors, but the real power of Emacs lies in its keyboard commands — short, simple keystrokes that invoke the 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; it is usually found either to the left of the Spacebar or to the right of the Control key.

Most Emacs documentation refer to the Control and Meta keys using shorthand names C- and M- respectively. Underlines are sometimes included to indicate combinations of 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, then continue to 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.

2.6 Emacs Command Summary

2.6.1 Cursor Motion Commands

2.6.2 Scrolling Commands

2.6.3 Editing Commands

2.6.4 File Commands

2.6.5 Buffer and Window Commands

2.6.6 Help Commands

2.6.7 Directory Editor

2.6.8 JuSt FoR fUn Commands

In order to become an efficient X/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

3. Running Common Music under X/Emacs

The remaining sections of this document assume that you have already downloaded Common Music and can start a GUI X/Emacs on your system. See the document Installing Common Music for more information about downloading and installing CM.

3.1 Quick-start (Linux, OS X, Cygwin)

The easiest way to start CM under X/Emacs is to pass your favorite editor command to the bin/cm.sh script. Here are several examples on different systems. Each example assumes that you have already cd'ed to the Common Music installation directory:

% bin/cm.sh -e xemacs

% bin/cm.sh -e Emacs

$ bin/cm.sh -l guile -e emacs

See the cm.sh documentation for more information about using the script to run Common Music.

3.2 Running CM in X/Emacs under Windows

You cannot use cm.sh in the Windows command interpreter. However, you can add code to your X/Emacs init file that will accomplish basically the same thing. These instructions are outlined in the next section Starting Common Music from inside X/Emacs.

3.3 Starting Common Music from inside X/Emacs

You can start Common Music from inside a running X/Emacs session if you add the following forms your X/Emacs init file. The example shown below is set up for a Windows installation. Change the pathname of the cm-direcoty to reflect your machine and use the Unix form of the directory delimiter / even if you are on Windows. If you are not on Windows then change the name of the cm-startfile from cm.bat to cm.sh.

;;; Edit the cm-directory string to point to the
;;; CM installation directory on your machine.
;;; On Unix machines change cm.bat to cm.sh

(defvar cm-directory "C:/Lisp/cm-2.4.1")

(defvar cm-startfile "cm.bat")

(let* ((els (concat cm-directory "/etc/xemacs"))
       (bin (concat cm-directory "/bin/"
                    cm-startfile))
       (load-path (cons els load-path)))
  (load "listener")
  (load "cm")
  (setq inferior-lisp-program bin))

Save the changes (C-x C-s) and quit X/Emacs (C-x C-c). Then restart X/Emacs and type C-x l to start Common Music's Listener window. Alternately, you can set the current buffer into Lisp-mode (M-x lisp-mode) and then select the Lisp Listener item from the Listener menu that appears in the X/Emacs menu bar.

4. The X/Emacs Lisp Listener

The Lisp Listener runs Common Music in a dedicated X/Emacs frame, or window, as a subprocess of the editor. This means that when you quit the editor you will also quit the Common Music session running in the Listener. There are two parts to the Listener, the Listener window itself and the Listener menu that automatically appears in the editing window whenever you editing in lisp-mode, the Emacs editing mode that supports Lisp program editing commands. This mode is automatically activated whenever you edit a .lisp, .cm or .ins text file.

4.1 The Listener menu

The Listener menu is available in the main X/Emacs menu bar whenever Lisp-Mode is the active mode in the editing window. The menu provides commands for starting and stopping the Listener, evaluating expressions in the Listener and formatting Lisp code in the edit window. The following menu items are defined:

Lisp Listener (C-x l)

Starts Common Music running in the Listener window. If the Listener is already running then it is reselected as the front-most window.

Quit Listener

Quits and closes the active Listener window.

Eval Selection (C-x C-e)

Evaluates the current selection in the edit window by "sending" it to the Listener. The current selection is:

• A Lisp expression that starts at the cursor's position.
• A Lisp expression that ends just before the cursor's position.
• All Lisp expression(s) inside a selected region of the edit window.

Eval Buffer (C-x C-h)

Evaluates all of the expressions in the edit window.

Macroexpand (C-x C-m)

Performs macroexpansion on the current edit selection.

Abort Error (C-x C-.)

Resumes the Listener's normal read-eval-print loop after an error occurs.

Indent (TAB)

Reformats the selected edit region or the current edit line according to proper Lisp indentation rules.

Comment Region

Prepends the Lisp comment character ; to the start of each line in the region. A Lisp comment is not evaluated.

Remove Comments

Undoes the effects of Comment Region.

Tools

The Tools sub-menu holds Lisp commands specific to the Lisp implementation running in the Listener. Consult your Common Lisp or Scheme documentation for more information.

4.2 The Listener window

The Listener window is a graphic front end to a Lisp read eval print loop. It consists of a menubar and a Listener pane in which input expressions may entered and their evaluated results observed.

4.2.1 The Listener menubar

The Listener menubar contains three menus: File, Edit and Buffers. The File menu defines the following commands:

New...

Creates a new X/Emacs edit window ready for Lisp-mode editing.

Open...

Opens a file for editing in the X/Emacs edit window.

Load...

Loads a file into the Lisp Listener.

Quit Listener

Quits and closes the Listener window.

The Edit menu is the XEmacs edit menu.

The Buffers menu contains a list of all the Lisp files that are currently available for editing in X/Emacs. Selecting a file from the Buffers menu makes it the active, front-most edit window.

4.2.2 Entering input in the Listener

The Listener window is a dedicated Lisp read-eval-print loop. Lisp expressions are input at the current listening point located just to the right of the most recent input prompt. When the Return key is pressed, Lisp first reads the input, then evaluates it and finally prints the results back to the Listener window on the next line. Any expression visible in the window can be copy/pasted to the input point by placing the cursor just to the right of the expression and then typing Return. The copied expression can then be edited at the input point using regular X/Emacs editing commands. Press the Return key to enter it into Lisp. The Listener records each input expression in its input history list. Previous input expressions can by recalled from the list using C-<uparrow> to move backward and C-<downarrow> to move forward through the list, and Return to reenter the desired input once it has been selected.

5. X/Emacs Tips

1. Determining the version of X/Emacs

Use the which command to see if an X/Emacs command is installed on your path. If it is, then use the --version option to see what version it is.

Version number of an (old) installed X/Emacs.

% which xemacs
no xemacs in /bin /sbin /usr/bin /usr/sbin
% which emacs
/usr/bin/emacs
% emacs --version
GNU Emacs 21.1.1
Copyright (C) 2001 Free Software Foundation, Inc.
GNU Emacs comes with ABSOLUTELY NO WARRANTY.
You may redistribute copies of Emacs
under the terms of the GNU General Public License.
For more information about these matters,
see the file named COPYING.
%

2. Apple keyboard shortcuts for OSX X/Emacs

You can use the standard Apple shortcuts for copy/paste etc. by adding the following forms to your X/Emacs init file:

Apple command definitions for Mac shortcuts.

;; move Meta next to Control to free up Apple key.
(setq mac-command-key-is-meta nil)
;; standard Apple key commands
(global-set-key [(alt a)] 'mark-whole-buffer)
(global-set-key [(alt v)] 'yank)
(global-set-key [(alt c)] 'kill-ring-save)
(global-set-key [(alt x)] 'kill-region)
(global-set-key [(alt s)] 'save-buffer)
(global-set-key [(alt l)] 'goto-line)
(global-set-key [(alt o)] 'find-file)
(global-set-key [(alt f)] 'isearch-forward)
(global-set-key [(alt g)] 'isearch-repeat-forward)
(global-set-key [(alt w)]
                (lambda ()
                  (interactive)
                  (kill-buffer (current-buffer))))
(global-set-key [(alt ?.)] 'keyboard-quit)
(global-set-key [(alt z)] 'undo)

3. Avoiding startup error message on OSX X/Emacs

When you start OS X Emacs from a shell (via cm.sh, for example), the application may complain about missing directories. These directories are actually installed under the application. You can stop the error message from occuring if you have root privledges by installing two links, as shown in this interaction.

Installing links for Emacs.

$ su root
$ mkdir -p /usr/local/share/emacs
$ cd /usr/local/share/emacs/
$ ln -s /Applications/Emacs.app/Contents/Resources/site-lisp site-lisp
$ ln -s /Applications/Emacs.app/Contents/Resources/ 21.3.50