2021-10-02 18:21:51 +00:00
# Getting started
2021-10-11 19:05:06 +00:00
GHCup makes it easy to install specific versions of GHC on GNU/Linux,
macOS (aka Darwin), FreeBSD and Windows and can also bootstrap a fresh [Haskell developer environment ](./install/#supported-tools ) from scratch.
2022-04-02 18:11:09 +00:00
It follows the UNIX philosophy of [do one thing and do it well ](https://en.wikipedia.org/wiki/Unix_philosophy#Do_One_Thing_and_Do_It_Well ). 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 ).
2021-10-02 18:21:51 +00:00
## Installation
2021-10-04 19:40:48 +00:00
The following commands will download the `ghcup` binary into `~/.ghcup/bin` (or `C:\ghcup\bin` on windows) and then
run it to interactively install the [Haskell Toolchain ](#supported-tools ). These commands should be run as **non-root/non-admin
user**.
For Linux, macOS, FreeBSD or Windows Subsystem 2 for Linux, run this in a terminal:
2021-10-02 18:21:51 +00:00
```sh
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
```
2021-10-04 19:40:48 +00:00
For Windows, run this in a PowerShell session:
2021-10-02 18:21:51 +00:00
```psh
Set-ExecutionPolicy Bypass -Scope Process -Force;[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;Invoke-Command -ScriptBlock ([ScriptBlock]::Create((Invoke-WebRequest https://www.haskell.org/ghcup/sh/bootstrap-haskell.ps1 -UseBasicParsing))) -ArgumentList $true
```
2022-03-18 17:31:16 +00:00
There's also a [youtube video ](https://www.youtube.com/watch?v=bB4fmQiUYPw ) explaining installation on windows.
2021-10-11 19:05:06 +00:00
If you want to know what these scripts do, check out the [source code at the repository ](https://gitlab.haskell.org/haskell/ghcup-hs/-/tree/master/scripts/bootstrap ). Advanced users may want to perform a [manual installation ](#manual-install ) and GPG verify the binaries.
2022-01-06 07:54:27 +00:00
### Which versions get installed?
GHCup has two main channels for every tool: **recommended** and **latest** . By default, it installs *recommended* .
*latest* follows the latest release of every tool, while *recommended* is at the discretion of the GHCup maintainers and based on community adoption (hackage libraries, tools like HLS, stackage support, etc.) and known bugs.
Also see [tags and shortcuts ](../guide/#tags-and-shortcuts ) for more information.
2022-04-02 17:45:50 +00:00
## Next steps
2021-10-13 12:48:07 +00:00
2022-04-02 17:45:50 +00:00
1. Follow the [First steps guide ](../steps ) on how to build a "Hello world" program, use `ghc` , run an interactive REPL and create a Haskell project
2022-03-18 17:31:16 +00:00
2. To understand the difference and overlap of `stack` and `cabal` , read on [here ](https://gist.github.com/merijn/8152d561fb8b011f9313c48d876ceb07 )
2022-04-02 17:45:50 +00:00
3. To learn Haskell proper check out the links at [How to learn Haskell proper ](../steps#how-to-learn-haskell-proper )
2022-03-18 17:31:16 +00:00
4. To learn more about Haskell Toolchain management, check out the [ghcup user guide ](./guide.md )
2021-10-02 18:21:51 +00:00
2021-10-13 13:00:11 +00:00
## Uninstallation
On linux, just run `ghcup nuke` , then make sure any ghcup added lines in your `~/.bashrc` (or similar) are removed.
2022-03-18 17:31:16 +00:00
On windows, right click on the `Uninstall Haskell.ps1` PowerShell script on your Desktop and select *Run with PowerShell* .
2021-10-13 13:00:11 +00:00
2021-10-02 18:21:51 +00:00
## Supported tools
2021-10-04 19:40:48 +00:00
GHCup supports the following tools, which are also known as the **Haskell Toolchain** :
2021-10-02 18:21:51 +00:00
2022-03-18 17:31:16 +00:00
< details > < summary > Show all supported < a href = 'https://www.haskell.org/ghc/' > GHC< / a > versions< / summary >
2022-03-08 21:23:29 +00:00
< table >
< thead > < tr > < th > GHC Version< / th > < th > Tags< / th > < / tr > < / thead >
< tbody >
2022-05-28 14:44:15 +00:00
< tr > < td > 9.2.3< / td > < td > < span style = "color:blue" > latest< / span > , base-4.16.2.0< / td > < / tr >
< tr > < td > 9.2.2< / td > < td > base-4.16.1.0< / td > < / tr >
2022-03-18 17:31:16 +00:00
< tr > < td > 9.2.1< / td > < td > base-4.16.0.0< / td > < / tr >
< tr > < td > 9.0.2< / td > < td > base-4.15.1.0< / td > < / tr >
< tr > < td > 9.0.1< / td > < td > base-4.15.0.0< / td > < / tr >
< tr > < td > 8.10.7< / td > < td > < span style = "color:green" > recommended< / span > , base-4.14.3.0< / td > < / tr >
< tr > < td > 8.10.6< / td > < td > base-4.14.3.0< / td > < / tr >
< tr > < td > 8.10.5< / td > < td > base-4.14.2.0< / td > < / tr >
< tr > < td > 8.10.4< / td > < td > base-4.14.1.0< / td > < / tr >
< tr > < td > 8.10.3< / td > < td > base-4.14.1.0< / td > < / tr >
< tr > < td > 8.10.2< / td > < td > base-4.14.1.0< / td > < / tr >
< tr > < td > 8.10.1< / td > < td > base-4.14.0.0< / td > < / tr >
< tr > < td > 8.8.4< / td > < td > base-4.13.0.0< / td > < / tr >
< tr > < td > 8.8.3< / td > < td > base-4.13.0.0< / td > < / tr >
< tr > < td > 8.8.2< / td > < td > base-4.13.0.0< / td > < / tr >
< tr > < td > 8.8.1< / td > < td > base-4.13.0.0< / td > < / tr >
< tr > < td > 8.6.5< / td > < td > base-4.12.0.0< / td > < / tr >
< tr > < td > 8.6.4< / td > < td > base-4.12.0.0< / td > < / tr >
< tr > < td > 8.6.3< / td > < td > base-4.12.0.0< / td > < / tr >
< tr > < td > 8.6.2< / td > < td > base-4.12.0.0< / td > < / tr >
< tr > < td > 8.6.1< / td > < td > base-4.12.0.0< / td > < / tr >
< tr > < td > 8.4.4< / td > < td > base-4.11.1.0< / td > < / tr >
< tr > < td > 8.4.3< / td > < td > base-4.11.1.0< / td > < / tr >
< tr > < td > 8.4.2< / td > < td > base-4.11.1.0< / td > < / tr >
< tr > < td > 8.4.1< / td > < td > base-4.11.0.0< / td > < / tr >
< tr > < td > 8.2.2< / td > < td > base-4.10.1.0< / td > < / tr >
< tr > < td > 8.0.2< / td > < td > base-4.9.1.0< / td > < / tr >
< tr > < td > 7.10.3< / td > < td > base-4.8.2.0< / td > < / tr >
2022-03-08 21:23:29 +00:00
< / tbody >
< / table >
< / details >
2022-03-18 17:31:16 +00:00
< details > < summary > Show all supported < a href = 'https://cabal.readthedocs.io/en/stable/' > cabal-install< / a > versions< / summary >
< table >
2022-03-08 21:23:29 +00:00
< thead > < tr > < th > Cabal Version< / th > < th > Tags< / th > < / tr > < / thead >
< tbody >
< tr > < td > 3.6.2.0< / td > < td > < span style = "color:blue" > latest< / span > , < span style = "color:green" > recommended< / span > < / td > < / tr >
2022-03-18 17:31:16 +00:00
< tr > < td > 3.6.0.0< / td > < td > < / td > < / tr >
< tr > < td > 3.4.1.0< / td > < td > < / td > < / tr >
< tr > < td > 3.4.0.0< / td > < td > < / td > < / tr >
< tr > < td > 3.2.0.0< / td > < td > < / td > < / tr >
< tr > < td > 3.0.0.0< / td > < td > < / td > < / tr >
< tr > < td > 2.4.1.0< / td > < td > < / td > < / tr >
2022-03-08 21:23:29 +00:00
< / tbody >
< / table >
< / details >
2022-03-18 17:31:16 +00:00
< details > < summary > Show all supported < a href = 'https://haskell-language-server.readthedocs.io/en/stable/' > HLS< / a > versions< / summary >
2022-03-08 21:23:29 +00:00
< table >
< thead > < tr > < th > HLS Version< / th > < th > Tags< / th > < / tr > < / thead >
< tbody >
2022-05-03 09:40:05 +00:00
< tr > < td > 1.7.0.0< / td > < td > < span style = "color:blue" > latest< / span > , < span style = "color:green" > recommended< / span > < / td > < / tr >
< tr > < td > 1.6.1.0< / td > < td > < / td > < / tr >
2022-03-18 17:31:16 +00:00
< tr > < td > 1.6.0.0< / td > < td > < / td > < / tr >
< tr > < td > 1.5.1< / td > < td > < / td > < / tr >
< tr > < td > 1.5.0< / td > < td > < / td > < / tr >
< tr > < td > 1.4.0< / td > < td > < / td > < / tr >
< tr > < td > 1.3.0< / td > < td > < / td > < / tr >
< tr > < td > 1.2.0< / td > < td > < / td > < / tr >
< tr > < td > 1.1.0< / td > < td > < / td > < / tr >
2022-03-08 21:23:29 +00:00
< / tbody >
< / table >
< / details >
2022-03-18 17:31:16 +00:00
< details > < summary > Show all supported < a href = 'https://docs.haskellstack.org/en/stable/README/' > Stack< / a > versions< / summary >
2022-03-08 21:23:29 +00:00
< table >
< thead > < tr > < th > Stack Version< / th > < th > Tags< / th > < / tr > < / thead >
< tbody >
< tr > < td > 2.7.5< / td > < td > < span style = "color:blue" > latest< / span > , < span style = "color:green" > recommended< / span > < / td > < / tr >
2022-03-18 17:31:16 +00:00
< tr > < td > 2.7.3< / td > < td > < / td > < / tr >
< tr > < td > 2.7.1< / td > < td > < / td > < / tr >
< tr > < td > 2.5.1< / td > < td > < / td > < / tr >
2022-03-08 21:23:29 +00:00
< / tbody >
< / table >
< / details >
2021-10-02 18:21:51 +00:00
## Supported platforms
This list may not be exhaustive and specifies support for bindists only.
| Platform | Architecture | ghcup | GHC | cabal | HLS | stack |
| ------ | ------ | ------ | ------ | ------ | ------ | ------ |
| Windows 7 | amd64 | ❔ | ✅ | ✅ | ✅ | ✅ |
| Windows 10 | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows Server 2016 | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows Server 2019 | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows Server 2022 | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows WSL1 | amd64 | ❌ | ❔ | ❔ | ❔ | ❔ |
| Windows WSL2 | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
2021-10-06 15:27:47 +00:00
| MacOS >=10.13 | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| MacOS < 10.13 | amd64 | ❌ | ❔ | ❔ | ❔ | ❔ |
2021-10-02 18:21:51 +00:00
| MacOS | aarch64 | ✅ | ✅ | ✅ | ⚠️ | ❌ |
| FreeBSD | amd64 | ✅ | ⚠️ | ✅ | ⚠️ | ❌ |
| Linux generic | x86 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Linux generic | amd64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Linux generic | aarch64 | ✅ | ⚠️ | ✅ | ⚠️ | ❌ |
| Linux generic | armv7 | ✅ | ⚠️ | ✅ | ⚠️ | ❌ |
2021-10-04 19:40:48 +00:00
### Windows 7
2021-10-02 18:21:51 +00:00
May or may not work, several issues:
2021-10-11 19:11:29 +00:00
* [https://gitlab.haskell.org/haskell/ghcup-hs/-/issues/140 ](https://gitlab.haskell.org/haskell/ghcup-hs/-/issues/140 )
* [https://gitlab.haskell.org/haskell/ghcup-hs/-/issues/197 ](https://gitlab.haskell.org/haskell/ghcup-hs/-/issues/197 )
2021-10-02 18:21:51 +00:00
2021-10-04 19:40:48 +00:00
### WSL1
2021-10-02 18:21:51 +00:00
Unsupported. GHC may or may not work. Upgrade to WSL2.
2022-02-03 14:39:11 +00:00
### MacOS <10.13
2021-10-02 18:21:51 +00:00
2022-02-03 14:39:11 +00:00
Not supported. Would require separate binaries, since >=10.13 binaries are incompatible.
2021-10-02 18:21:51 +00:00
Please upgrade.
2021-10-04 19:40:48 +00:00
### MacOS aarch64
2021-10-02 18:21:51 +00:00
2022-02-03 14:39:11 +00:00
HLS bindists are still experimental. Stack has only unofficial binaries for this platform.
There are various issues with GHC itself.
2021-10-02 18:21:51 +00:00
2021-10-04 19:40:48 +00:00
### FreeBSD
2021-10-02 18:21:51 +00:00
Lacks some upstream bindists and may need compat libs, since most bindists are built on FreeBSD-12.
HLS bindists are experimental.
2021-10-04 19:40:48 +00:00
### Linux ARMv7/AARCH64
2021-10-02 18:21:51 +00:00
2022-02-03 14:39:11 +00:00
Lower availability of bindists. Stack and HLS binaries are experimental.
2021-10-02 18:21:51 +00:00
## Manual install
Download the binary for your platform at [https://downloads.haskell.org/~ghcup/ ](https://downloads.haskell.org/~ghcup/ )
and place it into your `PATH` anywhere.
2022-05-16 19:39:13 +00:00
If you want to GPG verify the binaries, import the following keys first: `7784930957807690A66EBDBE3786C5262ECB4A3F` and `FE5AB6C91FEA597C3B31180B73EDE9E8CFBAEF01` .
2021-10-04 19:40:48 +00:00
2021-10-02 18:21:51 +00:00
Then adjust your `PATH` in `~/.bashrc` (or similar, depending on your shell) like so:
```sh
export PATH="$HOME/.cabal/bin:$HOME/.ghcup/bin:$PATH"
```
## Vim integration
See [ghcup.vim ](https://github.com/hasufell/ghcup.vim ).
2021-10-12 10:58:21 +00:00
## Get help
* [Libera IRC chat on #haskell-ghcup or #haskell ](https://kiwiirc.com/nextclient/irc.libera.chat/?nick=Guest%7C?#haskell,#haskell-ghcup )
* [GHCup issue tracker ](https://gitlab.haskell.org/haskell/ghcup-hs/issues )
* [Matrix ](https://app.element.io/#/room/#haskell-tooling:matrix.org )
* [Discord ](https://discord.gg/pKYf3zDQU7 )
