Update README

README.md

@@ -1,37 +1,144 @@
-# ghcup
+`ghcup` makes it easy to install specific versions of `ghc` on GNU/Linux,
+macOS (aka Darwin) and FreeBSD and can also bootstrap a fresh Haskell developer environment from scratch.
+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).
 
-A rewrite of ghcup in haskell.
+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).
 
-## TODO
+*Ubuntu users may prefer [hvr's ppa](https://launchpad.net/~hvr/+archive/ubuntu/ghc).*
 
-* create static ghcup binaries
-    * adjust url in GHCupDownloads
-* add print-system-reqs command
+## Table of Contents
 
-## Motivation
+   * [Installation](#installation)
+   * [Usage](#usage)
+     * [Manpages](#manpages)
+   * [Design goals](#design-goals)
+   * [How](#how)
+   * [Known users](#known-users)
+   * [Known problems](#known-problems)
+   * [FAQ](#faq)
 
-Maintenance problems:
+## Installation
 
-* platform incompatibilities regularly causing breaking bugs:
-	* [Mktemp not working properly on macOS](https://gitlab.haskell.org/haskell/ghcup/issues/130)
-	* [ln: illegal option -- T on macOS Catalina](https://gitlab.haskell.org/haskell/ghcup/issues/123)
-	* [Wrong tar flag on darwin](https://gitlab.haskell.org/haskell/ghcup/issues/119))
-* refactoring being difficult due to POSIX sh
+### Simple bootstrap
 
-Benefits of a rewrite:
+Follow the instructions at [https://www.haskell.org/ghcup/](https://www.haskell.org/ghcup/)
 
-* Features such as installing [release candidates](https://gitlab.haskell.org/haskell/ghcup/issues/94) or [HEAD builds](https://gitlab.haskell.org/haskell/ghcup/issues/65) can be more conveniently implemented in a rewrite
-* Refactoring will be easier
-* Better tool support (such as linting the downloads file)
-* saner downloads file format (such as JSON)
+### Manual install
 
-Downsides:
+Download the binary for your platform at [https://github.com/hasufell/ghcup-hs/releases](https://github.com/hasufell/ghcup-hs/releases)
+and place it into your `PATH` anywhere.
 
-* building static binaries for all platforms (and possibly causing SSL/DNS problems)
-* still bootstrapping those binaries via a POSIX sh script
+Then adjust your `PATH` in `~/.bashrc` (or similar, depending on your shell) like so:
 
-## Goals
+```sh
+export PATH="$HOME/.cabal/bin:$HOME/.ghcup/bin:$PATH"
+```
+
+## Usage
+
+See `ghcup --help`.
+
+Common use cases are:
+
+```sh
+# list available ghc/cabal versions
+ghcup list
+
+# install the recommended GHC version
+ghcup install ghc
+
+# install a specific GHC version
+ghcup install ghc -v 8.2.2
+
+# set the currently "active" GHC version
+ghcup set -v 8.4.4
+
+# install cabal-install
+ghcup install cabal
+
+# update ghcup itself
+ghcup upgrade
+```
+
+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.
+
+### Manpages
+
+For man pages to work you need [man-db](http://man-db.nongnu.org/) as your `man` provider, then issue `man ghc`. Manpages only work for the currently set ghc.
+`MANPATH` may be required to be unset.
+
+## Design goals
+
+1. simplicity
+2. non-interactive
+3. portable (eh)
+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
+
+## 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`.
+
+## Known users
+
+* [vabal](https://github.com/Franciman/vabal)
+
+## Known problems
+
+### 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.
+
+### Precompiled binaries
+
+Since this uses precompiled binaries you may run into
+several problems.
+
+#### Missing libtinfo (ncurses)
+
+You may run into problems with *ncurses* and **missing libtinfo**, in case
+your distribution doesn't use the legacy way of building
+ncurses and has no compatibility symlinks in place.
+
+Ask your distributor on how to solve this or
+try to compile from source via `ghcup compile <version>`.
+
+#### 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://gitlab.haskell.org/haskell/ghcup/issues/58) for a discussion.
+
+### Compilation
+
+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
+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.
+
+## FAQ
+
+1. Why reimplement stack?
+
+ghcup is not a reimplementation of stack. The only common part is automatic installation of GHC, but even that differs in scope and design.
+
+2. Why not support windows?
+
+Consider using [Chocolatey](https://chocolatey.org/search?q=ghc) or [ghcups](https://github.com/kakkun61/ghcups).
 
-* Correct low-level code
-* Good exception handling
-* Cleaner user interface