Installing Common Music

Contents

  1. Before Installing
  2. Tarball Installation
  3. CVS Installation
  4. Starting Common Music
  5. Programs and Interfaces
    1. Common Foreign Function Interface (CFFI)
    2. Common Lisp Music (CLM)
    3. Common Music Notation (CMN)
    4. CM-GTK
    5. Fomus
    6. Midishare Interface
    7. Open Sound Control (OSC)
    8. Player Interface
    9. Portmidi Interface
    10. Real Time Scheduling (RTS)
    11. Sa
    12. SAL
  6. Appendix

Before Installing

In order 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   10 hkt  admin   340 24 Mar 11:30 osc/
drwxr-xr-x    5 hkt  admin   170 21 Nov 17:44 portmidi/
drwxr-xr-x   23 hkt  wheel   782 16 Mar 13:29 rts/

Tarball Installation

Sources for stable and developmental releases can be downloaded as tarball archives (*.tar.gz or *.tgz).

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@commonmusic.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, and interfaces to Midishare, OSC messaging, Portmidi and RTS: 

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

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, assuming you have configured your Emacs with SSLIME. Examples: 

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

    See the document Running Common Music in Emacs for more information about using CM with 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")

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. Required by the Portmidi, Midishare and RTS interfaces.

CLM

(use-system :clm)

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)

A music notation package for Common Lisp that outputs to EPS.

CM-GTK

(use-system :cm-gtk)

Graphical User Interface for CM implemented in GTK+2.

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

Fomus

(use-system :fomus)

A music notation package for Common Lisp that outputs to Lilypond, CMN and MusicXML.

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.

Open Sound Control

(use-system :osc)

Support for real time OSC communication with external applications like SuperCollider, PD and Max/MSP.

Player Interface

(use-system :player)

An interface to Midishare's Player sequencer for Common Lisp and Gauche Scheme.

Portmidi Interface

(use-system :portmidi)

An interface to the Portmidi MIDI library for Common Lisp and Gauche Scheme.

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

Real Time Scheduling

(use-system :rts)

Real time scheduling services for supported Lisp/OS systems.

See the RTS topic help for more information about working with RTS.

Sa

(use-system :sa)

A Common Lisp interface to the SndObj Audio Library.

SAL

(use-system :sal)

SAL is an alternate language syntax for working with Common Music. Sal provides commands, statements and infix expressions. It lets you start working with Common Music immediately, without having to first learn Lisp notation and evaluation rules. Sal comes with its own Emacs mode (sal-mode.el) that includes syntax highlighting and command execution services via SLIME. SAL has its own lexer/parser and combines features of Lisp, Dylan, PLA and Stella.

See the SAL topic help for more information about working with SAL.

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