GHCup

https://www.haskell.org/ghcup/
Admin
GHCup is the main installer for the Haskell programming language, providing easy installation and...
Tokens:19,374
Snippets:266
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Executable and Data Rules Example

Source: https://www.haskell.org/ghcup/packaging/new_tools

Demonstrates how to specify individual executables and data files for installation, including their source and destination paths.

```yaml
exeRules:
  - installSource: "dhall"
    installDest: "bin/dhall"
  - installSource: "dhall-to-json"
    installDest: "bin/dhall-to-json"
dataRules:
  - installSource: "dhall.1"
    installDest: "share/man1/dhall.1"

```

--------------------------------

### Setup WASM Toolchain

Source: https://www.haskell.org/ghcup/guide/cross

Clone the ghc-wasm-meta repository, set the SKIP_GHC environment variable, run the setup script, and source the environment variables. This prepares the system for WASM cross bindist installation.

```bash
git clone https://gitlab.haskell.org/ghc/ghc-wasm-meta.git
cd ghc-wasm-meta/
export SKIP_GHC=yes
./setup.sh
source ~/.ghc-wasm/env

```

--------------------------------

### Dhall Tool Installation Specification

Source: https://www.haskell.org/ghcup/packaging/new_tools

Example of an install specification for the 'dhall' tool, including download URIs, hashes, and installation rules for different operating systems.

```yaml
ghcupDownloads:
  dhall:
    1.42.2:
      viTags:
        - Latest
        - Recommended
      viArch:
        A_64:
          Linux_UnknownLinux:
            unknown_versioning:
              dlUri: https://github.com/dhall-lang/dhall-haskell/releases/download/1.42.2/dhall-1.42.2-x86_64-linux.tar.bz2
              dlHash: b2509bbe07772f268ef193d9c36b18aa13bd32ecec76fd4b21782715b38386a3
              dlInstallSpec: &dhall-install-spec1
                exeRules:
                  - installSource: "bin/dhall"
                exeSymLinked:
                 - linkName: "dhall-${PKGVER}"
                   pVPMajorLinks: true
                   setName: "dhall"
                   target: "bin/dhall"
          Darwin:
            unknown_versioning:
              dlUri: https://github.com/dhall-lang/dhall-haskell/releases/download/1.42.2/dhall-1.42.2-x86_64-darwin.tar.bz2
              dlHash: b1c5fd87b018d13d3a07db0561d1ffb906b7b840151fdb8ce00dc9f2f8dffe4a
              dlInstallSpec: *dhall-install-spec1
          Windows:
            unknown_versioning:
              dlUri: https://github.com/dhall-lang/dhall-haskell/releases/download/1.42.2/dhall-1.42.2-x86_64-windows.zip
              dlHash: c2447b8406d11611f43c47366fc93baa8061961736b46b9822077625cbd8ff9e
              dlInstallSpec: &dhall-install-win-spec1
                exeRules:
                  - installSource: "bin/dhall.exe"
                exeSymLinked:
                 - linkName: "dhall-${PKGVER}.exe"
                   pVPMajorLinks: true
                   setName: "dhall.exe"
                   target: "bin/dhall.exe"

```

--------------------------------

### Install GHCup on Linux, macOS, FreeBSD, or WSL2

Source: https://www.haskell.org/ghcup/install

Run this command in a terminal to download and execute the GHCup installation script. It installs ghcup into ~/.ghcup/bin.

```shell
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh

```

--------------------------------

### Install Recommended GHC Version

Source: https://www.haskell.org/ghcup/guide

Installs the GHC version recommended by the GHCup project.

```bash
ghcup install ghc

```

--------------------------------

### Install Cabal-Install

Source: https://www.haskell.org/ghcup/guide

Installs the cabal-install tool, used for building Haskell projects.

```bash
ghcup install cabal

```

--------------------------------

### Configure GHCup to Use Stack Setup Metadata

Source: https://www.haskell.org/ghcup/guide/stack

Permanently configure GHCup to use both GHCup's and Stack's setup-info metadata for installing GHC. This ensures GHCup can find GHC versions from both sources.

```yaml
url-source:
  - GHCupURL
  # stack versions take precedence
  # you'll still have access to GHCup provided versions and tools in case they don't exist in stack metadata
  - StackSetupURL
```

--------------------------------

### Install GHC, Cabal, Stack, and HLS on Windows

Source: https://www.haskell.org/ghcup/install/manual

Install recommended GHC, latest Cabal, Stack, and HLS using ghcup commands in PowerShell.

```powershell
ghcup install ghc --set recommended
```

```powershell
ghcup install cabal latest
```

```powershell
ghcup install stack latest
```

```powershell
ghcup install hls latest
```

```powershell
cabal update
```

--------------------------------

### Install GHC with a Custom Bindist (Local File)

Source: https://www.haskell.org/ghcup/guide/advanced_install

Use this command to install a GHC version from a locally built bindist file. The version string is appended to the tool name.

```bash
ghcup install ghc -u 'file:///home/mearwald/tmp/ghc-eff-patches/ghc-8.10.2-x86_64-deb10-linux.tar.xz' 8.10.2-eff
```

--------------------------------

### Install GHC with a Custom Bindist (DWARF)

Source: https://www.haskell.org/ghcup/guide/advanced_install

Install a GHC version with DWARF debugging symbols from a specified URL. The version string is appended to the tool name.

```bash
ghcup install ghc -u 'https://downloads.haskell.org/~ghc/8.10.2/ghc-8.10.2-x86_64-deb10-linux-dwarf.tar.xz' 8.10.2-dwarf
```

--------------------------------

### Data Rules with Wildcard Pattern

Source: https://www.haskell.org/ghcup/packaging/new_tools

Example of using wildcard patterns in dataRules to install multiple files from a directory.

```yaml
dataRules:
  - installPattern: ["data/**"]

```

--------------------------------

### Start GHCi Interactive Environment

Source: https://www.haskell.org/ghcup/steps

Launch the GHCi interactive Read-Evaluate-Print Loop (REPL).

```bash
➜ ghci
GHCi, version 9.0.2: https://www.haskell.org/ghc/  :? for help
ghci>

```

--------------------------------

### Configure Make Arguments

Source: https://www.haskell.org/ghcup/packaging/new_tools

Sets arguments for the `make` command, including `DESTDIR` for temporary installation and `PREFIX` for the installation path.

```yaml
make:
  makeArgs:
    - DESTDIR=${TMPDIR}
    - PREFIX=${PREFIX}
    - install

```

--------------------------------

### Install GHCup on Linux/macOS/FreeBSD/WSL2

Source: https://www.haskell.org/ghcup

Run this command in a terminal as a non-root user to install GHCup on Unix-like systems.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
```

--------------------------------

### Install GHCup on Windows using PowerShell

Source: https://www.haskell.org/ghcup/install

Execute this PowerShell command to install GHCup on Windows. It sets the security protocol and runs the bootstrap script interactively.

```powershell
Set-ExecutionPolicy Bypass -Scope Process -Force;[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; try { & ([ScriptBlock]::Create((Invoke-WebRequest https://www.haskell.org/ghcup/sh/bootstrap-haskell.ps1 -UseBasicParsing))) -Interactive -DisableCurl } catch { Write-Error $_ }

```

--------------------------------

### Check GHC Installation

Source: https://www.haskell.org/ghcup/steps

Verify that the Haskell toolchain is installed by checking the GHC version.

```bash
➜ ghc --version
The Glorious Glasgow Haskell Compilation System, version 8.10.7

```

--------------------------------

### Install GHCup on Windows

Source: https://www.haskell.org/ghcup

Execute this PowerShell command as a non-admin user to install GHCup on Windows.

```powershell
Set-ExecutionPolicy Bypass -Scope Process -Force;[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; try { & ([ScriptBlock]::Create((Invoke-WebRequest https://www.haskell.org/ghcup/sh/bootstrap-haskell.ps1 -UseBasicParsing))) -Interactive -DisableCurl } catch { Write-Error $_ }
```

--------------------------------

### List Available GHC/Cabal Versions

Source: https://www.haskell.org/ghcup/guide

Lists all available GHC and Cabal-install versions that can be installed.

```bash
ghcup list

```

--------------------------------

### Install Emscripten Toolchain for GHC JS

Source: https://www.haskell.org/ghcup/guide/cross

Clone the emsdk repository, install a specific version of emscripten, activate it, and set up the environment variables. This is a prerequisite for installing GHC JS cross bindists.

```bash
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install VERSION
./emsdk activate VERSION
source ./emsdk_env.sh

```

--------------------------------

### Use External Packages with cabal-install in GHCi

Source: https://www.haskell.org/ghcup/steps

Start a GHCi session with external packages 'async' and 'say' available for use.

```bash
cabal repl --build-depends async,say

```

--------------------------------

### Use External Packages with Stack in GHCi

Source: https://www.haskell.org/ghcup/steps

Start a GHCi session with external packages 'async' and 'say' available for use using Stack.

```bash
stack exec --package async --package say -- ghci

```

--------------------------------

### Perform Isolated GHC Installation

Source: https://www.haskell.org/ghcup/guide/advanced_install

Install a specific GHC version to an isolated directory. This prevents conflicts with main installations and requires manual management.

```bash
ghcup install ghc 8.10.5 --isolate /home/user/isolated_dir/ghc
```

--------------------------------

### Execute Command with Specific GHC Toolchain

Source: https://www.haskell.org/ghcup/guide

Use 'ghcup run' to execute a command, such as 'code Setup.hs', with a specific GHC version (8.10.7) and the latest versions of other tools like Cabal, HLS, and Stack. The '--install' flag ensures that if any of the specified tools are not installed, they will be installed first.

```bash
ghcup run --ghc 8.10.7 --cabal latest --hls latest --stack latest --install -- code Setup.hs

```

--------------------------------

### Install Specific GHC Version with GHCup and Stack Metadata

Source: https://www.haskell.org/ghcup/guide/stack

Use GHCup to install a specific GHC version (e.g., 9.4.7) by leveraging Stack's setup-info metadata. This command allows GHCup to find and install GHC versions defined in Stack's metadata.

```shell
# ghcup will only see GHC now
ghcup -s StackSetupURL install ghc 9.4.7
# this combines both ghcup and stack metadata
ghcup -s '["GHCupURL", "StackSetupURL"]' install ghc 9.4.7
```

--------------------------------

### Install GHC with a Custom Bindist (CI Artifact)

Source: https://www.haskell.org/ghcup/guide/advanced_install

Install GHC from a CI artifact by specifying the job URL and a version identifier. This is useful for testing specific branches or job outputs.

```bash
ghcup install ghc -u 'https://gitlab.haskell.org/ghc/ghc/-/jobs/artifacts/master/raw/ghc-x86_64-linux-fedora33-release.tar.xz?job=x86_64-linux-fedora33-release' head
```

```bash
ghcup install ghc -u ' https://gitlab.haskell.org/api/v4/projects/1/jobs/1129565/artifacts/ghc-x86_64-linux-alpine3_12-validate+fully_static.tar.xz' mr7847
```

--------------------------------

### Perform Isolated HLS Installation

Source: https://www.haskell.org/ghcup/guide/advanced_install

Install the Haskell Language Server (HLS) to a specified isolated directory. This installation will not interfere with other GHCup managed tools.

```bash
ghcup install hls --isolate /home/username/dir/hls/
```

--------------------------------

### Add New CLI Command Example Link

Source: https://www.haskell.org/ghcup/dev

Link to a GitHub commit illustrating how to add a new CLI command using optparse-applicative in GHCup.

```markdown
https://github.com/haskell/ghcup-hs/commit/c19dd5ee8b2edbaf0336af143f1c75b6f4843e26
```

--------------------------------

### Perform Isolated Cabal Installation

Source: https://www.haskell.org/ghcup/guide/advanced_install

Install Cabal to a custom, isolated location. This installation is separate from your main GHCup installations.

```bash
ghcup install cabal --isolate /home/username/my_isolated_dir/
```

--------------------------------

### Install Specific GHC Version

Source: https://www.haskell.org/ghcup/guide

Installs a specific version of GHC. Ensure the version number is accurate.

```bash
ghcup install ghc 8.2.2

```

--------------------------------

### Perform Isolated GHC Installation with Custom Bindist

Source: https://www.haskell.org/ghcup/guide/advanced_install

Install GHC to an isolated location using a custom bindist URL. The version string 'head' is used here, corresponding to the artifact.

```bash
ghcup install ghc --isolate /home/username/my_isolated_dir/ -u 'https://gitlab.haskell.org/ghc/ghc/-/jobs/artifacts/master/raw/ghc-x86_64-linux-fedora33-release.tar.xz?job=x86_64-linux-fedora33-release' head
```

--------------------------------

### Build and Run Hello World with GHC JS

Source: https://www.haskell.org/ghcup/guide/cross

Compile a simple Haskell 'hello world' program using the installed GHC JS compiler and then execute the compiled output.

```bash
echo 'main = putStrLn "hello world"' > hello.hs
javascript-unknown-ghcjs-ghc -fforce-recomp hello.hs
./hello

```

--------------------------------

### Non-interactive ghcup Installation on Linux/macOS/FreeBSD

Source: https://www.haskell.org/ghcup/guide

Install ghcup non-interactively on Linux, macOS, or FreeBSD CI runners using curl. This command downloads and executes the bootstrap script with environment variables set for non-interactive and minimal installation.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | BOOTSTRAP_HASKELL_NONINTERACTIVE=1 BOOTSTRAP_HASKELL_MINIMAL=1 sh

```

--------------------------------

### Install GHC JS Cross Bindist

Source: https://www.haskell.org/ghcup/guide/cross

Install a GHC JS cross bindist using ghcup, specifying the target compiler version. This command requires the emscripten toolchain to be set up.

```bash
emconfigure ghcup install ghc --set javascript-unknown-ghcjs-9.12.2

```

--------------------------------

### GHCup Tool and Version Information

Source: https://www.haskell.org/ghcup

This table displays available tools managed by GHCup, their GHC versions, and associated tags. Use 'i' to install recommended versions or 'a' to show all versions.

```text
┌─────────────┬─────────────────────────────GHCup──────────────────────────────────────────┐│ Tool        │ GHC versions                                Tags                           │├─────────────┼────────────────────────────────────────────────────────────────────────────┤│ agda        │ ✗  wasm32-wasi-9.12.2.20250327              base-4.21.0.0,TH-support       ││ cabal       │ ✗  wasm32-wasi-9.10.1.20250327              base-4.20.0.0                  ││ dhall       │ ✗  wasm32-wasi-9.10.1.20241021              base-4.20.0.0,TH-support       ││ GHC         │ ✗  wasm32-wasi-9.10.1                       base-4.20.0.0                  ││ GHCup       │ ✗  wasm32-wasi-9.10.0.20240412              base-4.20.0.0                  ││ hlint       │ ✗  wasm32-wasi-9.10.0.20240313              base-4.20.0.0                  ││ HLS         │ ✗  wasm32-wasi-9.8.1                        base-4.19.0.0                  ││ ormolu      │ ✗  wasm32-wasi-9.8.0.20230927               base-4.19.0.0                  ││ pandoc      │ ✗  wasm32-wasi-9.6.7.20250206               base-4.18.3.0                  ││ purescript  │ ✗  wasm32-wasi-9.6.4                        base-4.18.2.0                  ││ shellcheck  │ ✗  wasm32-wasi-9.6.3.20230927               base-4.18.1.0                  ││ Stack       │ ✗  javascript-unknown-ghcjs-9.12.2          base-4.21.0.0                  ││             │ ✗  javascript-unknown-ghcjs-9.12.1          base-4.21.0.0                  ││             │ ✗  javascript-unknown-ghcjs-9.10.2          base-4.20.1.0                  ││             │ ✗  javascript-unknown-ghcjs-9.10.0.20240413 base-4.20.0.0                  ││             │ ✗  javascript-unknown-ghcjs-9.6.7           base-4.18.3.0                  ││             │ ✗  javascript-unknown-ghcjs-9.6.2           base-4.18.0.0                  ││             │ ✓  9.14.1                                   latest,base-4.22.0.0           ││             │ ✓  9.12.4                                   base-4.21.2.0                  ││             │ ✗  9.12.3.20260311                          latest-prerelease,base-4.21.2.0│└─────────────┴────────────────────────────────────────────────────────────────────────────┘q:Quit  i:Install and set recommended version  a:Show all versions  h:help  Enter:Show tool details
```

--------------------------------

### Dhall Install Specification for Windows

Source: https://www.haskell.org/ghcup/packaging/new_tools

Specific install specification for the Windows binary of the 'dhall' tool, detailing executable rules and symlinking.

```yaml
dlInstallSpec: &dhall-install-win-spec1
  exeRules:
    - installSource: "bin/dhall.exe"
  exeSymLinked:
   - linkName: "dhall-${PKGVER}.exe"
     pVPMajorLinks: true
     setName: "dhall.exe"
     target: "bin/dhall.exe"

```

--------------------------------

### Build and Run Hello World with GHC WASM

Source: https://www.haskell.org/ghcup/guide/cross

Compile a simple Haskell 'hello world' program using the installed GHC WASM compiler and then execute the compiled WebAssembly binary using wasmtime.

```bash
echo 'main = putStrLn "hello world"' > hello.hs
wasm32-wasi-ghc hello.hs -o hello.wasm
wasmtime ./hello.wasm

```

--------------------------------

### Configure Mirrors for ghcup

Source: https://www.haskell.org/ghcup/guide

Define mirror configurations in ~/.ghcup/config.yaml to specify alternative download locations for metadata and bindists. This example shows how to configure mirrors for raw.githubusercontent.com, github.com, and downloads.haskell.org.

```yaml
mirrors:
  # yaml download location, would result in:
  #      https://raw.githubusercontent.com/haskell/ghcup-metadata/develop/ghcup-0.0.9.yaml
  #   -> https://mirror.sjtu.edu.cn/ghcup/yaml/haskell/ghcup-metadata/master/ghcup-0.0.9.yaml
  "raw.githubusercontent.com":
    authority:
      host: "mirror.sjtu.edu.cn"
    pathPrefix: "ghcup/yaml"
  # for stack and some older HLS versions, would result in e.g.
  #      https://github.com/haskell/haskell-language-server/releases/download/1.2.0/haskell-language-server-Windows-1.2.0.tar.gz
  #   -> https://mirror.sjtu.edu.cn/ghcup/github/haskell/haskell-language-server/releases/download/1.2.0/haskell-language-server-Windows-1.2.0.tar.gz
  "github.com":
    authority:
      host: "mirror.sjtu.edu.cn"
    pathPrefix: "ghcup/github"
  # for all haskell.org hosted bindists, would result in e.g.
  #      https://downloads.haskell.org/~ghc/9.8.1/ghc-9.8.1-x86_64-deb10-linux.tar.xz
  #   -> https://mirror.sjtu.edu.cn/ghcup/haskell-downloads/~ghc/9.8.1/ghc-9.8.1-x86_64-deb10-linux.tar.xz
  "downloads.haskell.org":
    authority:
      host: "mirror.sjtu.edu.cn"
    pathPrefix: "downloads.haskell.org"

```

--------------------------------

### Dhall Install Specification for Linux/macOS

Source: https://www.haskell.org/ghcup/packaging/new_tools

Specific install specification for the Linux and macOS binaries of the 'dhall' tool, detailing executable rules and symlinking.

```yaml
dlInstallSpec: &dhall-install-spec1
  exeRules:
    - installSource: "bin/dhall"
  exeSymLinked:
   - linkName: "dhall-${PKGVER}"
     pVPMajorLinks: true
     setName: "dhall"
     target: "bin/dhall"

```

--------------------------------

### Use a new module interactively

Source: https://www.haskell.org/ghcup/steps

Start the Haskell interpreter (`cabal repl`) and import your new module to use its functions. This allows for interactive testing and development.

```bash
➜ cabal repl
ghci> import OtherLib
ghci> otherFunc "Hello Haskell"
```

--------------------------------

### Install GHC WASM Cross Bindist

Source: https://www.haskell.org/ghcup/guide/cross

Install a GHC WASM cross bindist using ghcup, specifying the target compiler and host architecture. This command requires the WASM toolchain to be set up.

```bash
ghcup install ghc --set wasm32-wasi-9.6.3.20230927 -- --host=x86_64-linux --with-intree-gmp --with-system-libffi

```

--------------------------------

### Compile HLS using Git Describe for Version

Source: https://www.haskell.org/ghcup/guide/compiling

Use 'git describe' to automatically set the HLS version when building from git sources. This helps avoid overwriting existing installations.

```bash
ghcup compile hls --git-ref master --ghc 9.2.3 --git-describe-version
```

--------------------------------

### Non-interactive ghcup Installation on Windows

Source: https://www.haskell.org/ghcup/guide

Install ghcup non-interactively on Windows CI runners using PowerShell. This script sets error handling, bypasses execution policy, updates security protocols, and then downloads and runs the bootstrap script with minimal options.

```powershell
$ErrorActionPreference = 'Stop';Set-ExecutionPolicy Bypass -Scope Process -Force;[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;try { & ([ScriptBlock]::Create((Invoke-WebRequest https://www.haskell.org/ghcup/sh/bootstrap-haskell.ps1 -UseBasicParsing))) -Minimal -InBash -InstallDir "C:\" } catch { Write-Error $_ }
```

--------------------------------

### List GHC Versions with Revisions

Source: https://www.haskell.org/ghcup/guide

Shows available GHC versions, including revisions. The '✗' indicates an outdated revision, and '✓' indicates the currently installed or latest revision.

```bash
✗  9.6.7-r1                                 latest
✓  9.6.7-r0                                       

```

--------------------------------

### Add Cross Release Channel

Source: https://www.haskell.org/ghcup/guide/cross

Add the 'cross' release channel to ghcup configuration to enable installation of cross-compilation bindists.

```bash
ghcup config add-release-channel cross

```

--------------------------------

### Configure Stack to Use GHCup's MSYS2 on Windows

Source: https://www.haskell.org/ghcup/guide/stack

Configure Stack's `config.yaml` to use GHCup's MSYS2 installation instead of Stack's default. This involves setting `skip-msys` and providing paths to GHCup's MSYS2 libraries, binaries, and include directories.

```yaml
skip-msys: true
extra-lib-dirs:
- C:\ghcup\msys64\mingw64\lib
- C:\ghcup\msys64\mingw64\bin
extra-path:
- C:\ghcup\msys64\mingw64\bin
- C:\ghcup\msys64\usr\bin
- C:\ghcup\msys64\usr\local\bin
extra-include-dirs:
- C:\ghcup\msys64\mingw64\include
```

--------------------------------

### Define a new module

Source: https://www.haskell.org/ghcup/steps

Create a new Haskell file (e.g., `src/OtherLib.hs`) to define your new module and its functions. This example defines `otherFunc` which calculates the length of a string.

```haskell
module OtherLib where

otherFunc :: String -> Int
otherFunc str = length str
```

--------------------------------

### Lens Example: Viewing a modified Nothing value

Source: https://www.haskell.org/ghcup/dev

Demonstrates the behavior of the 'lens' library when attempting to view a modified Nothing value, resulting in an empty string.

```haskell
> view (_Just . to (++ "abc")) Nothing
""
```

--------------------------------

### Compile HLS with Explicit Overwrite Version

Source: https://www.haskell.org/ghcup/guide/compiling

Explicitly set the HLS version to be installed, overriding any auto-detected version. Useful for specific release tagging.

```bash
ghcup compile hls --git-ref master --ghc 9.2.3 --overwrite-version 1.7.0.0-p1
```

--------------------------------

### Update MSYS2 packages on Windows

Source: https://www.haskell.org/ghcup/install/manual

Update MSYS2 system packages and install necessary tools like curl, autoconf, pkgconf, and ca-certificates using pacman.

```bash
ghcup run -m -- pacman --noconfirm -Syuu
```

```bash
ghcup run -m -- pacman --noconfirm -Syuu
```

```bash
ghcup run -m -- pacman --noconfirm -S --needed curl autoconf mingw-w64-x86_64-pkgconf
```

```bash
ghcup run -m -- pacman --noconfirm -S ca-certificates
```

--------------------------------

### Configure Configure and Make

Source: https://www.haskell.org/ghcup/packaging/new_tools

Sets up arguments for both `configure` and `make` steps. `configFile` is optional for configure.

```yaml
configure:
  configFile: configure
  configArgs:
    - --prefix=${PREFIX}
make:
  makeArgs:
    - DESTDIR=${TMPDIR}
    - install

```

--------------------------------

### GHCup Certificate Trust Error Example

Source: https://www.haskell.org/ghcup/guide/trouble

This error message indicates that GHCup cannot trust the certificate for downloads.haskell.org, likely due to an unknown or untrusted issuer.

```text
ERROR: The certificate of ‘downloads.haskell.org’ is not trusted.
ERROR: The certificate of ‘downloads.haskell.org’ doesn't have a known issuer.

```

--------------------------------

### Optics Example: Viewing a modified Nothing value

Source: https://www.haskell.org/ghcup/dev

Illustrates the error message produced by the 'optics' library when attempting to view a modified Nothing value, highlighting type mismatches.

```haskell
> view (_Just % to (++ "abc")) Nothing

<interactive>:2:1: error:
    • An_AffineFold cannot be used as A_Getter
    • In the expression: view (_Just % to (++ "abc")) Nothing
      In an equation for ‘it’: it = view (_Just % to (++ "abc")) Nothing
```

--------------------------------

### Customize GHC Bindist in GHCup Config

Source: https://www.haskell.org/ghcup/guide/stack

Customize or add specific GHC bindist information within the GHCup configuration. This example shows how to override the URL and checksum for a specific GHC version on Linux.

```yaml
url-source:
  - GHCupURL
  - StackSetupURL
  - setup-info:
      ghc:
        linux64-tinfo6:
          9.4.7:
            url: "https://downloads.haskell.org/~ghc/9.4.7/ghc-9.4.7-x86_64-fedora27-linux.tar.xz"
            content-length: 179117892
            sha256: 216b76b7c6383e6ad9ba82533f323f8550e52893a8b9fa33c7b9dc4201ac766a
```

--------------------------------

### Create a Haskell Program

Source: https://www.haskell.org/ghcup/steps

Write a simple 'Hello, Haskell!' program in a file named hello.hs.

```haskell
main = putStrLn "Hello, Haskell!"

```

--------------------------------

### Set up MSYS2 shell environment on Windows

Source: https://www.haskell.org/ghcup/install/manual

Configure MSYS2 shell to match Windows home directory and inherit the system PATH.

```bash
ghcup run -m -- sed -i -e 's/db_home:.*$/db_home: windows/' /etc/nsswitch.conf
```

```bash
ghcup run -m -- sed -i -e 's/#MSYS2_PATH_TYPE=.*/MSYS2_PATH_TYPE=inherit/' /c/msys64/msys2.ini
```

```bash
ghcup run -m -- sed -i -e 's/rem set MSYS2_PATH_TYPE=inherit/set MSYS2_PATH_TYPE=inherit/' /c/msys64/msys2_shell.cmd
```

--------------------------------

### Initialize a new Haskell project

Source: https://www.haskell.org/ghcup/steps

Use `cabal init --interactive` to create a new Haskell project structure with sensible defaults. This command sets up the necessary files and directories for a cabal project.

```bash
mkdir haskell-project
cd haskell-project
cabal init --interactive
```

--------------------------------

### Build GHCup with Stack

Source: https://www.haskell.org/ghcup/dev

Use this command to build the GHCup project when using the Stack build tool.

```bash
stack build
```

--------------------------------

### Disable Stack's GHC Installation

Source: https://www.haskell.org/ghcup/guide/stack

Configure Stack globally to not install GHC versions itself. This is useful when Stack is configured to use an external GHC manager like GHCup.

```shell
stack config set install-ghc false --global
```

--------------------------------

### Compile a Haskell Program with GHC

Source: https://www.haskell.org/ghcup/steps

Compile the hello.hs file into an executable using the ghc command.

```bash
➜ ghc hello.hs
[1 of 1] Compiling Main             ( hello.hs, hello.o )
Linking hello ...

```

--------------------------------

### Curl SSL Certificate Problem Example

Source: https://www.haskell.org/ghcup/guide/trouble

This is an example error message indicating an SSL certificate problem when using curl, often due to outdated or improperly configured CA certificates.

```text
curl: (60) SSL certificate problem: unable to get local issuer certificate
More details here: https://curl.se/docs/sslcerts.html

```

--------------------------------

### Import GPG keys for Haskell binaries

Source: https://www.haskell.org/ghcup/install/manual

Import these GPG keys to verify the integrity of downloaded Haskell binaries on Unix-like systems.

```bash
gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 7D1E8AFD1D4A16D71FADA2F2CCC85C0E40C06A8C
```

```bash
gpg --batch --keyserver keyserver.ubuntu.com --recv-keys FE5AB6C91FEA597C3B31180B73EDE9E8CFBAEF01
```

```bash
gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 88B57FCF7DB53B4DB3BFA4B1588764FBE22D19C4
```

```bash
gpg --batch --keyserver keyserver.ubuntu.com --recv-keys EAF2A9A722C0C96F2B431CA511AAD8CEDEE0CAEF
```

--------------------------------

### Make External Packages Visible with cabal-install

Source: https://www.haskell.org/ghcup/steps

Generate an environment file to make 'async' and 'say' visible for GHC tools in the current directory.

```bash
cabal install --lib async say --package-env .

```

--------------------------------

### Configure Mirror URL in GHCup YAML

Source: https://www.haskell.org/ghcup/guide/channels

This YAML configuration demonstrates how to set up a third-party mirror by specifying a direct URL for the metadata file in the `url-source` list.

```yaml
url-source:
  - https://mirror.sjtu.edu.cn/ghcup/yaml/ghcup/data/ghcup-0.0.9.yaml

```

--------------------------------

### Configure Bubblewrap for Build System

Source: https://www.haskell.org/ghcup/guide/config

Integrate bubblewrap with GHCup to execute build commands in a sandboxed environment. This enhances security by isolating build processes from the host system. Ensure the specified paths for bind mounts are correct for your system.

```yaml
build-wrapper:
  cmd: bwrap
  cmdArgs:
    [ --ro-bind, /, /
    , --bind, /home/wurst/.ghcup, /home/wurst/.ghcup
    , --bind, /home/wurst/.cabal, /home/wurst/.cabal
    , --dev, /dev
    , --proc, /proc
    , --tmpfs, /tmp
    ]

```

--------------------------------

### Compile GHC from Source

Source: https://www.haskell.org/ghcup/about/known_problems

If facing issues with precompiled binaries, such as missing libtinfo, you can attempt to compile GHC from source using ghcup.

```bash
ghcup compile <version>
```

--------------------------------

### Create Stack GHCup Hook Manually

Source: https://www.haskell.org/ghcup/guide/stack

Manually create a GHCup hook for Stack by downloading the `ghc-install.sh` script and making it executable. This hook allows Stack to use GHCup for GHC management.

```shell
cd "$(stack path --stack-root)"
mkdir hooks
cd hooks
curl -O https://raw.githubusercontent.com/haskell/ghcup-hs/master/scripts/hooks/stack/ghc-install.sh
chmod +x ghc-install.sh
stack config set system-ghc false --global
```

--------------------------------

### Curl Schannel Error Example

Source: https://www.haskell.org/ghcup/guide/trouble

This error message from curl indicates a problem with the Windows Schannel security package, specifically related to certificate revocation checks.

```text
curl: (35) schannel: next InitializeSecurityContext failed: CRYPT_E_NO_REVOCATION_CHECK (0x80092012) - The revocation function was unable to check revocation for the certificate.

```

--------------------------------

### Configure Make/Configure Environment

Source: https://www.haskell.org/ghcup/packaging/new_tools

Specifies environment variables for `configure` and `make` steps. `union` determines how specified variables interact with existing system variables.

```yaml
configure:
  configFile: configure
  configArgs:
    - --prefix=${PREFIX}
  configEnv:
    env:
      - ["CC", "clang"]
    union: PreferSpec
make:
  makeArgs:
    - DESTDIR=${TMPDIR}
    - install
  makeEnv:
    env:
      - ["SED", "gsed"]
    union: PreferSystem

```

--------------------------------

### Use Wget Instead of Curl on Unix-like Systems

Source: https://www.haskell.org/ghcup/guide/trouble

If curl fails due to certificate issues, try using wget as an alternative downloader for the GHCup bootstrap script.

```sh
`wget -O /dev/stdout https://raw.githubusercontent.com/haskell/ghcup-hs/master/scripts/bootstrap/bootstrap-haskell | BOOTSTRAP_HASKELL_DOWNLOADER=wget sh`
```

--------------------------------

### Load Haskell File in GHCi

Source: https://www.haskell.org/ghcup/steps

Load the hello.hs file into the GHCi session using the :load command.

```haskell
ghci> :load hello.hs
[1 of 1] Compiling Main             ( hello.hs, interpreted )
Ok, one module loaded.
ghci> main
Hello, Haskell!

```

--------------------------------

### Build GHCup Release Binaries with Cabal

Source: https://www.haskell.org/ghcup/dev

Build the release binaries for GHCup using Cabal, specifying the release project file.

```bash
cabal build --project-file=cabal.project.release
```

--------------------------------

### Add a dependency to a Haskell project

Source: https://www.haskell.org/ghcup/steps

Modify the `build-depends` field in your `.cabal` file to include new dependencies. Ensure the dependency is listed with its version. For example, adding the `directory` package.

```cabal
library
    exposed-modules:  MyLib

    -- Modules included in this library but not exported.
    -- other-modules:

    -- LANGUAGE extensions used by modules in this package.
    -- other-extensions:
    build-depends:    base ^>=4.14.3.0
    hs-source-dirs:   src
    default-language: Haskell2010
```

```cabal
    build-depends:    base ^>=4.14.3.0
                    , directory
```

--------------------------------

### Launch GHCup TUI

Source: https://www.haskell.org/ghcup/guide

Use this command to launch the interactive text-based user interface for GHCup.

```bash
ghcup tui

```

--------------------------------

### Build GHCup with Cabal

Source: https://www.haskell.org/ghcup/dev

Use this command to build the GHCup project with Cabal, allowing specification of the GHC version.

```bash
cabal build
```

--------------------------------

### Configure GHCup to Use Local Git Metadata

Source: https://www.haskell.org/ghcup/guide/channels

Update GHCup's `config.yaml` to point to local metadata files cloned from the Git repository. This enables instant TUI startup as metadata is read from disk.

```yaml
url-source:
- file:///home/user/git/ghcup-metadata/ghcup-0.0.9.yaml
- file:///home/user/git/ghcup-metadata/ghcup-cross-0.0.9.yaml
- file:///home/user/git/ghcup-metadata/ghcup-prereleases-0.0.9.yaml

```

--------------------------------

### Update HLS from Git Master for Multiple GHCs

Source: https://www.haskell.org/ghcup/guide/compiling

Install HLS from the master git branch for multiple GHC versions. This creates a new HLS version in ghcup, potentially with a name like '1.7.0.0-105-gdc682ba1'.

```bash
ghcup compile hls --git-ref master --git-describe-version --ghc 8.10.7 --ghc 9.2.4 --cabal-update
```

--------------------------------

### Show All Revisions

Source: https://www.haskell.org/ghcup/guide

Displays all available GHC revisions, including older ones that are not shown by default.

```bash
ghcup list --show-revisions=all

```

--------------------------------

### Configure Binary Symlinks

Source: https://www.haskell.org/ghcup/packaging/new_tools

Defines how binaries are symlinked into `~/.ghcup/bin/`. Use `target` for the binary path, `linkName` for the symlink name, `setName` for the alias, and `pVPMajorLinks` for versioned symlinks.

```yaml
exeSymLinked:
  - target: "bin/dhall"
    linkName: "dhall-${PKGVER}"
    setName: "dhall"
    pVPMajorLinks: true

```

--------------------------------

### Specify Alternative Metadata File via Command Line

Source: https://www.haskell.org/ghcup/guide/channels

Use the `--url-source` option with GHCup to specify an alternative metadata file, either by alias or a direct URL. This overrides the configuration file setting for the current command.

```bash
ghcup --url-source=prereleases tui
ghcup --url-source=https://some-url/ghcup-0.0.9.yaml tui

```

--------------------------------

### Add Release Channels via Command Line

Source: https://www.haskell.org/ghcup/guide/channels

Use the `ghcup config add-release-channel` command to add 'prerelease' and 'cross' channels. This modifies the GHCup configuration file.

```bash
ghcup config add-release-channel prereleases
ghcup config add-release-channel cross

```

--------------------------------

### Run a Haskell Program with runghc

Source: https://www.haskell.org/ghcup/steps

Interpret and run the hello.hs file directly without explicit compilation.

```bash
➜ runghc hello.hs
Hello, Haskell!

```

--------------------------------

### Compile with Warnings Enabled

Source: https://www.haskell.org/ghcup/steps

Compile the Haskell program with the -Wall flag to enable all warnings and -fforce-recomp to force recompilation.

```bash
➜ ghc -Wall hello.hs -fforce-recomp
[1 of 1] Compiling Main             ( hello.hs, hello.o )

hello.hs:1:1: warning: [-Wmissing-signatures]
    Top-level binding with no type signature: main :: IO ()
  |
1 | main = putStrLn "Hello, Haskell!"
  | ^^^^
Linking hello ...

```

--------------------------------

### GHCup Configuration with Multiple Release Channels

Source: https://www.haskell.org/ghcup/guide/channels

This YAML configuration shows how multiple release channels are specified in GHCup's `config.yaml` file. Later channels take precedence over earlier ones.

```yaml
url-source:
- GHCupURL # An alias for the base URL that contains all the release bindists
- prereleases
- cross

```

--------------------------------

### Import GPG Keys for ghcup Verification

Source: https://www.haskell.org/ghcup/guide

Import necessary GPG keys from a keyserver to verify the signature of the ghcup metadata file. This is a prerequisite for enabling GPG verification in ghcup.

```bash
gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 7D1E8AFD1D4A16D71FADA2F2CCC85C0E40C06A8C
gpg --batch --keyserver keyserver.ubuntu.com --recv-keys FE5AB6C91FEA597C3B31180B73EDE9E8CFBAEF01
gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 88B57FCF7DB53B4DB3BFA4B1588764FBE22D19C4
gpg --batch --keyserver keyserver.ubuntu.com --recv-keys EAF2A9A722C0C96F2B431CA511AAD8CEDEE0CAEF

```

--------------------------------

### Import and Use External Packages in GHCi

Source: https://www.haskell.org/ghcup/steps

Import and use functions from the 'async' and 'say' packages within GHCi.

```haskell
GHCi, version 9.0.1: https://www.haskell.org/ghc/  :? for help
ghci> import Control.Concurrent.Async
ghci> import Say
ghci> concurrently_ (sayString "Hello") (sayString "World")
Hello
World

```

--------------------------------

### Compile HLS from Hackage

Source: https://www.haskell.org/ghcup/guide/compiling

Compile HLS from a specific version available on Hackage. Ensure your system meets prerequisites.

```bash
ghcup compile hls --version 1.7.0.0 --ghc 9.2.3
```

--------------------------------

### Configure Cabal for MSYS2 on Windows

Source: https://www.haskell.org/ghcup/install/manual

Modify the Cabal config file to include MSYS2 include and library directories, and set program paths.

```text
extra-include-dirs: C:\msys64\mingw64\include
extra-lib-dirs: C:\msys64\mingw64\lib
extra-prog-path: C:\ghcup\bin, C:\cabal\bin, C:\msys64\mingw64\bin, C:\msys64\usr\bin
```

--------------------------------

### Add Tool Details

Source: https://www.haskell.org/ghcup/packaging/new_tools

Injects metadata for a tool, including homepage, repository, description, and author information, directly under the tool name.

```yaml
ghcupDownloads:
  dhall:
    toolDetails:
      toolHomepage: "https://dhall-lang.org/"
      toolRepository: "https://github.com/dhall-lang/dhall-lang"
      toolDescription: "Maintainable configuration files"
      toolAuthor: "Gabriella Gonzalez"
      toolMaintainer: "Gabriella Gonzalez"
      toolContact: "some-email@gmail.com"
    toolVersions:
      1.42.2:
        viTags:
          - Latest
          - Recommended
        viArch:
          A_64:
            Linux_UnknownLinux:
          # ... etc.

```

--------------------------------

### Default GHCup Configuration

Source: https://www.haskell.org/ghcup/guide/channels

The default configuration for GHCup specifies only the base URL for release bindists.

```yaml
url-source:
  - GHCupURL

```

--------------------------------

### Run the main executable

Source: https://www.haskell.org/ghcup/steps

Use `cabal run` to compile and execute the main program of your Haskell project. The output will be displayed in the terminal.

```bash
cabal run
```

--------------------------------

### Add New GHC Version Link

Source: https://www.haskell.org/ghcup/dev

Reference for adding a new GHC version to the GHCup metadata repository.

```markdown
https://github.com/haskell/ghcup-metadata#adding-a-new-ghc-version
```

--------------------------------

### Configure Stack to Use System GHC

Source: https://www.haskell.org/ghcup/guide/stack

Globally configure Stack to use the system GHC (including GHCup managed ones) and disable its own GHC management. This is an alternative strategy to using hooks.

```shell
stack config set system-ghc true --global
stack config set install-ghc false --global
```

--------------------------------

### Run a Compiled Haskell Program

Source: https://www.haskell.org/ghcup/steps

Execute the compiled Haskell program.

```bash
➜ ./hello
Hello, Haskell!

```

--------------------------------

### Compile HLS from Source Distribution

Source: https://www.haskell.org/ghcup/guide/compiling

Compile HLS from a source distribution tarball packaged during release. This uses a specific version number.

```bash
ghcup compile hls --source-dist 1.7.0.0 --ghc 9.2.3
```

--------------------------------

### Import and Use Library Modules in GHCi

Source: https://www.haskell.org/ghcup/steps

Import the Data.Bits module and use its functions for bitwise operations.

```haskell
ghci> import Data.Bits
ghci> shiftL 32 1
64
ghci> clearBit 33 0
32

```

--------------------------------

### Compile HLS with Cabal Update

Source: https://www.haskell.org/ghcup/guide/compiling

Instruct ghcup to run 'cabal update' before building HLS. This ensures the package index is up-to-date.

```bash
ghcup compile hls --version 1.7.0.0 --ghc 9.2.3 --cabal-update
```

--------------------------------

### Configure Patterned Binary Symlinks

Source: https://www.haskell.org/ghcup/packaging/new_tools

Specifies symlinks using patterns for more complex scenarios like HLS. `${TARGETFN}` resolves to the matched filename.

```yaml
exeSymLinked:
- targetPattern: ["bin/haskell-language-server-wrapper*"]
  linkName: "${TARGETFN}-${PKGVER}"
  setName: "${TARGETFN}"
- targetPattern: ["bin/haskell-language-server-*"]
  targetPatternIgnore: ["bin/haskell-language-server-wrapper*"]
  linkName: "${TARGETFN}~${PKGVER}"
  setName: "${TARGETFN}"

```

--------------------------------

### Enable GHC Linker Override

Source: https://www.haskell.org/ghcup/guide

Configure ghcup to enable GHC's default linker override behavior by adding '--enable-ld-override' to 'def-ghc-conf-options' in ~/.ghcup/config.yaml. This ensures GHC respects the system's default linker.

```yaml
def-ghc-conf-options:
  - "--enable-ld-override"

```

--------------------------------

### Upgrade GHCup

Source: https://www.haskell.org/ghcup/guide

Updates GHCup to the latest available version.

```bash
ghcup upgrade

```

--------------------------------

### Add a new module to the Haskell package

Source: https://www.haskell.org/ghcup/steps

To include a new module, add its name to the `exposed-modules` list in your `.cabal` file and create the corresponding `.hs` file in the `src` directory.

```cabal
    exposed-modules:  MyLib
                      OtherLib
```

--------------------------------

### Configure GPG Verification Mode in ghcup

Source: https://www.haskell.org/ghcup/guide

Set the GPG verification mode in ~/.ghcup/config.yaml to control how ghcup handles GPG signature verification. Options include 'GPGLax', 'GPGStrict', and 'GPGNone'.

```yaml
gpg-setting: GPGLax # GPGStrict | GPGLax | GPGNone

```
Tokens:
Raw