Download and Installation for Euterpea 2

THIS PAGE IS OUTDATED.

If you landed here by following a link, you probably need to look at either the Home page or the Troubleshooting page.

Current Hackage versions: Euterpea 2.0.7, HSoM 1.0.0
Current development GitHub versions: Euterpea 2.0.8 (newer), HSoM 1.0.0 (same as Hackage).

Announcements

  • Supported GHC versions: currently Euterpea is only guaranteed on versions 8.2 through 8.6.5 on Mac and Windows. Newer versions are typically supported as they are released via Haskell Platform.
  • Haskell Platform 8.6.x users: you need to use cabal v1-update and cabal v1-install Euterpea instead of the old cabal update and install commands.
  • Windows Lilypond users: there are known compatibility problems between Lilypond and recent versions of Haskell Platform, including 8.4.3 and later versions. It results in errors relating to pthread.dll See the Windows section of the troubleshooting page for more details.

These instructions are for Euterpea version 2 and the Haskell School of Music companion library, called HSoM. On this page, you will find information and instructions on:

Supported GHC/Cabal and Operating System Versions

Euterpea is actively developed and tested with the following operating systems:

  • Windows 10 (whatever the most recent widely-available version is)
  • Mac OSX 10.14 (Mojave)
  • GHC 8.6.3-8.6.5
  • cabal 2.4+ (through 3.x)

Euterpea will also work with:

  • GHC >=8.0.2
  • Windows 7 to 8.1.
  • Mac OSX 10.10-10.12. Sometimes versions as far back as 10.8 will also work, but not always – it’s hit and miss.
  • The more popular Linux distributions. However, success is not guaranteed on arbitrary Linux machines due to the sheer number of different varieties available.

Euterpea and HSoM are NOT guaranteed to work if you are using any the following:

  • Extremely old hardware or operating systems (such as Windows XP, >10 year old Mac laptops, etc.)
  • Arbitrary Linux distributions (NixOS is known to be problematic due to its restrictions on older package versions)
  • Custom Haskell installations, such as those using newer versions of GHC than what Haskell Platform supports
  • Versions of Haskell Platform other than those recommended further down this page
  • Package managers other than Cabal (the Stack and Homebrew package managers are not actively supported)

Links to current versions:

Bug reporting:

Installing Haskell Platform

Recommended versions by operating system:

  • Windows: 
    • Windows 10 Creators Update and later: any version of Haskell Platform 8.2.1,Hakell Platform 8.4.3, or Haskell Platform 8.6.5. Core 64-bit is is the minimal requirement and recommended for most users. If you want to use other audio or graphics libraries beyond Euterpea/HSoM, then the full version is recommended if one exists for the version you’re using (for example, if you need the networks package then you should use the full version if possible). Versions earlier than 8.2 are not recommended, but if you must use an older one, you must use the 32-bit version of it for Euterpea’s MIDI playback to work.
    • Older Windows versions (10 prior to Creators Update, 7, 8, etc.) may need to use 32-bit 8.0.2 in order for Euterpea’s MIDI playback to work. Older Windows versions are no longer actively supported, so your mileage may vary.
  • Mac: Haskell Platform 8.4.3 or Haskell Platform 8.6.5 Note that 8.6.5 does not have a dedicated installer, so you must use a tool like ghcup. Inexperienced users may find setup for 8.4.3 simpler.
  • Linux: Haskell Platform 8.4.3  core or full. Euterpea and HSoM require ALSA and are unfortunately not guaranteed to install successfully on all flavors of Linux. Later versions have not been tested.

If you have older versions of Haskell Platform installed, it is recommended that you uninstall them first before installing a newer version. Windows users should also delete the “ghc” and “cabal” directories from their AppData folders if possible (you may need to enable viewing hidden folders to do this). Mac users can run sudo uninstall-hs and follow the directions given.

Antivirus notes: some antivirus software will attempt to block the download and/or installation of newer Haskell Platform versions even though it is safe. Avast is particularly aggressive about this and will even delete the downloaded installer when you try to run it. If you experience problems like this, disable your antivirus before downloading and installing Haskell Platform. You may also need to leave your antivirus off while you install Euterpea and HSoM to avoid further problems. Remember to re-enable your antivirus software after you’re done!

Installing Euterpea 2

The most recent, stable version of Euterpea 2 is available on Hackage. To install it:

  1. Follow the steps above to install Haskell Platform Full or Core.
  2. Open a command prompt (or PowerShell) or terminal and run the following to install from Hackage (you do not need to manually download anything; it will be done automatically):
cabal update

cabal install Euterpea

Cabal version 3.x users: you will need to use v1-style commands:

cabal v1-update

cabal v1-install Euterpea

You can check your cabal version by running:

cabal --version

Haskell Platform 8.6.3 users: you may need to use the command cabal v2-update to fetch the most recent list of packages from Hackage.

Note: cabal may prompt you to install another newer version of itself with “cabal install cabal-install” – you do not need to do this unless you want to, and doing so only installs a newer version of cabal, not whichever other library you are trying to install. If you update cabal, it is important that you still run the commands as shown above to install Euterpea itself.

OPTIONAL: Obtaining the Development Version from GitHub

More recent, development versions of Euterpea exist on GitHub. These are works in progress that are updated frequently and are not guaranteed to be stable.

Most users should use the Hackage version that you get from the instructions in the previous section. If you successfully installed Euterpea from Hackage and don’t specifically want the development version, you are done and can move on to the section for “Installing HSoM” if you want that library too.

If, however, you wish to install the newest development version from GitHub rather than using the most recent stable version on Hackage, you can do so as follows:

  1. Follow the instructions above for installing Haskell Platform.
  2. Download and unzip Euterpea 2 from GitHub.
  3. Open a command prompt (or PowerShell) or terminal within the folder where Euterpea.cabal is located.
  4. Run the following: 
    cabal update

cabal install

    (Cabal 3.x users should use v1-update and v1-install)

Haskell Platform 8.6.3 users: you may need to use the command cabal v2-update to fetch the most recent list of packages from Hackage.

Note: do NOT include “Euterpea” at the end of the installation command if you want the GitHub version (otherwise you will end up with the Hackage version!). If you already installed Euterpea or an earlier version, you may be warned that you are reinstalling and may be prompted to add extra flags such as –reinstall and/or –force-reinstalls. If these prompts occur, you can force cabal to overwrite your old installation with: cabal install –reinstall –force-reinstalls

Installing HSoM

  1. Follow the steps above to install Haskell Platform and Euterpea
  2. Open a command prompt (or PowerShell) or terminal and run the following: cabal install HSoM

If you need the most recent development (unstable) version of HSoM instead of the stable Hackage release, you can download it from GitHub and use the same approach as described in the section on installing the development version of Euterpea.

Mac users: if you are using HSoM’s MUIs, you must compile your code to executable. See the section further down on “Testing HSoM’s MUIs” for more information on how to do this.

Updating Euterpea/HSoM

Note that reinstallations can break dependencies in other libraries. If you have both Euterpea and HSoM installed, you must update Euterpea first before updating HSoM. After that, you must update any other libraries you have that depend on Euterpea/HSoM (if you have any).

If a new version has been released on Hackage, you can update your installations by opening a terminal/command prompt and running the following:

cabal update
cabal install Euterpea --reinstall --force-reinstalls

To update an installation from GitHub (applicable to HSoM and the development version of Euterpea):

  1. Download and unzip the new version from GitHub. Alternatively, you can use GitHub’s desktop or command line programs to automatically update your copy of the repository.
  2. Open a command prompt or terminal.
  3. Run the following, where MyFolder is the location of the .cabal file for the library you are installing: 
    cabal update

cd MyFolder

cabal install --reinstall --force-reinstalls

    (Remember to use v1-update and v1-install if using Cabal 3.x or later)

First Time Euterpea/HSoM Setup

Setting up MIDI

Euterpea’s play function and HSoM’s MUIs may not work out of the box depending on how your system is configured. See the page on Setting up MIDI for more information (some machines may require the use of playDev instead of play). If everything is set up correctly, you should hear a single tone by opening GHCi and running the following:

import Euterpea
play $ c 4 qn

 Testing HSoM’s MUIs

Open GHCi and run the following:

import HSoM.Examples.MUIExamples2
bifurcate

A window should open with various sliders and a list of MIDI output devices. You should hear notes generated automatically every second or so when the program first starts. If you hear nothing and/or if there are no MIDI output devices listed, try for Setting up MIDI. If you experience other problems, first try compiling to executable as described below (mainly an issue for Mac users), and then look at the troubleshooting section at the bottom of the page.

Compiling to Executable

On newer Macs, MUIs will not work from the GHCi interpreter. Failure cases range from unresponsive windows to threading errors. However, if this happens to you, you will still be able to run MUIs successfully by compiling your code to executable. Windows users can also benefit from compiling to executable with some MUIs because it can help speed up execution between frames, which is useful for interactive programs.

The easiest way to try compiling a MUI to executable the first time is to use one of the MUI example that comes included with HSoM. We’ll use bifurcate here.

First, create a file called Bifurcate.lhs with the following code:

> module Main where
> import HSoM.Examples.MUIExamples2
> main = bifurcate

Then, run compile this program to executable from a terminal with:

ghc Bifurcate.lhs

and then run it with this.

./Bifurcate

Mac and Linux users: you will need to have a synthesizer running first before starting ./Bifurcate or you will see no MIDI output device options and may get errors. You may also need to Ctrl+C out of the application from the terminal when you’re done; the red “close” button doesn’t always show up.

Mac users with older OSX versions and/or older versions of Haskell Platform: if the steps above still don’t work for you, then try running this:

cabal install GLUT --ghc-options="-optl-Wl,-framework,GLUT" --reinstall --jobs=1 --force-reinstalls

 Using Euterpea and HSoM

Once installed, you can import Euterpea and HSoM as libraries into your own Haskell source files. For example:

module MyModule where
import Euterpea
import HSoM

Any basic text editor can be used to create and modify Haskell source files, which have the extensions hs and lhs. A variety of editors preferred by Haskell coders exists on HaskellWiki. The hs format treats lines as code (as shown above) unless they are specifically denoted as comments with “–” for single lines or “{-” and “-}” to enclose multi-line comments. In contrast, lines of code in lhs files are denoted with a “>” at the start of each line and comments are written as regular text. In lhs format, the lines of code above would be:

> module MyModule where
> import Euterpea
> import HSoM

This is a comment. Comments must be separated from code lines by a blank line.

To load a source file, you can either double-click the file to load it in GHCi. Alternatively, from the command line, you can cd to the directory where your source file is and run:

ghci
:load MyModule

To compile Euterpea-based code with GHC, your hs/lhs file can have any name, but the module name at the top of the file must be Main and should have a main function to execute called main. We recommend compiling with one of the following sets of flags, for single threaded and multithreaded programs respectively:

ghc -O2 MyModule.lhs
ghc -O2 -threaded -rtsopts MyModule.lhs

NOTE: as of May 2016 we are aware of some situations in which recursive AudSF functions in Euterpea compile incorrectly using the -O2 flag for additional compiler optimizations. Currently the best solution is to compile without the -O2 flag (which is just “ghc MyModule.lhs”). If you are using Euterpea’s signal processing framework and observe results that seem incorrect, please try recompiling without optimization. 

See the Haskell School of Music textbook and the Examples page for more examples of using the Euterpea and HSoM libraries.

 Troubleshooting

Troubleshooting info has been moved to its own Troubleshooting Page.