Preparing your system to use Stackage

Table of Contents

• Installing Haskell from scratch (GHC, Cabal, packages, Stackage)
  • Ubuntu
  • Linux (general)
  • Mac OS X
  • Windows
• Using on existing Haskell setup (GHC, Cabal already installed)
  • Using a Stackage snapshot
  • Using a cabal.config file (simplest usage)
• Detailed topics
  • Snapshot types
  • Haskell Platform vs raw tools

Installing Haskell from scratch

Starting with a fresh Haskell installation requires a few steps (getting GHC, cabal, etc). Please see the heading that suits your platform for detailed instructions.

Ubuntu

We'll use Herbert's PPAs.

1. sudo apt-get update

2. sudo apt-get install software-properties-common

3. sudo add-apt-repository -y ppa:hvr/ghc

4. sudo apt-get update

5. sudo apt-get install cabal-install-1.20 ghc-7.8.3

6. Add the following to your PATH environment variable:

   ~/.cabal/bin:/opt/cabal/1.20/bin:/opt/ghc/7.8.3/bin
   

7. cabal update

8. Edit your ~/.cabal/config file, and replace your remote-repo: line with the line available here

9. Run cabal update again, and you're all ready to go!

Note: Many of these steps are likely unnecessary, e.g., if you already have software-properties-common installed, you don't need to reinstall it. All steps are provided here for completeness.

Other Linux

1. Install GHC 7.8.3, and make sure it is in your PATH. Also add ~/.cabal/bin to your PATH. For more information, see bitemyapp's guide.
2. wget http://hackage.haskell.org/package/cabal-install-1.20.0.3/cabal-install-1.20.0.3.tar.gz
3. tar zxfv cabal-install-1.20.0.3.tar.gz
4. cd cabal-install-1.20.0.3
5. sh bootstrap.sh
6. cabal update
7. Edit your ~/.cabal/config file, and replace your remote-repo: line with the line available here
8. Run cabal update again, and you're all ready to go!

Mac OS X

It is highly recommended to install GHC via the Haskell Platform. Therefore, you should also use a Haskell Platform snapshot. (These instructions will use such a snapshot automatically.)

1. Install Haskell Platform for Mac
2. Modify your PATH to include $HOME/Library/Haskell/bin
3. cabal update
4. Edit your ~/.cabal/config file, and replace your remote-repo: line with the line available here
5. Run cabal update again, and you're all ready to go!

Windows

It is highly recommended to install GHC via the Haskell Platform. Therefore, you should also use a Haskell Platform snapshot. (These instructions will use such a snapshot automatically.)

1. Install Haskell Platform for Windows
2. Modify your PATH to include %APPDATA%\cabal\bin
3. cabal update
4. Edit your %appdata%\cabal\config file, and replace your remote-repo: line with the line available here
5. Run cabal update again, and you're all ready to go!

Using on existing Haskell setup

If you already have GHC, Cabal, etc. installed and setup, there are two options for using Stackage. See the headings below for which suits you better.

Using a Stackage snapshot

You have the following options when switching to a new snapshot:

1. Switch globally, by:
   1. Updating your ~/.cabal/config file with a new remote-repo.
   2. Deleting your ~/.ghc directory.
   3. Running cabal update
2. Switch in a sandbox. You can currently use hsenv to do that. cabal sandboxes are currently limited

Using a cabal.config file (simplest usage)

If you already have your system up-and-running with GHC and cabal, and don't want to play around with modifying your remote-repo, you can still get most of the benefits of Stackage. Assuming you're using GHC 7.8, download the current cabal.config file into your projects working directory (next to your .cabal file). Poof! Your project is now (mostly) Stackage-enabled.

Detailed topics

Snapshot types

These instructions are for users wishing to use Stackage Server as their package repository. There are two different tools that need to be installed on your system to use Stackage Server: GHC, and cabal-install. There are generally speaking two ways of getting these tools: via Haskell Platform, or installing them separately. We'll cover these options in a bit.

Currently, we support three different system configurations. Each of these options has its own set of Stackage snapshots available, and each of these in turn has exclusive and inclusive variants.

• Haskell Platform 2014.2.0.0: exclusive and inclusive
• GHC 7.8.3 with cabal-install: exclusive and inclusive
• GHC 7.6.3 with cabal-install: exclusive and inclusive

You'll need to choose the appropriate one of the above six snapshots based on what installation you do, and whether you want exclusive or inclusive snapshots. The links above will automatically redirect you to the most recent snapshot available.

Haskell Platform vs raw tools

Stackage Server is designed to work either with or without Haskell Platform. The decision on which route to take is entirely up to you; here are some general guidelines to help you decide:

• On Windows, building cabal-install manually is difficult. Additionally, installing the network package requires installing an extra tool (msys). Unless you know what you're doing, you likely want to install Haskell Platform.

• On Mac OS X, there are complications regarding the correct CPP toolchain to get set up. There are some scripts available to help, but the Haskell Platform provides a fully functioning toolset. Like Windows, you're likely safer sticking with Haskell Platform.

• The biggest downside of Haskell Platform is that it ties you to older versions of dependencies. The biggest two examples in the current platform release are attoparsec and QuickCheck. For the former, the version included by Haskell Platform has a known security vulnerability. The QuickCheck version included is before a major API change, which a number of packages are beginning to use.

  The choice is yours, but my advice for users not on Windows or Mac is to not use Haskell Platform.