How it started

🤹 small team at work (Capital Match), using different platforms
- originally used stack
- distro packages constantly out of date
🦾 first version was 165 LOC
- Posix shell
only supported linux and mac
inspired by rustup
support from Herbert/haskell.org

GHCup today

Haskell Survey 2022:

over 17k LOC Haskell
supports all platforms: Linux, Windows, macOS, FreeBSD
first thing new Haskell users get exposed to

GHCup and haskell.org

The default installer:

provides infrastructure (home page, downloads)

GHCup and the Haskell Foundation

affiliation: https://haskell.foundation/affiliates/
pays for CI
pays consultants to assist the project

What is a good installer?

it installs (just that)
- everywhere
intuitive interface
- ghcup install ghc
good documentation
- but you shouldn’t have to read it
get out of the way
- has no self-fulfilling purpose

Goals and principles

☮️ unification
unix principles
- 🛠️ do one thing and do it well
- ⚗️ pipes, compose stdout and stdin (re-usable)
🎁 good re-distribution
🛣️ user experience

What is GHCup (simplified)?

curl -s -L 'https://downloads.haskell.org/~ghc/9.6.5/ghc-9.6.5-x86_64-fedora33-linux.tar.xz' |
  tar -xJ -C /tmp                              &&
  cd /tmp/ghc-9.6.5-x86_64-unknown-linux/      &&
  ./configure --prefix="$HOME/.local"          &&
  make install                                 &&
  rm -rf /tmp/ghc-9.6.5-x86_64-unknown-linux/

What is GHCup really?

https://hasufell.github.io/posts/2023-11-14-ghcup-is-not-an-installer.html
installer (portable)
distribution channel
feedback channel
testing/QA gateway
provider of sane defaults (e.g. “recommended” GHC version)
glue for holistic toolchain experience
- VSCode, stack, cabal-install integration
CI provisioning (e.g. github actions)

Upstream (dependencies)

supported tools
- GHC
- Cabal
- HLS
- Stack
decisions that affect us
- release frequency
- upstream CI
- platform support
- binary distributions (the .tar.gz/.zip)

Downstream (dependents)

Haskell developers
- beginners, advanced, students, companies
end users (e.g. compiling pandoc from source)
GitHub CI
- GitHub images, Haskell repos
🪞 mirrors
- sjtug
🧰 tools
- vscode-haskell, Haskell playground, nvim-lsp-installer

The installer in detail

How does it work?

Architectural components
- bootstrap scripts
- ghcup binary (compiled)
- ghcup-metadata
Logical components
- cli interface
- file layout / installation destination
- bindist selection
- tui interface
- configuration

Basic CLI (context)

Architectural components
- bootstrap scripts
- ghcup binary (compiled)
- ghcup-metadata
Logical components
- cli interface
- file layout / installation destination
- bindist selection
- tui interface
- configuration

Basic CLI

show all available tools / versions
```
ghcup list
```
install a tool
```
ghcup install ghc latest
```
make a tool version the default
```
ghcup set ghc latest
```
remove a tool version
```
ghcup rm ghc 9.10.1
```

File layout (context)

Architectural components
- bootstrap scripts
- ghcup binary (compiled)
- ghcup-metadata
Logical components
- cli interface
- file layout / installation destination
- bindist selection
- tui interface
- configuration

File layout

root dir

$ ls ~/.ghcup
📁bin 📁ghc 📁hls
📁cache 📁db 📁logs 📁tmp 🗑️trash 📄config.yaml 📄env

GHC and HLS are installed into sub-directories

$ ls ~/.ghcup/ghc
📁8.10.7 📁9.0.2 📁9.2.8

bin directory is mostly symbolic links (compare with update-alternatives)

$ ls ~/.ghcup/bin
📄ghcup
🔗cabal 📄cabal-3.10.3.0
🔗ghc 🔗ghc-8.10 🔗ghc-8.10.7 🔗ghc-9.0 🔗ghc-9.0.2 🔗ghc-9.2 🔗ghc-9.2.8

Bindist selection (context)

Architectural components
- bootstrap scripts
- ghcup binary (compiled)
- ghcup-metadata
Logical components
- cli interface
- file layout / installation destination
- bindist selection
- tui interface
- configuration

Bindist selection (sysinfo)

Gather system information:

module GHCup.Platform
System.Info.arch and System.Info.os (compile-time strings)
distro detection mostly via /etc/os-release
- specified by freedesktop.org
- using os-release package for parsing

Bindist selection (mapping)

Map binaries to systems:

binary compatibility (platform, distro, distro version)
- finite set of binaries
- statically linked GHC?
static mapping in ghcup-metadata YAML files
- Tool -> Version -> Architecture -> Platform/Distro -> binary URL
- mapping based on binary compatibility
  - https://gitlab.haskell.org/ghc/ghc/-/wikis/platforms/linux
alternative dynamic logic (utilizing ldconfig -p output)
- for stack compatibility
updated on every release
“channels”

TUI interface (context)

Architectural components
- bootstrap scripts
- ghcup binary (compiled)
- ghcup-metadata
Logical components
- cli interface
- file layout / installation destination
- bindist selection
- tui interface
- configuration

Configuration (context)

Architectural components
- bootstrap scripts
- ghcup binary (compiled)
- ghcup-metadata
Logical components
- cli interface
- file layout / installation destination
- bindist selection
- tui interface
- configuration

Configuration

Types of configuration:
- environment variables
- cli switches / TUI options
- config file (~/.ghcup/config.yaml)
e.g.
- env: GHCUP_INSTALL_BASE_PREFIX (default $HOME)
- cli: ghcup install ghc -u <url> <version>
- config: url-source (selecting and mixing “channels”)
  - file/http/https URI
  - GHCupURL
  - StackSetupURL

What is distribution?

QA gate between “upstream” and “downstream”
trust relationship (with upstream and downstream)
release selection and defaults
binary distribution

What happens on e.g. a GHC release

testing and inspection of bindists
- manual
- automated at github.com/haskell/ghcup-metadata
fixing bindists
building additional bindists (e.g. FreeBSD)
forks at github.com/stable-haskell
- builds cabal, stack and HLS binaries
- GHC TBD

The “recommended” versions (defaults)

community adoption (both industry and “open source”)
stack LTS
HLS support
known issues and regressions
GHC HQs opinion and support window
must be consistent across platforms

How to contribute

loose project structure (BDFL)
discuss early
repositories
- github.com/haskell/ghcup-hs: documentation, bootstrap-scripts, ghcup exe
- github.com/haskell/ghcup-metadata: bindist mapping (YAML), bindist testing
build with cabal/stack
Developer Guide
communication
- #haskell-ghcup on libera IRC
- #ghcup:matrix.org (bridged with IRC)
- github issues
- haskell discourse (interacting with the community)

Getting started

Head over to https://github.com/haskell/ghcup-hs/issues/1074 (zurihac labeled issue).

GHCup

Introduction

What is GHCup?

State of 2019