This is the Stable Haskell Edition of GHC, not the upstream GHC codebase.
This is the source tree for GHC, a compiler and interactive environment for the Haskell functional programming language.
Important: All issues and bug reports for this fork should be reported at: https://github.com/stable-haskell/ghc/issues
For more information about upstream GHC, visit GHC's web site.
Information for developers of upstream GHC can be found on the GHC issue tracker, and you can also view proposals for new GHC features.
There are two ways to get a source tree:
-
Download source tarballs
Download the GHC source distribution:
ghc-<version>-src.tar.xzwhich contains GHC itself and the "boot" libraries.
-
Check out the source code from git
$ git clone --recurse-submodules https://github.com/stable-haskell/ghc.git
See the GHC team's working conventions regarding how to contribute a patch to GHC. First time contributors are encouraged to get started by just sending a Merge Request.
For full information on building GHC, see the GHC Building Guide. Here follows a summary - if you get into trouble, the Building Guide has all the answers.
To build GHC, you need:
- A working version of GHC (>= 9.8.4), as the compiler is written in Haskell
- cabal-install
Both the bootstrap compiler and cabal-install can be easily installed with GHCup:
$ ghcup install ghc --set 9.8.4
$ ghcup install cabal
For additional system dependencies and libraries, see Setting up your system for building GHC. For instructions on how to port GHC to a new platform, see the GHC Building Guide.
For building library documentation, you'll need Haddock. To build the compiler documentation, you need Sphinx and Xelatex (only for PDF output).
Quick start: The following gives you a default build:
$ make CABAL=$PWD/_build/stage0/bin/cabal
On Windows, you should run the build command from an appropriate environment (e.g., MSYS2).
This gives you the default build, which includes everything optimised and built. It can take a long time.
To run the test suite:
$ make test CABAL=$PWD/_build/stage0/bin/cabal
To build javascript-unknown-ghcjs:
- Download the emscripten toolchain using the instructions at https://emscripten.org/docs/getting_started/downloads.html
- Activate the environment using
source ./emsdk_env.sh make stage3-javascript-unknown-ghcjs
Stage3 builds pinned native Alex and Happy with the bootstrap compiler, including
when DIST_BUILD=1 uses a prebuilt bindist. These tools and their matching data
files live under _build/stage3-tools; stage3 does not require them on PATH.
Stages 1 and 2 can be built with Buck2 through the
experimental cabal buck2 command
(announcement).
cabal buck2 builds the dependencies with Cabal and generates a
BUCK.cabal.bzl file per package; buck2 then builds the packages.
This experimental path is tested on x86_64 Linux with GHC 9.8.4 as the boot compiler. Install GHC 9.8.4, cabal-install, the usual GHC build prerequisites, GNU coreutils, curl, git, Python 3 and zstd. The helper installs the compatible Buck2 release and patched Cabal and haskell-buck2 sources at exact commits (the patches are not upstream yet):
$ mk/buck2-tools.sh _build/buck2-tools ghc-9.8.4
$ export PATH="$PWD/_build/buck2-tools/bin:$PATH"
$ make buck2-stage1 CABAL_BUCK2="$PWD/_build/buck2-tools/bin/cabal" GHC0=ghc-9.8.4
$ buck2 build //... -m opt
$ buck2 build //ghc:ghc -m opt --show-output # the stage-1 compiler
The helper currently supports Linux only. It checks the downloaded
Buck2 archive's SHA-256 before running it and records source identities
alongside the cached tools. To try other tool sources, override the
repository/revision variables listed in mk/buck2-tools.sh and use a
fresh prefix and a clean ./buck2 checkout of the requested revision.
The CI cache key includes this script, so changing a pin invalidates it.
Stage 2 is built by the stage-1 compiler, through the wrappers of
buck2-ghc/BUCK (//buck2-ghc:ghc runs //ghc:ghc with a libdir of its
own). make buck2-stage2 runs cabal buck2 --variant stage2 on
cabal.project.stage2.buck2: every package gets a BUCK.stage2.cabal.bzl
with targets suffixed -stage2, built in the stage2 platform
(buck2/platforms/BUCK) where the toolchain is the stage-1 compiler.
$ make buck2-stage2 CABAL_BUCK2="$PWD/_build/buck2-tools/bin/cabal" GHC0=ghc-9.8.4
$ buck2 build //buck2-ghc:stage2-libdir -m opt --show-output # the stage-2 installation
//buck2-ghc:stage2-libdir is an installation: bin/ghc is
//ghc:ghc-stage2 with a libdir where every stage-2 library is
registered, next to ghc-pkg, hsc2hs, haddock, hpc, hp2ps,
runghc, ghc-iserv and unlit. mk/buck2-smoke-test.sh <store>
compiles and runs programs with it (libraries, -threaded, Template
Haskell with both interpreters, the FFI, hsc2hs, runghc and Haddock HTML
generation). The runghc and Haddock wrappers select the installed compiler
and libdir; Haddock's auxiliary files are copied from haddock-api's data
files. The stage-2 libraries are static (the stage2 platform selects
static linkage).
mk/buck2-tools.sh <prefix> installs the tools (buck2, the cabal with
the buck2 command, haskell-buck2 at ./buck2); the workflow
.github/workflows/buck2.yml runs all of this on CI.
Packages with a Custom Setup.hs have a hand-maintained BUCK file next
to the generated BUCK.cabal.bzl: compiler/BUCK (primop .hs-incl
files, GHC.Platform.Constants, GHC.Settings.Config) and
libraries/ghc-boot/BUCK (GHC.Platform.Host). libraries/ghc-boot-th
and libraries/ghc-internal have a BUCK that exports their sources for
ghc-boot-th-next. rts/BUCK registers the RTS ways as sub-libraries of
the rts unit, libraries/ghc-internal/BUCK generates the two modules
the compiler prints (GHC.Internal.Prim, GHC.Internal.PrimopWrappers).
Stage 3 is not supported.
If you've encountered what you believe is a bug in this fork, or you'd like to propose a feature request, please let us know! Submit an issue at https://github.com/stable-haskell/ghc/issues and we'll be sure to look into it. Remember: Filing a bug is the best way to make sure your issue isn't lost over time, so please feel free.
If you're an active user of GHC, you may also be interested in joining the glasgow-haskell-users mailing list, where developers and GHC users discuss various topics and hang out.
Make sure your system has the necessary tools to compile GHC. You can find an overview of how to prepare your system here:
https://gitlab.haskell.org/ghc/ghc/wikis/building/preparation
After building GHC (see "Building & Installing" above), you can start making your commits. When you're done, you can submit a merge request to GitLab for code review.
Changes to the base library require a proposal to the
core libraries committee.
The GHC Wiki has a good summary for the overall process. One or several reviewers will review your PR, and when they are ok with your changes, they will assign the PR to Marge Bot which will automatically rebase, batch and then merge your PR (assuming the build passes).
The home for GHC hackers is our GitLab instance:
https://gitlab.haskell.org/ghc/ghc
From here, you can file bugs (or look them up), use the wiki, view the git history, among other things.
An overview of things like using Git, the release process, filing bugs and more can be located here:
https://gitlab.haskell.org/ghc/ghc/wikis/contributing
You can find our coding conventions for the compiler and RTS here:
https://gitlab.haskell.org/ghc/ghc/wikis/commentary/coding-style https://gitlab.haskell.org/ghc/ghc/wikis/commentary/rts/conventions
If you're going to contribute regularly, learning how to use the build system is important and will save you lots of time. You should read over this page carefully:
https://gitlab.haskell.org/ghc/ghc/wikis/building/using
If you want to watch issues and code review activities, the following page is a good start:
https://gitlab.haskell.org/ghc/ghc/activity
GHC is a big project, so you'll surely need help. Luckily, we can provide plenty through a variety of means!
If you're a Discord user, you can join our server.
GHC is a community project developed by a team of highly-talented researchers, individual contributors, and full-time developers. We are indebted to the many people whose work has brought GHC to its current state.
Some larger decisions are made by a smaller group of core contributors, as described in our governance documentation.