Installing Common Music

Contents

  1. Pre-installation
  2. Installing Sources
  3. Starting Common Music
  4. Programs and Interfaces
    1. CFFI
    2. CLM
    3. CMN
    4. CM-GTK
    5. Fomus
    6. Midishare Interface
    7. Player Interface
    8. Portmidi Interface
  5. Appendix

Pre-installation

To build Common Music from its sources you must have write permission in an installation directory, a working Lisp command on your execution path and some familiarity with the shell, or terminal, application. If you are going to use CM in conjunction with other lisp programs like CLM or Fomus, or with Lisp interfaces to external programs such as Portmidi and Midishare, consider creating a common "parent" directory to contain the different Lisp systems so that you can load them transparently using use-system. It does not matter where on the file system this Lisp installation directory is located; for sake of illustration this document assumes that the lisp software systems are all installed under "/usr/local/lisp".

Installing Lisp music packages under a common parent directory will allow you to load the separate systems transparently using use-system. This listing shows the various lisp systems and interfaces discussed in this document.

$ ls -l /usr/local/lisp
drwxr-xr-x   15 hkt  admin   510 14 Nov 13:56 cffi/
drwxr-xr-x  188 hkt  admin  6392 14 Nov 09:57 clm-3/
drwxr-xr-x    9 hkt  admin   306 21 Nov 09:59 cm/
drwxr-xr-x   11 hkt  admin   374  5 Oct 17:28 cm-gtk/
drwxr-xr-x   64 hkt  admin  2176 25 Oct 12:46 cmn/
drwxr-xr-x   64 hkt  admin  2176 11 Nov 08:10 fomus/
drwxr-xr-x    7 hkt  admin   238 26 Oct 18:04 midishare/
drwxr-xr-x    5 hkt  admin   170 21 Nov 17:44 portmidi/

Installing Sources

Sources for stable and developmental releases can be downloaded as tarball archives (cm.tar.gz) or via anonymous CVS.

Tarball Installation

To install CM from a tarball simply download the archive and restore it under your Lisp installation directory: 

$ cd /usr/local/lisp
$ tar -zxf cm.tar.gz

CVS Installation

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

To install the latest developmental sources via CVS:

  1. Change directories to your Lisp installation directory. 

    $ cd /usr/local/lisp

  2. Set the shell variable CVSROOT to point to the CVS repository: 

    $ export CVSROOT=":pserver:anonymous@cvs.sourceforge.net:/cvsroot/commonmusic"

  3. Use cvs login to connect to the Sourceforge CVS server, press Enter when prompted for a password: 

    $ cvs login
CVS password:

  4. Use cvs checkout to restore CM's source tree to your Lisp installation directory: 

    $ cvs checkout -P cm

After the source tree has been restored you do not need to use login or checkout again. You can periodically update your CM installation tree to the most recent file versions from the Sourceforge repository by executing cvs update from inside the top-level CM directory: 

$ cd /usr/local/lisp/cm
$ cvs update

You can also checkout several optional packages from the same Sourceforge repository: a GTK GUI, an interface to Midishare and an interface to Portmidi: 

$ cvs checkout -P cm-gtk
$ cvs checkout -P midishare
$ cvs checkout -P portmidi

Starting Common Music

Once the sources have been installed on your local machine and you have a Lisp command that starts a supported lisp implementation, you can start Common Music. There are a number of different ways to do this, here are some typical strategies:

  1. To start Common Music from the Shell use the cm.sh script located in CM's binary directory. You must have a valid Lisp command installed on your path for this to work. 

    $ /usr/local/lisp/cm/bin/cm.sh

    Consider installing a global command that runs cm.sh without having to type its pathname. This example adds a cm command to /usr/bin that starts the script simply by typing cm to the shell prompt: 

    $ sudo ln -s /usr/local/lisp/cm/bin/cm.sh /usr/bin/cm
$ cm

    By specifying the -l and -e options you can launch CM under Emacs in any supported Lisp. Examples: 

    $ cm -l openmcl -e Emacs
$ cm -l gosh -e xemacs
$ cm -l clisp -e emacs

  2. To start Common Music from the Common Lisp REPL load "cm.lisp" from CM's source directory and then use the (cm) function to make the CM symbol package and readtable current: 

    > (load "/usr/local/lisp/cm/src/cm.lisp")
> (cm)

  3. To start Common Music from the Scheme REPL load "cm.scm" from CM's source directory: 

    > (load "/usr/local/lisp/cm/src/cm.scm")

  4. To start Common Music from inside Emacs add the following code to your ~/.emacs file. The example code assumes you have installed the cm shell command described in the first example: 

    (add-to-list 'load-path "/usr/local/lisp/cm/etc/xemacs")
(load "cm.el")
(setq inferior-lisp-program "cm")

    Restart Emacs and type C-x l to start CM in a dedicated Emacs buffer. See Running Common Music under Emacs for more information.

Regardless of which method you use to start CM the system will automatically generate, compile and load files as needed during the startup process. Once the files have been loaded CM will look for your "~/.cminit.lisp" customization file and automatically load it if it exists.

Programs and Interfaces

Once CM is running you can load in other Lisp programs and interfaces using the use-system function. This facility works transparently if the other Lisp software packages all share the same parent directory as your CM installation directory. To load programs and interfaces as part of CM's normal start up process add the appropriate use-system forms to either cm.lisp or to your personal ~/.cminit.lisp file. The use-system facility will automatically compile source code as necessary during the loading process.

The following Common Lisp packages can be loaded with use-system:

CFFI

(use-system :cffi)

The Common Foreign Function interface for Common Lisp, by James Bielman and Luís Oliveira. Required by the Portmidi and Midishare interfaces.

CLM

(use-system :clm)

Common Lisp Music, by William Schottstaedt. A sound synthesis package for Common Lisp and Scheme (Guile/Snd).

CLM instrument files must be compiled inside the CM package in order to work with the process macro.

CMN

(use-system :cmn)

Common Music Notation, by William Schottstaedt. A music notation package for Common Lisp.

CM-GTK

(use-system :cm-gtk)

Graphical User Interface for CM implemented in GTK+2, by Rick Taube.

See the Plotter and CMIO topic help for more information about working with the GUI tools.

Fomus

(use-system :fomus)

Fomus, by David Psenicka. A music notation package for Common Lisp.

Midishare Interface

(use-system :midishare)

A Common Lisp interface to Midishare, a real-time MIDI operating system by Grame.

See the midishare topic help for more information about working with Midishare in CM.

Player Interface

(use-system :player)

A Common Lisp interface to Midishare's Player sequencer.

Portmidi Interface

(use-system :portmidi)

A Common Lisp interface to the Portmidi MIDI library.

See the Portmidi topic help for more information about working with Portmidi in CM.

Appendix

A. Lisp Commands

In order to run Common Music you must be able to start one of the supported lisp implementations. Most implementations provide a shell command that lets you to start Lisp simply by typing the command name to the shell prompt. If you are on OS X, Linux or Cygwin you can use the which command to see if a Lisp command is installed on your path: 

$ which clisp
/usr/local/bin/clisp
$ which openmcl
/Lisp/bin/openmcl
$ which guile
/sw/bin/guile

Here are the command names of the supported Lisp implementations. Note that several implementations require you install the command yourself:

Implementation Command
Allegro: none
CLISP: clisp 1
CMUCL: lisp
Gauche: gosh
Guile: guile
Lispworks: none
OpenMCL: openmcl 2
SBCL: sbcl
STklos: stklos

1. Installing a CLISP.BAT file on Windows 2000/XP:

  1. Copy this batch file contents and paste it into a new window in Note Pad.

    @echo off

    REM Edit the clispdir pathname inside "" to point to
REM the clisp installation directory on your machine.
set clispdir="\Lisp\clisp-2.35"
    pushd %clispdir%
    .\full\lisp.exe -B . -M .\full\lispinit.mem %1 %2 %3 %4 %5 %6 %7 %8 %9
    popd

  2. Set the pathname in green to the true CLISP installation directory on your machine.

  3. Save the text in a file called "clisp.bat".

  4. Move clisp.bat to a directory on your path, for example C:\WINNT\System32\

2. Installing the openmcl script from the ccl distribution:

  1. Edit the file ccl/scripts/openmcl and set the CCL_DEFAULT_DIRECTORY variable to the OpenMCL installation directory on your machine, for example:

    CCL_DEFAULT_DIRECTORY=/usr/local/lisp/ccl

  2. Copy the file to a directory on your path, for example: 

    $ sudo cp /usr/local/lisp/ccl/scripts/openmcl /usr/bin