This repo is a collection of different GHCup metadata. These are mappings from tool versions (e.g. GHC 9.6.5) to bindist URLs (e.g. https://downloads.haskell.org/~ghc/9.6.5/ghc-9.6.5-x86_64-fedora33-linux.tar.xz), depending on architecture (e.g. X86_64), platform (e.g Linux) and possibly distro (e.g. Fedora).

• ghcup-A.B.C.yaml: this is the main metadata and what ghcup uses by default
• ghcup-vanilla-A.B.C.yaml: this is similar to ghcup-A.B.C.yaml, but only uses upstream bindists (no patches/fixes are applied, no missing platforms added)
• ghcup-prereleases-A.B.C.yaml: this contains pre-releases of all tools
• ghcup-cross-A.B.C.yaml: this contains experimental cross compilers. See https://www.haskell.org/ghcup/guide/#cross-support for details.

If you want access to both pre-releases and cross compilers, run:

ghcup config add-release-channel https://raw.githubusercontent.com/haskell/ghcup-metadata/master/ghcup-prereleases-0.0.7.yaml
ghcup config add-release-channel https://raw.githubusercontent.com/haskell/ghcup-metadata/master/ghcup-cross-0.0.8.yaml

If you want only vanilla upstream bindists and opt out of all unofficial stuff, you'd run:

ghcup config set url-source https://raw.githubusercontent.com/haskell/ghcup-metadata/master/ghcup-vanilla-0.0.8.yaml

Also check the config.yaml documentation.

This channel is strictly maintained by the GHCup project. Most bindists here are built downstream by the GHCup developers, e.g.:

• https://github.com/stable-haskell/haskell-language-server
• https://github.com/stable-haskell/cabal
• https://github.com/stable-haskell/stack

For GHC bindists there is no automation yet and it is done manually (e.g. for FreeBSD and Alpine i386).

You can suggest updates to tool versions via raising an issue or a PR.

These are technically maintained by the upstream developers (GHC, HLS, cabal and stack developers). GHCup developers do not interfere with decisions in general and do only little QA.

You can suggest updates to tool versions via raising an issue or a PR, but you may also want to CC some of the upstream developers.

For GHC:

• bgamari
• mpickering
• wz1000

For Cabal:

• Kleidukos
• geekosaur
• Mikolaj

For Stack:

• mpilgrem

For HLS:

• wz1000
• michaelpj

Other channels are maintained in collaboration.

Tags are documented here. Search for data Tag. Some tags are unique. Uniqueness is checked by cabal run ghcup-gen -- check -f ghcup-<yaml-ver>.yaml.

If you want to check prereleases, do: cabal run ghcup-gen -- check -f ghcup-prereleases-<yaml-ver>.yaml --channel=prerelease

The following things are relevant when raising a PR.

ghcup-gen is a cabal project that lives in this repository to aid with various metadata tasks. Run cabal run ghcup-gen -- --help for more information.

To test that the yaml is valid and certain tags are unique, you can run:

cabal run ghcup-gen -- check -f ghcup-0.0.8.yaml

To test that all bindists you just added are fetchable, you can run e.g.:

cabal run ghcup-gen -- check-tarballs -f ghcup-0.0.8.yaml -u 'ghc-9\.6\.6'

There is a manual workflow that runs smoke tests on all supported platforms against a tool version (e.g. installing GHC and compiling a hello world): https://github.com/haskell/ghcup-metadata/actions/workflows/bindists.yaml

To execute it your branch must exist on the main repository and you must have privileges to the repository. If you don't, ask the ghcup maintainer or some of the listed upstream maintainers.

Some of the failures are expected (e.g. armv7 on GHC).

• make sure to sign the yaml files you edited, e.g.: gpg --detach-sign -u <your-email> ghcup-0.0.8.yaml or ask a GHCup developer to sign
• PGP pubkeys need to be cross-signed by the GHCup team
• they need to be added to the CI: https://github.com/haskell/ghcup-metadata/blob/develop/.github/workflows/sigs
• and need to be documented on the homepage
  • https://github.com/haskell/ghcup-hs/blob/master/docs/guide.md#gpg-verification
  • https://github.com/haskell/ghcup-hs/blob/master/docs/install.md#unix

An introduction into GHCup can be found in this presentation: https://www.haskell.org/ghcup/talks/Zurihac2024/GHCup.html

You can also join the Matrix channel if you need help.