Installing Common Music

Installing Common Music involves downloading the sources, starting a supported Lisp implementation, loading CM's sources and (optionally) saving a Lisp image file containing the application. Once the system is installed you can run Common Music in X/Emacs and load in additional software systems such as CLM, CMN and Midishare.

Contents

  1. Downloading and restoring the sources
    1. Restoring sources from archives
    2. Restoring sources from CVS
  2. Starting a Lisp application
  3. Loading Common Music
    1. Quickstart (OS X, Linux or Cygwin)
    2. Lisp loading
    3. Saving images and other custom builds
  4. Configuring GTK
    1. Configuring X11 and GTK2 on Darwin (OS X)
    2. Installing GTK2 support in OpenMCL (OS X)
    3. Adding callback support to SBCL (Linux)
  5. Working with CLM, CMN and MidiShare
    1. Loading CLM and CMN
    2. Installing Midishare
  6. Troubleshooting
    1. End-of-line conversion (MacOS)
    2. Installation directory not restored (Windows)
    3. Installing a CLISP command on Windows
    4. The DOS directory character in Lisp

1. Downloading and restoring the sources

Common Music's sources can be downloaded from archives or via anonymous CVS.

1.1 Restoring sources from archives

  1. Download the latest CM source archive from the Sourceforge Common Music Project.

  2. Place the downloaded archive in an appropriate directory on your machine. If you are going to work with other Lisp packages such as CLM or CMN you might consider creating a parent Lisp directory to restore these different Lisp systems in.

  3. Restore the CM source archive with whatever software you use. This should unpack the contents of the archive in a directory named cm-n.n.n, where n.n.n is the version number of the CM release. This document will refer to this directory as the CM installation directory.

1.2 Restoring sources from CVS

The sources to Common Music are maintained in a CVS repository organized into different release branches that are tagged by symbolic release numbers. By convention, even numbered branches denote stable software release lines and odd numbered branches denote unstable, or developmental, releases. The CVS head branch — the release branch you get if you do not specify any release tag — always points to the latest developmental sources.

As of this date (November 2004), Common Music's CVS tree has two main branches: a rel-2_4 branch line contains sources and bug fixes to the stable 2.4.n releases; CM's head branch points to the 2.5.n developmental line.

To check out sources from Common Music's CVS repository use the Unix cvs command or a CVS client application. Downloading sources for the first time is accomplished in two steps: (1) logging in to the Sourceforge CVS server in anonymous mode and (2) checking out the sources to the desired release branch.

Directions for checking out sources from CM's repository at Sourceforge:

  1. Change directories to the parent directory in which you want to install the CM source tree.

  2. Use anonymous CVS login to the Sourceforge CVS repository. Press the Return key when prompted for a login password: 

    $ CVSROOT=":pserver:anonymous@cvs.sourceforge.net:/cvsroot/commonmusic" 
$ cvs login
CVS password:
$

  3. Use the CVS checkout command to restore the CM source tree to your computer.

    To download the latest (developmental) sources from the head branch: 

    $ cvs checkout -P cm
[cvs printout omitted...]

    To check out a stable release, specify the appropriate tag to the checkout command. For example, to get the latest stable version on the CM 2.4.n release line do: 

    $ cvs checkout -P -r rel-2_4 cm
[cvs printout omitted...]

    Once the source tree has been restored to your machine you can cd inside it and use the cm.sh script to build CM: 

    $ cd cm
$ bin/cm.sh
[build printout omitted...]

  4. Once you have checkout the sources you do not need to use the login or checkout command again. To remain current with a release line you simply cd to your CVS source tree and use the CVS update command to update your installation tree with the newest versions of the files from the repository. Then use the cm.sh script to recompile and reload CM: 

    $ cd /path/to/cm
$ cvs update
[cvs printout omitted...]
$ bin/cm.sh
[build printout omitted...]

2. Starting the Lisp application

In order to build Common Music from its sources you must be able to start one of the supported Lisp implementations. Each Lisp may be represented by (up to) three implementation files:

  1. A shell command or program that starts Lisp running in a Terminal (the CMD window on Windows) or under X/Emacs.

  2. An installed executable that runs when the command is invoked.

  3. An image file that contains the Lisp runtime environment.

The following table lists the commands, programs and image names for each Lisp implementation. Follow the links for additional information.

Application files for supported Lisp implementations.

Lisp Command Executable Image
CLISP clisp ./full/lisp(.exe) ./full/lispinit.mem
CMU lisp ./bin/lisp ./lib/cmucl/lib/lisp.core
OpenMCL openmcl ./dppccl ./dppccl.image
ACL ./alisp(.exe) ./lisp.dxl
Guile guile guile

If you are on OS X, Linux or Cygwin you can use the which command to see if a Lisp command is installed properly on your path.

Using 'which' to locate a lisp command (Linux, OS X, Cygwin).

$ which clisp
/usr/local/bin/clisp
$ which openmcl
/Lisp/bin/openmcl
$ which guile
/sw/bin/guile
$ which alisp
alisp: Command not found.

Even if your Lisp implementation does NOT come with an installed command you should create and install one to simplify working with Common Music. There is not one single way to do this that will work for all Lisp implementations and operating systems. On OS X, Linux or Cygwin, either copy the appropriate Lisp program/script to a directory on your $PATH or edit your $PATH definition in ~/.bash_profile or ~/.cshrc to include the directory that contains the Lisp program/script. On Windows 2000/XP install a batch file to start CLISP, see clisp.bat for information on how to do this. On MacOS, double-click the MCL Common Lisp application to start Lisp.

3. Loading Common Music

The following instructions assume you can start Lisp by typing the appropriate command in a Terminal window. The examples depict the load process in several different Lisp implementations; if you use some other Lisp or operating system the examples will appear slightly differently as you perform each step.

3.1 Quickstart (OS X, Linux or Cygwin)

The easiest way to load CM on OS X, Linux or Cygwin is with the cm.sh script located in the bin/ subdirectory of the CM installation directory. When the script finishes loading it will leave you in the CM package ready to begin work:

Running the cm.sh script. 

$ cd /path/to/cm
$ bin/cm.sh
[...build output omitted...]

 /\\\          
---\\\---------
----\\\--------
----/\\\------- Common Music 2.5.0
---/--\\\------
--/----\\\-----
 /      \\\/   
?

The cm.sh script can run CM in a Terminal or under X/Emacs. Type cm.sh -h for an overview of the script's command options and usage.

3.2 Lisp loading

The cm.sh script is used to start CM running from inside the Unix terminal. If you inside a Lisp application you can load Common Music's build script from the src/ subdirectory of the CM installation directory. For Scheme the build script is called cm.scm, for all Common Lisp implementations the file to load is called cm.lisp. Be sure to specify the full, true pathname to the file, i.e. avoid using links, relative paths, or shortcuts like "~/" unless you are sure your Lisp supports them.

Loading CM in Common Lisp.

? (load "/path/to/cm/src/cm.lisp")
[...build output omitted...]

Loading CM in Scheme.

guile> (load "/path/to/cm/src/cm.scm")
[...build output omitted...]

Loading CM in Clisp/Windows (Common Lisp). 

[1]> (load "c:\\path\\to\\cm\\src\\cm.lisp")
[...build output omitted...]

For information about using the DOS directory character in Lisp see Troubleshooting Tip 4.

Loading cm.scm into Guile (Scheme) loads CM's source files — no compilation or image saving occurs. In in all other Lisp implementations loading cm.lisp first compiles source files into an efficient (binary) representation and then loads them into Lisp.

Once the load process completes you can switch to the CM package using the cm function. This will allow you to easily access all the symbols and functions defined in Common Music. Use the quit function to exit from Common Music and Lisp.

Switching to the CM package.

? (cm)

 /\\\          
---\\\---------
----\\\--------
----/\\\------- Common Music 2.5.0
---/--\\\------
--/----\\\-----
 /      \\\/   

? (quit)

3.3 Saving Lisp images and other custom builds

A Lisp image file containing Common Music can be saved in CM's binary directory. Despite the fact that a saved image file may boot a few seconds faster than loading CM from compiled files, fasl loading is the preferred method for starting CM because it provides more flexibility for working with different Lisp systems together.

  1. To save a Lisp image file, start Lisp and then load make.lisp from the src/ subdirectory. Then call the make-cm function with :save-image specified: 

    ? (load "/path/to/cm/src/make.lisp")
; Loading /path/to/cm/src/make.fasl
? (make-cm :save-image t)
[...build output omitted...]
; Removing fasl files.
; Garbage collecting...
; Saving application image.
; Bye!
$

  2. Once the system loads and saves an image you will automatically exit Lisp. You can then start your freshly saved Common Music image using the cm.sh script or by specifying the image file to your Lisp command according to its installation directions.

See the documentation on make-cm for more information about the various build options.

4. Configuring GTK

CM's graphics support is implemented in GTK2, a popular graphics library that can be used with CM in the following Lisp environments:

CM's Lisp-to-GTK interface is implemented using λgtk, a separate software package developed by the author and made available under the LLGPL (Lisp Lesser General Public License).

CM will automatically include its GUI tools in any correctly configured and supported environment. If you use either OpenMCL on Darwin or SBCL on Linux then you may have to configure your environment before you attempt to build CM with its GUI.

4.1 Configuring X11 and GTK2 on Darwin (OS X)

You must have X11 and GTK2 installed and configured properly on your machine. Apple's X11 application must also be running before you can open any windows.

  1. X11.app normally resides in /Application/Utilities/. If you do not have it you can download it from Apple's X11 page. It should also be possible to use XDarwin/XFree86 but I have not tried it.

  2. Use FinkCommander to install Fink's gtk+2 package. CM assumes that all GTK+ libraries are restored under /sw/lib/ directory (the default location for installing Fink packages).

Once X11 and GTK2 are installed and the X11.app is running you can open a GUI window inside cm running in xterm or under XEmacs. You can also start GTK windows from inside Terminal.app or Emacs.app (the Cocoa Emacs application) if you add the following line to your ~/.bash_profile file: 

export DISPLAY=:0.0

It has been noticed on some networked OSX computers that opening the first GTK window inside Lisp takes over a minute to complete. The problem is related to font loading but I have not yet been able to determine exactly what is going wrong. If you encounter this problem the (temporary) fix is to add the following line to your ~/.bash_profile file: 

export GDK_USE_XFT=0

4.2 Installing GTK2 support in OpenMCL (OS X)

In order to work with GTK2 in OpenMCL you must first install a foreign function interface (FFI) to the GTK libraries:

  1. Download openmcl-darwin-ffi-gtk2.tar.gz

  2. Untar the archive inside your ccl/darwin-headers/ directory under the OpenMCl distribution: 

    $ cd /path/to/ccl/darwin-headers
$ tar -zxf openmcl-darwin-ffi-gtk2.tar.gz

4.3 Adding callback support to SBCL (Linux)

As of this date (Feb '05) SBCL does not provide a native callback facility. Unless you are certain that callbacks exist in your version of SBCL you will need to install Thomas Burdick's SBCL callback package and save a new SBCL core image before you build CM:

  1. Download Thomas Burdick's Alien Function package and restore it to a directory on your machine.

  2. Compile the Alien Function package and save a new sbcl.core image: 

    $ cd sbcl-af
$ sbcl --load "system"
* (sb-ext:save-lisp-and-die "/tmp/sbcl.core")
$ cd /usr/local/lib/sbcl
$ mv sbcl.core sbcl.core.orig
$ mv /tmp/sbcl.core .

5. Working with CLM, CMN and Midishare

You can load other Lisp software systems into Lisp either before or after loading Common Music. If you want to save a Lisp image containing all of these systems bundled together, load the other software before you call make-cm to save the image.

5.1 Loading CLM and CMN

To work with either CLM or CLM you simply load the system using the appropriate command shown below:

Loading CLM and CMN into the CM package.

? (load "/path/to/clm-2/all")
[build output omitted...]
? (load "/path/to/cmn/cmn-all")
[build output omitted...]

Note that if you load CLM instruments that were compiled outside of the Common Music package you will have to import their symbols before working with the instruments:

Importing instruments compiled in the cl-user package. 

? (load "/path/to/clm-2/v")
#P"/path/to/clm-2/v.dfsl"  
? (load "/path/to/clm-2/grani")
#P"/path/to/clm-2/grani.dfsl"
? (import '(cl-user::fm-violin cl-user::grani))
T
? (new fm-violin :startime 0 :dur 3 :frequency 440)
#i(fm-violin startime 0 dur 3 frequency 440)

5.2 Installing Midishare

A direct connection from Common Music to one or more MIDI Drivers can be established using Midishare, a real-time MIDI operating system developed by Grame. Common Music currently works with Midishare in the following OS/Lisp combinations:

Directions for installing MidiShare:

  1. Download, install and configure the Midishare and Developer packages from the Midishare FTP Server. Be sure to set up your MidiShare driver ports (msDriver) and test your MIDI connection (msController) before attempting to build CM with Midishare.

  2. If you are running OpenMCL, download openmcl-midishare.tar.gz from the CCRMA ftp server and untar the archive in "ccl/darwin-headers/", i.e. the "darwin-headers/" subdirectory of your OpenMCL distribution: 

    $ cd /path/to/ccl/darwin-headers
$ tar -zxf openmcl-midishare.tar.gz

  3. Load the Midishare-Interface.lisp file located in the src/MidiShare/ sub-folder of the Common Music installation directory: 

    ? (load "/path/to/cm/src/midishare/Midishare-Interface")

  4. Once the file is load you can output MIDI events to the "midi.port" destination. 

    ? (events (new midi :time 0 :duration 2 :keynum 60) "midi.port")
"midi.port"

See the main MIDI documentation in the dictionary for more information about MIDI and working with MidiShare in real time.

6. Troubleshooting

1. Line conversion (MacOS)
Some installers on MacOS may not restore gzipped Unix tar files (*.tar.gz), correctly. Make sure that your installer performs end-of-line conversion on text files when it unpacks the sources. You can determine if this was done correctly by editing CM's readme.text using SimpleText. If the file is legible then your installer performed the conversion correctly.
2. Installation directory not restored (Windows)
Some installers on Windows may choose to ignore the archive's top-level directory if you unpack by double-clicking the file. These steps work for me using WinZip:
  1. Place the archive in the parent directory that will hold the CM distribution.
  2. Right-button the archive file and choose "Install Here" from the pop-up menu.
3. Installing a CLISP command (Windows)
When Clisp is installed on Windows it places a shortcut to the program on your desktop. Unfortunately, this shortcut is not very useful for working with Common Music or for running Clisp under Emacs. Here is how to install a CLISP command on Windows 2000:
  1. Copy the contents of the script file shown below and paste it into a new window in Note Pad.
  2. Change the pathname in green to the actual path to CLISP on your machine.
  3. Save the text in a file called "clisp.bat".
  4. Move the new clisp.bat file to some directory on your path, for example to C:\WINNT\System32\clisp.bat.

The clisp.bat script file for Windows 2000.

@echo off

REM Edit the clispdir pathname inside "" to point to
REM the clisp installation directory on your machine.

set clispdir="\Lisp\clisp-2.31"
pushd %clispdir%
.\full\lisp.exe -B . -M .\full\lispinit.mem %1 %2 %3 %4 %5 %6 %7 %8 %9
popd
4. The DOS directory character in Lisp (Windows)
You must double each DOS directory delimiter when you specify Window's directories in Lisp strings, i.e. "c:\\lisp\\cm-2.5.0\\readme.text" not "c:\lisp\cm-2.5.0\readme.text". This is because \ is a special quoting character inside Lisp strings; specifying two together actually produces one \ in the string. If this is too confusing then you should simply switch to using the Unix-style directory delimiter / on Windows, for example "c:/path/to/cm/readme.text". Allegro, Clisp and Guile all support Unix-style directory strings under Windows.

Valid XHTML 1.0!