Skip to content

Latest commit

 

History

History
490 lines (357 loc) · 17.5 KB

install.md

File metadata and controls

490 lines (357 loc) · 17.5 KB
Raw

Installation Instructions

Ultrashort: for the quicklisp afficionado (TL;DR)

For a minimum installation of slippery chicken, open your terminal, cd to your Quicklisp local-projects directory, then:

# in your Quicklisp standard directory
git clone https://github.com/ormf/cm.git
git clone https://github.com/mdedwards/slippery-chicken.git

In your Lisp REPL or your Lisp initialisation file:

(ql:quickload :slippery-chicken)

(If none of the above made any sense, or you want extra package functionality such as CLM, then keep reading.)

This document describes the installation process of slippery chicken using the ASDF build system, which is – as of March 2024 – the recommended method for this process.

You will find two versions of this description: A short one for those familiar with Common Lisp, ASDF and the like, and a long version more aimed at those who are new to the Lisp world or prefer to follow more verbose instructions.

Short

Before going ahead, make sure you have a running Common Lisp implementation on your system. We work with SBCL. Also make sure that ASDF is installed.

We recommend working with Quicklisp as it automatically downloads packages it finds on its servers and thus makes the installation process simpler.

Install Dependencies

First of all, install slippery chicken's dependencies. These are:

  • Common Music/CM (required)
  • Common Music Notation/CMN (optional)
  • Common Lisp Music/CLM (optional)
  • ffprobe (optional)
  • LilyPond (optional)

Without the optional dependencies, you will only be able to use a reduced feature set, such as writing MIDI or Music-XML files.

Note

The Common Lisp dependencies (CM, CMN and CLM) need to be available to the ASDF's/Quicklisp's search path. We suggest putting the code in one of the standard locations:

ASDF: ~/common-lisp/ or ~/.local/share/common-lisp/source/
Quicklisp: ~/quicklisp/local-projects/

Let's begin:

Common Music (required)

Download the CM-sources from https://github.com/ormf/cm and put them in your ASDF/Quicklisp directory, or if you're comfortable working with a (UNIX) terminal:

# in your ASDF/Quicklisp standard directory
git clone https://github.com/ormf/cm.git

Common Music Notation (optional)

Download the CMN-sources from https://ccrma.stanford.edu/software/cmn/ and unpack them to your ASDF/Quicklisp directory, or:

# in your ASDF/Quicklisp standard directory
curl https://ccrma.stanford.edu/software/cmn/cmn.tar.gz -o cmn.tar.gz
tar xf cmn.tar.gz

Common Lisp Music (optional)

Download the CLM-sources from https://ccrma.stanford.edu/software/clm/ and unpack them to your ASDF/Quicklisp directory, or:

# in your ASDF/Quicklisp standard directory
curl https://ccrma.stanford.edu/software/clm/clm-5.tar.gz -o clm.tar.gz
tar xf clm.tar.gz

Important

CLM requires a C compiler to be present on your system. If you don't have a C compiler or are not sure, jump to this section.

ffprobe (optional)

You can use apt on Linux, brew on MacOS or choco on Windows:

# Linux
apt get ffmpeg

# MacOS
brew install ffmpeg

# Windows
choco install ffmpeg

If none of these options are available to you, head to this site and install ffprobe according to the directions given there: https://ffmpeg.org/download.html

LilyPond (optional)

You can use apt on Linux, brew on MacOS or choco on Windows:

# Linux
apt get lilypond

# MacOS
brew install lilypond

# Windows
choco install lilypond

If none of these options are available, head to this site and install LilyPond according to the directions given there: LilyPond

Install slippery-chicken

Now you are ready to install slippery chicken. Download the sources from https://github.com/mdedwards/slippery-chicken and put them in your ASDF/Quicklisp directory, or:

# in your ASDF/Quicklisp standard directory
git clone https://github.com/mdedwards/slippery-chicken.git

Configure slippery-chicken

The last step is modifying the initialisation file of your Common Lisp implementation to load slippery chicken and its dependencies. The name and location of your init file depends on the implementation you are using. With SBCL, for example, it is ~/.sbclrc by default, whereas Clozure CL uses ~/ccl-init.lisp or ~/.ccl-init.lisp.

Add the following lines to the init file:

(ql:quickload :cmn) ;; if you're using it
(ql:quickload :clm) ;; if you're using it
(ql:quickload :slippery-chicken)

If you are not using Quicklisp, replace the ql:quickload with asdf:load-system. Please note that you might then need to manually install and load additional packages which are required by slippery-chicken as well as to load slippery chicken's dependencies before loading slippery-chicken itself. See below for details.

Finally, you might want to customise some of slippery chicken's global configuration variables1. In case you use one of the optional dependencies, ensure the following paths are set to the actual locations of the binaries on your system, by appending the respective lines to your CL init file:

# for example...
(sc:set-sc-config 'lilypond-command "/opt/homebrew/bin/lilypond")
(sc:set-sc-config 'ffprobe-command "/opt/homebrew/bin/ffprobe")
(sc:set-sc-config 'csound-command "/opt/homebrew/bin/csound")

You should be able to use the slippery-chicken package in your Common Lisp REPL.

Long

Prerequisites and Preparations

Although slippery chicken's dependency overhead is rather low and installing the software via ASDF is quite straightforward, a few remarks on its prerequisites are worth being be made. Generally, this document assumes that you have a working Common Lisp implementation running on your system as well as that you have a basic understanding of the Common Lisp language.

ASDF

Most current Common Lisp implementations already include the ASDF-package by default,2 thus it is very likely that you don't need to set up ASDF up before going ahead. You can find out whether ASDF is available on your system by evaluating this form in your Lisp interpreter:

(find :asdf *features*)

This should return :ASDF.

In ASDF-parlance, modules or programs (e.g. slippery-chicken) are termed systems. Each system contains a system definition file (the .asd file) which provides information about dependencies, system components, etc. In case you encounter ASDF-related errors, inspecting the .asd file of the respective system is always a good strategy.

Important

If you are not familiar with ASDF, it is worth mentioning that all systems need to be present in the ASDF-search-path/registry. A simple and straightforward way to do this is to place the respective files in ASDF's standard location (~/common-lisp/ or ~/.local/share/common-lisp/source/). You could also use symbolic links, of course. For more detail cf. https://asdf.common-lisp.dev/asdf.html#Configuring-ASDF-to-find-your-systems.

Quicklisp (recommended)

As some modules (i.e. dependencies) of slippery chicken themselves depend on modules probably not present on your system and ASDF itself does not take care to download them,3 you might want to use Quicklisp, a Common Lisp library manager built upon ASDF to dynamically (down-)load the respective components. In order to do so, head over to https://www.quicklisp.org/ and follow the instructions given there.

We recommend using Quicklisp as it facilitates handling nested dependencies and thus minimises the effort needed to install and load slippery chicken.

Important

When using Quicklisp, the default search-path (cf. ASDF) for local projects might change to ~/quicklisp/local-projects/.

Install Dependencies

One major dependency of slippery chicken is Common Music (CM). Without CM, slippery chicken will not work. Additionally, slippery chicken's functionality will be greatly enhanced when further modules are available. This is a list of slippery chicken's dependencies:

  • Common Music/CM (required)
  • Common Music Notation/CMN (optional)
  • Common Lisp Music/CLM (optional)
  • ffprobe (optional)
  • LilyPond (optional)

The following sub-sections describe the installation process for each module. Except for Common Music, it is possible to skip one or more of the following sub-sections and thus adapt the feature set of slippery chicken to your needs.

Common Music (required)

As mentioned before, Rick Taube's Common Music (CM) needs to be available for slippery chicken to work. As slippery chicken is written in Common Lisp (CL), we need a CL version of CM, which is provided by Orm Finnendahl.

Download the CM-sources from https://github.com/ormf/cm and put them in your ASDF/Quicklisp directory, or use the terminal:

# in your ASDF/Quicklisp standard directory
git clone https://github.com/ormf/cm.git

Common Music Notation (optional)

Bill Schottstaedt's Common Music Notation (CMN) is capable of quickly generating musical scores from CL and is required, for example, by slippery-chicken's cmn-display4 method.

If you want to use CMN, download the tarball archive from https://ccrma.stanford.edu/software/cmn/ and unpack(-tar) it to your ASDF-/quicklisp directory. Alternatively, you can also use the terminal:

# in your ASDF/Quicklisp standard directory
curl https://ccrma.stanford.edu/software/cmn/cmn.tar.gz -o cmn.tar.gz
tar xf cmn.tar.gz

Common Lisp Music (optional)

Bill Schottstaedt's Common Lisp Music (CLM) is used in slippery chicken to write and (quickly) analyse soundfiles.

In order to use CLM, download the tarball archive from https://ccrma.stanford.edu/software/clm/ and unpack(-tar) it to your ASDF-/quicklisp directory. Alternatively, you can also use the terminal:

# in your ASDF/Quicklisp standard directory
curl https://ccrma.stanford.edu/software/clm/clm-5.tar.gz -o clm.tar.gz
tar xf clm.tar.gz
C Compiler

CLM requires a C compiler to be present on your system. On most UNIX systems (including Apple's macOS/OSX) you'll already have the GNU C compiler. You can check whether yours is ready to go by typing the following command in your terminal:

gcc -v

You should get some version details containing something like this:

Configured with: --prefix=/Library/Developer/CommandLineTools/usr --with-gxx-include-dir=/usr/include/c++/4.2.1

If you don't have a C compiler, installation methods vary from OS to OS:

  • macOS
    • run xcode-select --install in the terminal or cf. this wiki entry
  • Linux
    • Should have a C compiler installed; if not, ask your preferred search engine.
  • Windows
    • CLM was not designed to run on Windows though Michael Edwards had success a long time ago on Windows 95/XP. See README.clm in the CLM distribution.

ffprobe (optional)

ffprobe (from the ffmpeg package) is used by slippery chicken to retrieve some metadata from media files (e.g. video and, when not available via CLM, audio files). Note that using ffprobe is significantly slower at this than CLM.

In order to install ffprobe, you can use apt on Linux, brew on MacOS or choco on Windows. If none of these options are viable for you, head to this site and install ffprobe according to the directions given there: https://ffmpeg.org/download.html

Note

ffprobe is not a Common Lisp module, thus all ASDF-/Quicklisp-related comments made above do not apply to this program.

LilyPond (optional)

If you want to directly render beautiful scores via LilyPond (e.g. via slippery-chicken's lp-display), you might be interested in installing this software on your system.

In order to install LilyPond, you can use apt on Linux, brew on MacOS or choco on Windows. If none of these options are viable for you, head to this site and install LilyPond according to the directions given there: LilyPond

Note

lilypond is not a Common Lisp module, thus all ASDF-/Quicklisp-related comments made above do not apply to this program.

Install slippery-chicken

Installing slippery chicken, after fulfilling the prerequisites and (required) dependencies, is usually very easy. You can either download the sources from http://github.com/mdedwards/slippery-chicken and put them in your ASDF/Quicklisp directory, or use the terminal:

# in your ASDF/Quicklisp standard directory
git clone https://github.com/mdedwards/slippery-chicken.git

Note

On Windows, the recommended way is to use GitBash to clone slippery chicken, with line-endings set to Unix-style. This can be configured globally in Git with these commands: git config --global core.autocrlf false git config --global core.eol lf. This configuration is necessary because slippery chicken might not compile correctly if the end-of-line (EOL) characters are set to CRLF instead of LF.

Configure slippery-chicken

Now that you have installed all the components that you would like to use, you need to take care of loading the modules before starting to work with slippery chicken. It is recommended to do this via the init file of your Common Lisp implementation which will be loaded and evaluated when you start your Common Lisp interpreter. The name and location of your init file depends on the implementation. On SBCL, for example, it is ~/.sbclrc by default, whereas Clozure CL uses ~/ccl-init.lisp or ~/.ccl-init.lisp. Add the following lines to your init file:

(ql:quickload :cmn) ;; if you're using it
(ql:quickload :clm) ;; if you're using it
(ql:quickload :slippery-chicken)

If you are not using Quicklisp, replace the ql:quickload with asdf:load-system. Please note that you then need to manually load various dependencies before loading slippery-chicken. The following could serve as an starting point to load a full slippery chicken installation without Quicklisp:

(asdf:load-system :cmn)
(asdf:load-system :alexandria) ;; required by Common Music (cm)
(asdf:load-system :cm)
(asdf:load-system :clm)
(asdf:load-system :cl-ppcre) ;; required by slippery-chicken
(asdf:load-system :slippery-chicken)

Customise Global Options

slippery chicken contains some global variables which could/should be modified to suit the user's requirements. For a detailed insight, take a look at src/globals.lsp.1

If you want to use slippery chicken with external programs like LilyPond, ffprobe, or Csound, you might need to tell slippery chicken where it can find the binaries to execute. This is because although there are standard locations for such files, the actual location might differ from operating system to operating system or machine to machine; locations also depend on the installation method. Below you will find an example that sets the variables for the aforementioned programs to the binary location where they were installed via Homebrew on a Mac. These lines could also be appended to the Common Lisp init file, but must be added after the commands which load slippery-chicken and its dependencies (see above).

(sc:set-sc-config 'lilypond-command "/opt/homebrew/bin/lilypond")
(sc:set-sc-config 'ffprobe-command "/opt/homebrew/bin/ffprobe")
(sc:set-sc-config 'csound-command "/opt/homebrew/bin/csound")

To find out where a particular program is, you can call e.g. which ffprobe in most terminals.

That's it. You should now be able to start working with slippery-chicken.

Footnotes

  1. https://michael-edwards.org/sc/robodoc/globals_lsp.html#robo230 ↩ ↩2

  2. Cf. https://asdf.common-lisp.dev/#implementations ↩

  3. Cf. https://asdf.common-lisp.dev/#what_it_is_not ↩

  4. Cf. https://michael-edwards.org/sc/manual/output.html#cmn ↩