hasufell/ghcup-hs
1
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Tweak appearance

Browse Source
This commit is contained in:
Julian Ospald 2021-10-04 21:40:48 +02:00
parent 9143ac97c5
commit e2f36611a1
Signed by: hasufell
GPG Key ID: 3786C5262ECB4A3F
5 changed files with 73 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
docs/about.md
View File

@ -40,7 +40,7 @@ cabal-install/HLS/stack are installed in `~/.ghcup/bin/<tool>-<ver>` and have un
## Known problems ## Known problems
#### Custom ghc version names ### Custom ghc version names
When installing ghc bindists with custom version names as outlined in When installing ghc bindists with custom version names as outlined in
[installing custom bindists](#installing-custom-bindists), then cabal might [installing custom bindists](#installing-custom-bindists), then cabal might
@ -51,16 +51,16 @@ as the current one via: `ghcup set ghc <version-name>`.
This problem doesn't exist for regularly installed GHC versions. This problem doesn't exist for regularly installed GHC versions.
#### Limited distributions supported ### 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. 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 ### Precompiled binaries
Since this uses precompiled binaries you may run into Since this uses precompiled binaries you may run into
several problems. several problems.
##### Missing libtinfo (ncurses) #### Missing libtinfo (ncurses)
You may run into problems with *ncurses* and **missing libtinfo**, in case You may run into problems with *ncurses* and **missing libtinfo**, in case
your distribution doesn't use the legacy way of building your distribution doesn't use the legacy way of building
@ -69,13 +69,13 @@ ncurses and has no compatibility symlinks in place.
Ask your distributor on how to solve this or Ask your distributor on how to solve this or
try to compile from source via `ghcup compile <version>`. try to compile from source via `ghcup compile <version>`.
##### Libnuma required #### 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 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 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. package of your distribution. See [here](https://gitlab.haskell.org/haskell/ghcup/issues/58) for a discussion.
#### Compilation ### Compilation
Although this script can compile GHC for you, it's just a very thin 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 wrapper around the build system. It makes no effort in trying
@ -83,7 +83,7 @@ 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) 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. on how to prepare your environment for building GHC.
#### Stack support ### Stack support
There may be a number of bugs when trying to make ghcup installed GHC versions work with stack, There may be a number of bugs when trying to make ghcup installed GHC versions work with stack,
such as: such as:
@ -95,7 +95,7 @@ issues discussed here:
- https://gitlab.haskell.org/haskell/ghcup-hs/-/issues/153 - https://gitlab.haskell.org/haskell/ghcup-hs/-/issues/153
#### Windows support ### Windows support
Windows support is in early stages. Since windows doesn't support symbolic links properly, Windows support is in early stages. Since windows doesn't support symbolic links properly,
ghcup uses a [shimgen wrapper](https://github.com/71/scoop-better-shimexe). It seems to work ghcup uses a [shimgen wrapper](https://github.com/71/scoop-better-shimexe). It seems to work
@ -108,17 +108,17 @@ Windows 7 and Powershell 2.0 aren't well supported at the moment, also see:
## FAQ ## FAQ
#### Why reimplement stack? ### Why reimplement stack?
GHCup is not a reimplementation of stack. The only common part is automatic installation of GHC, GHCup is not a reimplementation of stack. The only common part is automatic installation of GHC,
but even that differs in scope and design. but even that differs in scope and design.
#### Why should I use ghcup over stack? ### Why should I use ghcup over stack?
GHCup is not a replacement for stack. Instead, it supports installing and managing stack versions. GHCup is not a replacement for stack. Instead, it supports installing and managing stack versions.
It does the same for cabal, GHC and HLS. As such, It doesn't make a workflow choice for you. It does the same for cabal, GHC and HLS. As such, It doesn't make a workflow choice for you.
#### Why should I let ghcup manage stack? ### Why should I let ghcup manage stack?
You don't need to. However, some users seem to prefer to have a central tool that manages cabal and stack You don't need to. However, some users seem to prefer to have a central tool that manages cabal and stack
at the same time. Additionally, it can allow better sharing of GHC installation across these tools. at the same time. Additionally, it can allow better sharing of GHC installation across these tools.
@ -127,7 +127,7 @@ Also see:
* https://docs.haskellstack.org/en/stable/yaml_configuration/#system-ghc * https://docs.haskellstack.org/en/stable/yaml_configuration/#system-ghc
* https://github.com/commercialhaskell/stack/pull/5585 * https://github.com/commercialhaskell/stack/pull/5585
#### Why does ghcup not use stack code? ### Why does ghcup not use stack code?
Oddly, this question has been asked a couple of times. For the curious, here are a few reasons: Oddly, this question has been asked a couple of times. For the curious, here are a few reasons:
@ -138,14 +138,14 @@ Oddly, this question has been asked a couple of times. For the curious, here are
- it's not clear how GHCup would have been implemented with the provided API. It seems the codebases are fairly different. GHCup does a lot of symlink handling to expose a central `bin/` directory that users can easily put in PATH, without having to worry about anything more. It also provides explicit removal functionality, GHC cross-compilation, a TUI, etc etc. - it's not clear how GHCup would have been implemented with the provided API. It seems the codebases are fairly different. GHCup does a lot of symlink handling to expose a central `bin/` directory that users can easily put in PATH, without having to worry about anything more. It also provides explicit removal functionality, GHC cross-compilation, a TUI, etc etc.
3. GHCup is built around unix principles and supposed to be simple. 3. GHCup is built around unix principles and supposed to be simple.
#### Why not unify... ### Why not unify...
##### ...stack and Cabal and do away with standalone installers #### ...stack and Cabal and do away with standalone installers
GHCup is not involved in such decisions. cabal-install and stack might have a GHCup is not involved in such decisions. cabal-install and stack might have a
sufficiently different user experience to warrant having a choice. sufficiently different user experience to warrant having a choice.
##### ...installer implementations and have a common library #### ...installer implementations and have a common library
This sounds like an interesting goal. However, GHC installation isn't a hard engineering problem This sounds like an interesting goal. However, GHC installation isn't a hard engineering problem
and the shared code wouldn't be too exciting. For such an effort to make sense, all involved and the shared code wouldn't be too exciting. For such an effort to make sense, all involved
@ -158,7 +158,7 @@ can then call into ghcup or anything else, also see:
* https://github.com/haskell/cabal/issues/7394 * https://github.com/haskell/cabal/issues/7394
* https://github.com/commercialhaskell/stack/pull/5585 * https://github.com/commercialhaskell/stack/pull/5585
##### ...installers (like, all of it) #### ...installers (like, all of it)
So far, there hasn't been an **open** discussion about this. Is this even a good idea? So far, there hasn't been an **open** discussion about this. Is this even a good idea?
Sometimes projects converge eventually if their overlap is big enough, sometimes they don't. Sometimes projects converge eventually if their overlap is big enough, sometimes they don't.
@ -168,11 +168,11 @@ Take `curl` and `wget` as an example.
How bad do we need this? How bad do we need this?
#### Why not support windows? ### Why not support windows?
Windows is supported since GHCup version 0.1.15.1. Windows is supported since GHCup version 0.1.15.1.
#### Why the haskell reimplementation? ### Why the haskell reimplementation?
GHCup started as a portable posix shell script of maybe 50 LOC. GHC installation itself can be carried out in GHCup started as a portable posix shell script of maybe 50 LOC. GHC installation itself can be carried out in
about ~3 lines of shell code (download, unpack , configure+make install). However, much convenient functionality about ~3 lines of shell code (download, unpack , configure+make install). However, much convenient functionality
@ -183,7 +183,7 @@ The main concern when switching from a portable shell script to haskell was plat
However, ghcup now re-uses GHCs CI infrastructure and as such is perfectly in sync with all platforms that However, ghcup now re-uses GHCs CI infrastructure and as such is perfectly in sync with all platforms that
GHC supports. GHC supports.
#### Is GHCup affiliated with the Haskell Foundation? ### Is GHCup affiliated with the Haskell Foundation?
There has been some collaboration: Windows and Stack support were mainly requested by the Haskell Foundation There has been some collaboration: Windows and Stack support were mainly requested by the Haskell Foundation
and those seemed interesting features to add. and those seemed interesting features to add.

25
docs/css/extra.css
View File

@ -1,3 +1,28 @@
h2
{
border-bottom:1px solid #CCC;
padding-bottom:5px;
padding-top:15px;
}
h1 {
text-align: center;
font-size: 60px;
font-weight: 300;
padding-top:15px;
}
h3 {
font-size: 30px;
padding-top:10px;
}
h4 {
font-size: 25px;
padding-top:10px;
}
div.col-md-9 h1:first-of-type { div.col-md-9 h1:first-of-type {
text-align: center; text-align: center;
font-size: 60px; font-size: 60px;

12
docs/dev.md
View File

@ -4,15 +4,15 @@ All you wanted to know about development.
## Design decisions ## Design decisions
#### Using [Excepts](https://hackage.haskell.org/package/haskus-utils-variant-3.0/docs/Haskus-Utils-Variant-Excepts.html) as a beefed up ExceptT ### Using [Excepts](https://hackage.haskell.org/package/haskus-utils-variant-3.0/docs/Haskus-Utils-Variant-Excepts.html) as a beefed up ExceptT
This is an open variant, similar to [plucky](https://hackage.haskell.org/package/plucky) or [oops](https://github.com/i-am-tom/oops) and allows us to combine different error types. Maybe it is too much and it's a little bit [unergonomic](https://github.com/haskus/packages/issues/32) at times. If it really hurts maintenance, it will be removed. It was more of an experiment. This is an open variant, similar to [plucky](https://hackage.haskell.org/package/plucky) or [oops](https://github.com/i-am-tom/oops) and allows us to combine different error types. Maybe it is too much and it's a little bit [unergonomic](https://github.com/haskus/packages/issues/32) at times. If it really hurts maintenance, it will be removed. It was more of an experiment.
#### No use of haskell-TLS ### No use of haskell-TLS
I consider haskell-TLS an interesting experiment, but not a battle-tested and peer-reviewed crypto implementation. There is little to no research about what the intricacies of using haskell for low-level crypto are and how vulnerable such binaries are. Instead, we use either curl the binary (for FreeBSD and mac) or http-io-streams, which works with OpenSSL bindings. I consider haskell-TLS an interesting experiment, but not a battle-tested and peer-reviewed crypto implementation. There is little to no research about what the intricacies of using haskell for low-level crypto are and how vulnerable such binaries are. Instead, we use either curl the binary (for FreeBSD and mac) or http-io-streams, which works with OpenSSL bindings.
#### Optics instead of lens ### Optics instead of lens
They're a little safer (less Monoid weirdness with view) and have better error messages. Consider the following wit lens They're a little safer (less Monoid weirdness with view) and have better error messages. Consider the following wit lens
@ -32,7 +32,7 @@ vs optics
In an equation for ‘it’: it = view (_Just % to (++ "abc")) Nothing In an equation for ‘it’: it = view (_Just % to (++ "abc")) Nothing
``` ```
#### Strict and StrictData on by default ### Strict and StrictData on by default
Kazu Yamamoto [explained it in his PR](https://github.com/yesodweb/wai/pull/752#issuecomment-501531386) very well. I like to agree with him. The instances where we need non-strict behavior, we annotate it. Kazu Yamamoto [explained it in his PR](https://github.com/yesodweb/wai/pull/752#issuecomment-501531386) very well. I like to agree with him. The instances where we need non-strict behavior, we annotate it.
@ -42,7 +42,7 @@ Kazu Yamamoto [explained it in his PR](https://github.com/yesodweb/wai/pull/752#
2. mtl-style preferred 2. mtl-style preferred
3. no overly pointfree style 3. no overly pointfree style
#### Code structure ## Code structure
Main functionality is in `GHCup` module. Utility functions are Main functionality is in `GHCup` module. Utility functions are
organised tree-ish in `GHCup.Utils` and `GHCup.Utils.*`. organised tree-ish in `GHCup.Utils` and `GHCup.Utils.*`.
@ -55,7 +55,7 @@ yaml files: `ghcup-<yaml-ver>.yaml`.
## Common Tasks ## Common Tasks
#### Adding a new GHC version ### Adding a new GHC version
1. open the latest `ghcup-<yaml-ver>.yaml` 1. open the latest `ghcup-<yaml-ver>.yaml`
2. find the latest ghc version (in yaml tree e.g. `ghcupDownloads -> GHC -> 8.10.3`) 2. find the latest ghc version (in yaml tree e.g. `ghcupDownloads -> GHC -> 8.10.3`)

9
docs/guide.md
View File

@ -176,9 +176,9 @@ Examples:
5. you can even compile ghc to an isolated location. 5. you can even compile ghc to an isolated location.
- `ghcup compile ghc -j 4 -v 9.0.1 -b 8.10.5 -i /home/username/my/dir/ghc` - `ghcup compile ghc -j 4 -v 9.0.1 -b 8.10.5 -i /home/username/my/dir/ghc`
## CI ## Continuous integration
On windows, ghcup can be installed automatically on a CI runner like so: On windows, ghcup can be installed automatically on a CI runner non-interactively like so:
```ps ```ps
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 $false,$true,$true,$false,$false,$false,$false,"C:\" 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 $false,$true,$true,$false,$false,$false,$false,"C:\"
@ -192,6 +192,11 @@ curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | BOOTSTRAP_H
This will just install `ghcup` and on windows additionally `msys2`. This will just install `ghcup` and on windows additionally `msys2`.
For the full list of env variables and parameters to tweak the script behavior, see:
* [bootstrap-haskell for linux/darwin/freebsd](https://gitlab.haskell.org/haskell/ghcup-hs/-/blob/master/scripts/bootstrap/bootstrap-haskell#L7)
* [bootstrap-haskell.ps1 for windows](https://gitlab.haskell.org/haskell/ghcup-hs/-/blob/master/scripts/bootstrap/bootstrap-haskell.ps1#L17)
### Example github workflow ### Example github workflow
On github workflows you can use https://github.com/haskell/actions/ On github workflows you can use https://github.com/haskell/actions/

26
docs/install.md
View File

@ -4,23 +4,27 @@ Let's get started....
## Installation ## Installation
On Linux, macOS, FreeBSD or Windows Subsystem 2 for Linux, run the following in your terminal (as a user other than root), then follow the onscreen instructions: 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:
```sh ```sh
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
``` ```
If you are running Windows, run the following in a powershell session (as a non-admin user). For Windows, run this in a PowerShell session:
```psh ```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 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
``` ```
Advanced users may want to perform a [manual installation](#manual-install). Advanced users may want to perform a [manual installation](#manual-install) and GPG verify the binaries.
## Supported tools ## Supported tools
GHCup supports the following tools: GHCup supports the following tools, which are also known as the **Haskell Toolchain**:
1. [GHC](https://www.haskell.org/ghc/) 1. [GHC](https://www.haskell.org/ghc/)
2. [cabal-install](https://cabal.readthedocs.io/en/latest/) 2. [cabal-install](https://cabal.readthedocs.io/en/latest/)
@ -49,32 +53,32 @@ This list may not be exhaustive and specifies support for bindists only.
| Linux generic | aarch64 | ✅ | ⚠️ | ✅ | ⚠️ | ❌ | | Linux generic | aarch64 | ✅ | ⚠️ | ✅ | ⚠️ | ❌ |
| Linux generic | armv7 | ✅ | ⚠️ | ✅ | ⚠️ | ❌ | | Linux generic | armv7 | ✅ | ⚠️ | ✅ | ⚠️ | ❌ |
#### Windows 7 ### Windows 7
May or may not work, several issues: May or may not work, several issues:
* 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
#### WSL1 ### WSL1
Unsupported. GHC may or may not work. Upgrade to WSL2. Unsupported. GHC may or may not work. Upgrade to WSL2.
#### MacOS <13 ### MacOS <13
Not supported. Would require separate binaries, since >=13 binaries are incompatible. Not supported. Would require separate binaries, since >=13 binaries are incompatible.
Please upgrade. Please upgrade.
#### MacOS aarch64 ### MacOS aarch64
HLS bindists are still experimental. Stack is theoretically supported, but has no binaries yet. HLS bindists are still experimental. Stack is theoretically supported, but has no binaries yet.
#### FreeBSD ### FreeBSD
Lacks some upstream bindists and may need compat libs, since most bindists are built on FreeBSD-12. Lacks some upstream bindists and may need compat libs, since most bindists are built on FreeBSD-12.
HLS bindists are experimental. HLS bindists are experimental.
#### Linux ARMv7/AARCH64 ### Linux ARMv7/AARCH64
Lower availability of bindists. HLS only has experimental ones. Stack not supported currently. Lower availability of bindists. HLS only has experimental ones. Stack not supported currently.
@ -83,6 +87,8 @@ Lower availability of bindists. HLS only has experimental ones. Stack not suppor
Download the binary for your platform at [https://downloads.haskell.org/~ghcup/](https://downloads.haskell.org/~ghcup/) Download the binary for your platform at [https://downloads.haskell.org/~ghcup/](https://downloads.haskell.org/~ghcup/)
and place it into your `PATH` anywhere. and place it into your `PATH` anywhere.
If you want to GPG verify the binaries, import the following key first: `7784930957807690A66EBDBE3786C5262ECB4A3F`.
Then adjust your `PATH` in `~/.bashrc` (or similar, depending on your shell) like so: Then adjust your `PATH` in `~/.bashrc` (or similar, depending on your shell) like so:
```sh ```sh