Download and Installation

Note to CPSC 432 students:

The best platform on which to run Haskell and Euterpea is Windows, and you should feel free to follow the steps below to install it on your personal machine. The installation instructions for Linux are more complicated, but for most flavors of Linux, you should be fine with the instructions below.

On your Mac, you might find success installing Haskell and Euterpea (especially if it is one of the older OS versions), but you might not. If you are having trouble with it, at some point you should consider moving to Windows or Linux.

Note that the problems with the Mac are not something we have a lot of control over – indeed the problem is not with Euterpea, it is with the Haskell Platform, and even commercial software has compatibility issues with different versions of the Mac OS. For those using Mavericks, you may wish to try one of the following fixes for a successful install of the Haskell Platform:
Fix 1
Fix 2
If you do happen to get Haskell and Euterpea working on your Mac, please let us know!

Of course, you can also use:

  • One of the three Windows machines in the closed Zoo,
  • One of the ten Windows machines in the Dunham Cluster (DL 120, near the Hillhouse Ave entrance), or
  • One of the Linux machines in the zoo.

The Haskell Platform is already installed on these machines, but you need to install your own version of Euterpea in your own user space. To do this, follow these simple instructions:

  1. Install git from http://windows.github.com/ (unless it is already installed).
  2. Open a “Git Shell” to create a command prompt, and do the following:

git clone https://github.com/Euterpea/Euterpea
cd Euterpea
cabal update
cabal install

To hear sound on these machines, you may need to use headphones, since not all of them have speakers.

Installing GHC

You should install the Glasgow Haskell Compiler (GHC) first. The easiest way to do this is to download the Haskell Platform. This also contains Cabal, which is a powerful package management system for Haskell. You will need Cabal for installing and updating Euterpea. Mac users may need to download the 32-bit version of Haskell Platform to avoid compatibility problems.

Download the Haskell Platform installer for your operating system and set it up per the instructions. After doing so, you may proceed to the next steps.

Each version of Haskell Platform comes with a different version of the GHC compiler and Cabal. We recommend using Haskell Platform 2013.2.0.0, which has GHC 7.6.3, cabal-install version 1.16.0.2, and Cabal library version 1.16.0. Once Haskell Platform is installed, you can check the versions you have installed by running the following in a command prompt or terminal:

ghc --version
cabal --version

Note to Windows users: If you have installed previous versions of GHC or the Haskell Platform, it is best to first remove them, preferably through the uninstall option for these applications, but if necessary, manually remove things such as:

C:\Program Files\Haskell
C:\Program Files\Haskell Platform
C:\Documents and Settings\username\Application Data\ghc
C:\Documents and Settings\username\Application Data\cabal

You might want to search for anything with “ghc” or “cabal” in the name and get rid of it.

Installing Git

Git is the configuration management tool that we currently use to maintain Euterpea. You should install it for your operating system by following the instructions here:

http://git-scm.com/downloads

Path Environment

Windows users can skip this step since the PATH environment has already been set by the Haskell Platform installation.

Linux and OS X users should set ~/.cabal/bin to your PATH environment by entering the following command at the command prompt:

export PATH=~/.cabal/bin:$PATH

You can also set it permanently by modifying the file ~/.bashrc or ~/.profile (depending on which system you use) to include the above line. Otherwise, you’ll have to enter the above command every time you want to use any binary command installed by cabal.

If the ~/.cabal/bin directory does not exist on your installation, try ~/Library/Haskell/bin instead for the instructions above.

Installing Euterpea

For Linux users, first make sure that the ALSA development package (both header files and libraries) is already installed, since Euterpea depends on it.

Open a command prompt. “cd” to the directory (folder) in which you wish to place Euterpea. Then do:

cabal update

You may see a message telling you that a new version of cabal is available. You can check which version of cabal you have by running cabal --version. If you already have cabal-install version 1.16.0.2, then you do not need to do anything. If you have an older cabal version, then run the following:

cabal install cabal-install

Next, run:

git clone https://github.com/Euterpea/Euterpea
cd Euterpea
cabal install

Testing Installation Success

Assuming that the installation succeeds, you may enter the example directory and load/run some examples, as follows:

cd Euterpea/Examples
ghci

ghci is the command to start GHC interactively as an interpreter, where you may enter Haskell commands and load programs. For example, we can load a file from the Examples folder, and play one of the music values defined within it, as follows:

:load EuterpeaExamples.lhs
play childSong6

If your MIDI device is working properly, you should hear a melody, otherwise please see the below notes for your particular operating system or check the troubleshooting FAQ at the bottom of this page.

You can also type :help at the ghci command prompt for more instructions on how to use it.

Installation Notes for Linux

Linux machines don’t support MIDI by default, so there are a few extra steps to get it working.
First of all, we recommend using TiMidity and either Freepats or PersonalCopy for MIDI support. Before you attempt source compilation, you might want to check if your distribution already includes them as one of the pre-built packages for download.

To install PersonalCopy and have Timidity depend on it, follow these steps:

wget ftp://ftp.personalcopy.net/pub/Unison.sf2.gz # this can take a while to download.
sudo mkdir /etc/sounds
gunzip Unison.sf2.gz
mv Unison.sf2 /etc/sounds
sudo sh -c "echo soundfont /etc/sounds/Unison.sf2 > /etc/timidity/timidity.cfg"
sudo service timidity restart

Next, you’ll need to make sure that timidity is the default MIDI-Through port. The easiest way to do this is to remove the default dummy port:

sudo rmmod snd_seq_dummy

(If you want to make this change permanent, you can run

sudo sh -c "echo blacklist snd_seq_dummy > /etc/modprobe.d/blacklist-seq-dummy.conf"

which will create a configuration file that tells modprobe (the linux device driver loader) not to load snd_seq_dummy. It can be easily reversed by just deleting the file.)

Then, while Euterpea programs are running, you must have timidity running in the background, which you can achieve by first running
timidity -iA -Os &
before running the Euterpea program.

Installation Notes for Mac OS X

MIDI
Download SimpleSynth and open it before you run ghci. It’s a software MIDI synthesizer that plays MIDI output through the speaker.

GHCi GUI
You will have to use the “EnableGUI trick” to run GUI programs in GHCi for Euterpea. First, compile EnableGUI.hs to binary from the Euterpea/Examples directory:

ghc -c -fffi EnableGUI.hs

Note: on some systems it is necessary to include a -framework option, like this:

ghc -framework ApplicationServices -c -fffi EnableGUI.hs

Then run your Euterpea GUI programs in ghci like this:

ghci UIExamples.hs EnableGUI
*UIExamples> :m +EnableGUI
*UIExamples EnableGUI> enableGUI >> main

Otherwise, GHCi will not be able to fully activate the Graphics Window. (Fully compiled GUI programs do not suffer from this anomaly.)

Updating Euterpea

Once GitHub and the Haskell Platform are installed, you should not have to reinstall or update them. However, from time to time we suggest that you update to newer versions of Euterpea, which is still evolving. To do this, open a command prompt (make sure it is in administrator mode on Windows Vista/7/8), and do the following from the top-level Euterpea folder:

git pull
cabal install

This should update your Euterpea installation.

Troubleshooting FAQ

The instructions say to open a “command prompt” or “terminal” but I don’t know how.

  • On Windows 8, from the desktop, hover your mouse over the lower left corner until the start box appears and right click. Select “Command Prompt (Admin)”.
  • On Windows Vista or Windows 7 machines, click on the Start button, and look for the Command Prompt icon (usually under All Programs | Accessories). Right click on the icon, and then click “Run as administrator”.
  • On other Windows platforms, just click on the Command Prompt icon (usually under All Programs | Accessories), or execute “cmd.exe“.
  • On a Mac, open the “Terminal” application.

I followed the advice for my specific operating system, but I still can’t get MIDI output to work properly.

Make sure timidity or simplesynth are running in the background if you’re using those programs. Alternatively, instead of (for example) doing “play childSong6“, use “test childSong6” instead. This will write the MIDI output to a file named “test.mid“, and you can then play it with timidity (Linux) or Quicktime (Mac). Or, if you have an external MIDI device, you can connect it to your computer and have MIDI signals sent to it.

The “cabal install” appeared to succeed, but the Euterpea package can’t be found with “import Euterpea.”

Turn off any antivirus software and try the installation again. Some antivirus programs may silently block actions required for a successful installation when running “cabal install” – even in administrator mode on Windows. In some cases the installation may appear to succeed when it is actually incomplete. Recent versions of Avast are very problematic for this. If you are using Avast, turn it off completely during the time that you are attempting to install Euterpea.

Running Euterpea examples with the 64-bit version of Haskell Platform results in segfaults.

Uninstall Haskell Platform, delete any directories it leaves behind (usually called things like “ghc”, “cabal”, or “haskell”). Follow the setup instructions again but use the 32-bit version of Haskell Platform. The 64-bit version of Haskell Platform has known compatibility problems with some Mac OS versions.

A call to “caball install” fails unexpectedly partway through the installation with no error beyond “some packages failed to install” when installing either Euterpea or a new version of cabal.

If the installation requires downloading additional packages, a timeout can cause the installation to abort unexpectedly.  Check your Internet connection and try the same command again.

Doing “cabal install” to install Euterpea fails with a CCA-related error stating that ccap can’t be found.

Sometimes when Haskell Platoform is installed, some directories that should be added to the system path aren’t. Search your hard drive for “ccap” – it is an executable file that can appear in various places depending on the OS. Once you find the ccap file, add its directory to your system path. If there is no ccap file anywhere on your machine, you can try cabal install CCA --reinstall to reinstall CCA.

Doing “cabal install” to install Euterpea fails because CCA failed to install.

If you are using CCA-0.1.4, run “cabal update” to get the most recent version of the CCA library, which is CCA-0.1.5, and then try installing Euterpea again.

Comments are closed.