mirror of
https://github.com/commercialhaskell/stackage.git
synced 2026-01-16 17:28:29 +01:00
Use table of contents and remove some redundant sections about PATH
chrisdone
parent
32e3945014
commit
bca6f25ea7
@ -1,16 +1,22 @@
|
||||
# Quick start
|
||||
### Table of Contents
|
||||
|
||||
If you want to understand things in-depth, [please start reading at the overview](#overview). If you simply want to get up-and-running, choose your OS:
|
||||
* [Installing Haskell from scratch](#installing-haskell-from-scratch) (GHC, Cabal, packages, Stackage)
|
||||
* [Ubuntu](#ubuntu)
|
||||
* [Linux (general)](#other-linux)
|
||||
* [Mac OS X](#mac-os-x)
|
||||
* [Windows](#windows)
|
||||
* [Using on existing Haskell setup](#using-on-existing-haskell-setup) (GHC, Cabal already installed)
|
||||
* [Using a Stackage snapshot](#using-a-stackage-snapshot)
|
||||
* [Using a cabal.config file (simplest usage)](#using-a-cabalconfig-file-simplest-usage)
|
||||
* [Detailed topics](#detailed-topics)
|
||||
* [Snapshot types](#snapshot-types)
|
||||
* [Haskell Platform vs raw tools](#haskell-platform-vs-raw-tools)
|
||||
|
||||
* [Ubuntu](#ubuntu)
|
||||
* [Other Linux](#other-linux)
|
||||
* [Mac OS X](#mac-os-x)
|
||||
* [Windows](#windows)
|
||||
* [I already have my system up and running, what's the simplest thing that I can do?](#simplest-usage)
|
||||
# Installing Haskell from scratch
|
||||
|
||||
Note: much of the information below is inspired by [bitemyapp's guide](https://github.com/bitemyapp/learnhaskell#getting-started).
|
||||
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
|
||||
### Ubuntu
|
||||
|
||||
We'll use [Herbert's PPAs](http://launchpad.net/~hvr/+archive/ghc).
|
||||
|
||||
@ -31,7 +37,7 @@ 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
|
||||
### 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](https://github.com/bitemyapp/learnhaskell#getting-started).
|
||||
2. `wget http://hackage.haskell.org/package/cabal-install-1.20.0.3/cabal-install-1.20.0.3.tar.gz`
|
||||
@ -42,7 +48,7 @@ steps are provided here for completeness.
|
||||
7. Edit your `~/.cabal/config` file, and replace your `remote-repo:` line with the line [available here](http://www.stackage.org/alias/fpcomplete/unstable-ghc78-exclusive)
|
||||
8. Run `cabal update` again, and you're all ready to go!
|
||||
|
||||
## Mac OS X
|
||||
### 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
|
||||
@ -54,7 +60,7 @@ such a snapshot automatically.)
|
||||
4. Edit your `~/.cabal/config` file, and replace your `remote-repo:` line with the line [available here](http://www.stackage.org/alias/fpcomplete/unstable-ghc78hp-exclusive)
|
||||
5. Run `cabal update` again, and you're all ready to go!
|
||||
|
||||
## Windows
|
||||
### 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
|
||||
@ -66,17 +72,11 @@ such a snapshot automatically.)
|
||||
4. Edit your ` %appdata%\cabal\config` file, and replace your `remote-repo:` line with the line [available here](http://www.stackage.org/alias/fpcomplete/unstable-ghc78hp-exclusive)
|
||||
5. Run `cabal update` again, and you're all ready to go!
|
||||
|
||||
## Simplest usage
|
||||
# Using on existing Haskell setup
|
||||
|
||||
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](http://www.stackage.org/alias/fpcomplete/unstable-ghc78-exclusive/cabal.config)
|
||||
into your projects working directory (next to your `.cabal` file). Poof! Your
|
||||
project is now (mostly) Stackage-enabled.
|
||||
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.
|
||||
|
||||
# Switching to a new snapshot
|
||||
### Using a Stackage snapshot
|
||||
|
||||
You have the following options when switching to a new snapshot:
|
||||
|
||||
@ -86,7 +86,19 @@ You have the following options when switching to a new snapshot:
|
||||
3. Running `cabal update`
|
||||
2. Switch in a sandbox. You can currently use `hsenv` to do that. cabal sandboxes are currently limited
|
||||
|
||||
# Overview
|
||||
### 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](http://www.stackage.org/alias/fpcomplete/unstable-ghc78-exclusive/cabal.config)
|
||||
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](http://www.stackage.org/) 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](https://www.haskell.org/platform/), or installing them separately. We'll cover these options in a bit.
|
||||
|
||||
@ -98,7 +110,7 @@ Currently, we support three different system configurations. Each of these optio
|
||||
|
||||
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
|
||||
### 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:
|
||||
|
||||
@ -107,58 +119,3 @@ Stackage Server is designed to work either with or without Haskell Platform. The
|
||||
* 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.
|
||||
|
||||
## Set PATH to include cabal's bin directory
|
||||
|
||||
This applies to both Haskell Platform and manual installs. A very common source of confusion for new users is that executables are not available. For example, "I ran `cabal install alex`, but it's complaining that `alex` isn't available." It's __vitally important__ that you make sure that your PATH environment variable is configured to include cabal's bin directory.
|
||||
|
||||
On most POSIX systems, this directory will be `$HOME/.cabal/bin`. A simple way to do this is to edit your `~/.bashrc` and place in there:
|
||||
|
||||
```bash
|
||||
export PATH=$HOME/.cabal/bin:$PATH
|
||||
```
|
||||
|
||||
In Mac OS X, cabal installs binaries to: `$HOME/Library/Haskell/bin`.
|
||||
|
||||
In Windows Vista or newer Windows, cabal installs binaries to: `%APPDATA%\cabal\bin`.
|
||||
`%APPDATA%` is Windows specific Environment variable. Usually, this variable specifies `C:\Users\%USERNAME%\AppData\Roaming`.
|
||||
|
||||
## Haskell Platform
|
||||
|
||||
If you've elected to install Haskell Platform, please follow the instructions [on the Haskell Platform website](https://www.haskell.org/platform/).
|
||||
|
||||
__NOTE__: Distributions like Ubuntu often include a package including the Haskell Platform. Often, this package is very out-of-date, and will not be compatible with either Stackage Server or most recent releases of software on Hackage. Be sure you're installing version 2014.2.0.0 of the platform.
|
||||
|
||||
## Manual installation
|
||||
|
||||
Most Linux distributions provide some means of installing GHC and cabal-install. Like with Haskell Platform, make sure you're installing a recent enough version of each tool. Stackage Server supports GHC 7.6.3 and 7.8.3. It will theoretically work with any version of cabal-install since 1.16, though I'd highly recommend using 1.18 or higher, since there are some important dependency solver bug fixes.
|
||||
|
||||
Instead of enumerating a bunch of distro-specific instructions here, please [view the instructions from bitemyapp](https://github.com/bitemyapp/learnhaskell#getting-started). Alternatively, you may follow the instructions below to get GHC and cabal-install directly:
|
||||
|
||||
### 1. Install GHC
|
||||
|
||||
GHC has its own web site with license information, FAQ, download links and changelogs. Depending on your operating system, there should be a package made for its package manager, otherwise (e.g. Windows) it will be an installer.
|
||||
|
||||
You can also download the .tar.gz/.zip and unpack and install the executables and so forth manually.
|
||||
|
||||
Or you can even install from source, for which there is documentation.
|
||||
|
||||
[Download GHC now →](https://www.haskell.org/ghc/download)
|
||||
|
||||
### 2. Install cabal-install
|
||||
|
||||
After installing GHC, you will want the Haskell package manager:
|
||||
|
||||
[Get the Cabal archive →](https://hackage.haskell.org/package/cabal-install)
|
||||
|
||||
Download the tar.gz file (listed under Downloads at the bottom of the page), extract and inside the resulting directory, run:
|
||||
|
||||
```sh
|
||||
$ sh ./bootstrap.sh
|
||||
```
|
||||
|
||||
This will automatically download and install all the packages necessary to setup Cabal install. You should now be able to run the `cabal` executable. To test this, run:
|
||||
|
||||
```sh
|
||||
$ cabal update
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user