From e2f36611a1c0c45d0147ebd55b3a701973f56e22 Mon Sep 17 00:00:00 2001 From: Julian Ospald Date: Mon, 4 Oct 2021 21:40:48 +0200 Subject: [PATCH] Tweak appearance --- docs/about.md | 38 +++++++++++++++++++------------------- docs/css/extra.css | 25 +++++++++++++++++++++++++ docs/dev.md | 12 ++++++------ docs/guide.md | 9 +++++++-- docs/install.md | 26 ++++++++++++++++---------- 5 files changed, 73 insertions(+), 37 deletions(-) diff --git a/docs/about.md b/docs/about.md index c5ee75c..6a2b82d 100644 --- a/docs/about.md +++ b/docs/about.md @@ -40,7 +40,7 @@ cabal-install/HLS/stack are installed in `~/.ghcup/bin/-` and have un ## Known problems -#### Custom ghc version names +### Custom ghc version names When installing ghc bindists with custom version names as outlined in [installing custom bindists](#installing-custom-bindists), then cabal might @@ -51,16 +51,16 @@ as the current one via: `ghcup set ghc `. 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. -#### Precompiled binaries +### Precompiled binaries Since this uses precompiled binaries you may run into several problems. -##### Missing libtinfo (ncurses) +#### 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 @@ -69,13 +69,13 @@ 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 `. -##### 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 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 +### 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 @@ -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) 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, such as: @@ -95,7 +95,7 @@ issues discussed here: - 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, 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 -#### Why reimplement stack? +### 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. -#### 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. 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 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://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: @@ -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. 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 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 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/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? 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? -#### Why not support windows? +### Why not support windows? 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 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 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 and those seemed interesting features to add. diff --git a/docs/css/extra.css b/docs/css/extra.css index 9876f66..fab049d 100644 --- a/docs/css/extra.css +++ b/docs/css/extra.css @@ -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 { text-align: center; font-size: 60px; diff --git a/docs/dev.md b/docs/dev.md index 1a04211..feac445 100644 --- a/docs/dev.md +++ b/docs/dev.md @@ -4,15 +4,15 @@ All you wanted to know about development. ## 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. -#### 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. -#### 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 @@ -32,7 +32,7 @@ vs optics 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. @@ -42,7 +42,7 @@ Kazu Yamamoto [explained it in his PR](https://github.com/yesodweb/wai/pull/752# 2. mtl-style preferred 3. no overly pointfree style -#### Code structure +## Code structure Main functionality is in `GHCup` module. Utility functions are organised tree-ish in `GHCup.Utils` and `GHCup.Utils.*`. @@ -55,7 +55,7 @@ yaml files: `ghcup-.yaml`. ## Common Tasks -#### Adding a new GHC version +### Adding a new GHC version 1. open the latest `ghcup-.yaml` 2. find the latest ghc version (in yaml tree e.g. `ghcupDownloads -> GHC -> 8.10.3`) diff --git a/docs/guide.md b/docs/guide.md index 5a07093..98e07d2 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -176,9 +176,9 @@ Examples: 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` -## 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 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`. +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 On github workflows you can use https://github.com/haskell/actions/ diff --git a/docs/install.md b/docs/install.md index 6be587a..517e31e 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,23 +4,27 @@ Let's get started.... ## 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 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 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 -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/) 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 | armv7 | ✅ | ⚠️ | ✅ | ⚠️ | ❌ | -#### Windows 7 +### Windows 7 May or may not work, several issues: * https://gitlab.haskell.org/haskell/ghcup-hs/-/issues/140 * https://gitlab.haskell.org/haskell/ghcup-hs/-/issues/197 -#### WSL1 +### WSL1 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. Please upgrade. -#### MacOS aarch64 +### MacOS aarch64 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. HLS bindists are experimental. -#### Linux ARMv7/AARCH64 +### Linux ARMv7/AARCH64 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/) 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: ```sh