Here are detailed instructions for downloading Euterpea.
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 188.8.131.52, 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:
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 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.
GitHub 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:
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:
You can also set it permanently by modifying the file
~/.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.
~/.cabal/bin directory does not exist on your installation, try
~/Library/Haskell/bin instead for the instructions above.
Open a command prompt
The remaining steps are done from a command prompt. You can open a command prompt window as follows:
- 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 “
- On a Mac, open the “Terminal” application.
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:
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 184.108.40.206, then you do not need to do anything. If you have an older cabal version, then run the following:
cabal install cabal-install
git clone https://github.com/dwincort/Euterpea
Assuming that the installation succeeds, you may enter the example directory and load/run some examples, as follows:
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:
If your MIDI device is working properly, you should hear a melody, otherwise please read the next section on how to set up MIDI output.
You can also type
:help at the ghci command prompt for more instructions on how to use it.
Note: On MacOS X, you will have to use the “EnableGUI trick” to run GUI programs for Euterpea, as follows: First compile
EnableGUI.hs to binary from the
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.)
Setting up MIDI
If you are using Mac or Linux and cannot hear anything, chances are your sound card does not have a hardware MIDI synthesizer built in. If that is the case:
- If you are using MacOS, download SimpleSynth and open it before you run ghci. It’s a software MIDI synthesizer that plays MIDI output through the speaker.
- If you use Linux, download and install Timidity++ as well as freepats. 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.
- After they are properly installed, you can start timidity like this before you run ghci:
timidity -iA -Os &
This will start timidity in the background to listen for MIDI output and play it.
- 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.
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:
This should update your Euterpea installation.
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.
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.