ghcup/README.md

147 lines
5.1 KiB
Markdown
Raw Normal View History

2018-10-16 06:41:42 +00:00
[![GitHub release](https://img.shields.io/github/release/haskell/ghcup.svg)](https://github.com/haskell/ghcup/releases)
[![Build Status](https://travis-ci.org/haskell/ghcup.svg?branch=master)](https://travis-ci.org/haskell/ghcup)
[![license](https://img.shields.io/github/license/haskell/ghcup.svg)](COPYING)
2018-09-29 15:29:45 +00:00
`ghcup` makes it easy to install specific versions of `ghc` on GNU/Linux as well as macOS (aka Darwin), and can also bootstrap a fresh Haskell developer environment from scratch.
2018-10-20 01:42:25 +00:00
It follows the unix UNIX philosophy of [do one thing and do it well](https://en.wikipedia.org/wiki/Unix_philosophy#Do_One_Thing_and_Do_It_Well).
2018-09-29 09:27:45 +00:00
2018-10-19 15:57:26 +00:00
Similar in scope to [rustup](https://github.com/rust-lang-nursery/rustup.rs), [pyenv](https://github.com/pyenv/pyenv) and [jenv](http://www.jenv.be).
*Ubuntu users may prefer [hvr's ppa](https://launchpad.net/~hvr/+archive/ubuntu/ghc).*
2019-01-13 06:34:44 +00:00
*This project was started when [CM](https://github.com/capital-match) was switching from stack to [cabal nix-style builds](https://www.haskell.org/cabal/users-guide/nix-local-build-overview.html).*
2018-09-29 17:00:12 +00:00
## Table of Contents
* [Installation](#installation)
* [Usage](#usage)
2018-11-24 11:35:17 +00:00
* [Design goals](#design-goals)
2018-10-19 15:52:02 +00:00
* [How](#how)
2019-01-07 08:03:59 +00:00
* [Known users](#known-users)
2018-09-29 17:00:12 +00:00
* [Known problems](#known-problems)
2018-09-29 09:27:45 +00:00
## Installation
2019-01-07 08:03:59 +00:00
Choose one of the following installation methods.
### Simple bootstrap of ghcup, GHC and cabal-install
```sh
# complete bootstrap
curl https://raw.githubusercontent.com/haskell/ghcup/master/bootstrap-haskell -sSf | sh
# prepare your environment
. "$HOME/.ghcup/env"
echo '. $HOME/.ghcup/env' >> "$HOME/.bashrc" # or similar
# now create a project, such as:
mkdir myproject && cd myproject
cabal init -n --is-executable
cabal v2-run
```
### Manual install
2018-10-15 14:15:57 +00:00
Just place the `ghcup` shell script into your `PATH` anywhere.
E.g.:
2018-09-29 09:27:45 +00:00
2018-10-15 16:22:37 +00:00
```sh
2018-10-20 01:46:58 +00:00
( mkdir -p ~/.ghcup/bin && curl https://raw.githubusercontent.com/haskell/ghcup/master/ghcup > ~/.ghcup/bin/ghcup && chmod +x ~/.ghcup/bin/ghcup) && echo "Success"
```
2018-10-15 16:22:37 +00:00
Then adjust your `PATH` in `~/.bashrc` (or similar, depending on your shell) like so, for example:
```sh
2018-10-20 01:46:58 +00:00
export PATH="$HOME/.cabal/bin:$HOME/.ghcup/bin:$PATH"
2018-10-15 16:22:37 +00:00
```
2019-01-07 08:03:59 +00:00
Security aware users may want to use the files from the [release page](https://github.com/haskell/ghcup/releases)
and verify the gpg signatures.
2018-09-29 09:27:45 +00:00
## Usage
2018-09-29 17:17:14 +00:00
See `ghcup --help`.
2018-09-29 09:27:45 +00:00
2018-10-30 03:34:40 +00:00
Common use cases are:
```sh
# install the last known "best" GHC version
ghcup install
# install a specific GHC version
ghcup install 8.2.2
# set the currently "active" GHC version
ghcup set 8.4.4
# install cabal-install
ghcup install-cabal
# update cabal-install
cabal new-install cabal-install
```
2018-10-20 01:42:25 +00:00
Generally this is meant to be used with [`cabal-install`](https://hackage.haskell.org/package/cabal-install), which
handles your haskell packages and can demand that [a specific version](https://cabal.readthedocs.io/en/latest/nix-local-build.html#cfg-flag---with-compiler) of `ghc` is available, which `ghcup` can do.
2018-11-24 11:35:17 +00:00
## Design goals
1. simplicity
2. non-interactive
3. portable
4. do one thing and do it well (UNIX philosophy)
### Non-goals
1. invoking `sudo`, `apt-get` or *any* package manager
2. handling system packages
3. handling cabal projects
4. being a stack alternative
2018-10-19 15:52:02 +00:00
## How
Installs a specified GHC version into `~/.ghcup/ghc/<ver>`, and places `ghc-<ver>` symlinks in `~/.ghcup/bin/`.
Optionally, an unversioned `ghc` link can point to a default version of your choice.
This uses precompiled GHC binaries that have been compiled on fedora/debian by [upstream GHC](https://www.haskell.org/ghc/download_ghc_8_6_1.html#binaries).
Alternatively, you can also tell it to compile from source (note that this might fail due to missing requirements).
In addition this script can also install `cabal-install`.
2019-01-07 08:03:59 +00:00
## Known users
* [vabal](https://github.com/Franciman/vabal)
2018-10-19 13:41:12 +00:00
## Known problems
2018-09-29 09:27:45 +00:00
2018-10-19 13:41:12 +00:00
### Limited distributions supported
Currently only GNU/Linux distributions compatible with the [upstream GHC](https://www.haskell.org/ghc/download_ghc_8_6_1.html#binaries) binaries are supported.
2018-09-29 09:27:45 +00:00
### Precompiled binaries
2018-09-29 09:27:45 +00:00
Since this uses precompiled binaries you may run into
2019-02-05 01:12:06 +00:00
several problems.
#### Missing libtinfo (ncurses)
You may run into problems with *ncurses* and **missing libtinfo**, in case
2018-09-29 09:27:45 +00:00
your distribution doesn't use the legacy way of building
ncurses and has no compatibility symlinks in place.
2018-10-15 15:24:09 +00:00
Ask your distributor on how to solve this or
try to compile from source via `ghcup compile <version>`.
2019-02-05 01:12:06 +00:00
#### Libnuma required
This was a [bug](https://ghc.haskell.org/trac/ghc/ticket/15688) in the build system of some GHC versions that lead to
unconditionally enabled libnuma support. To mitigate this you might have to install the libnuma
package of your distribution. See [here](https://github.com/haskell/ghcup/issues/58) for a discussion.
### Compilation
2018-10-02 17:33:47 +00:00
Although this script can compile GHC for you, it's just a very thin
wrapper around the build system. It makes no effort in trying
2018-10-01 06:15:02 +00:00
to figure out whether you have the correct toolchain and
the correct dependencies. Refer to [the official docs](https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Linux)
on how to prepare your environment for building GHC.