This repository has been moved to https://gitlab.haskell.org/ghc/ghc.nix

These Nix expressions provide an environment for GHC development.

This repository does not contain the GHC sources themselves, so make sure you've cloned that repository first. The directions at https://ghc.dev are an excellent place to start.

Simple usage

Quickstart

To enter an environment without cloning this repository you can run:

nix-shell https://github.com/alpmestan/ghc.nix/archive/master.tar.gz --attr devShells.<your-system>.default

where <your-system> would be the nix name of your system, in the typical case this is one of

x86_64-linux (for x86_64 Linux systems)
aarch64-linux (for ARM Linux systems)
x86_64-darwin (for old macs that do not have apple silicon)
aarch64-darwin (for macs with apple silicon)

Hence, an invocation on an x86_64 Linux system would look like this:

nix-shell https://github.com/alpmestan/ghc.nix/archive/master.tar.gz --attr devShells.x86_64-linux.default

Using flakes

This repository is flakes enabled, which means, that you can more easily get a devShell using:

nix develop github:alpmestan/ghc.nix

Building GHC

These commands assume you have cloned this repository to ~/ghc.nix. shell.nix has many parameters, all of them optional. You should take a look at ghc.nix for more details.

$ nix-shell ~/ghc.nix/shell.nix
# from the nix shell:
$ ./boot && configure_ghc
# example hadrian command: use 4 cores, build a 'quickest' flavoured GHC
# and place all the build artifacts under ./_mybuild/.
$ hadrian/build -j4 --flavour=quickest --build-root=_mybuild

# if you have never used cabal-install on your machine, you will likely
# need to run the following before the hadrian command:
$ cabal update

Note

configure_ghc runs ./configure $CONFIGURE_ARGS. While this is technically optional, this argument ensures that configure knows where the compiler's dependencies (e.g. gmp, libnuma, libdw) are found, allowing the compiler to be used even outsite of nix-shell. Plus, for the JavaScript cross compiler, configure_ghc actually runs the wrapper emconfigure!

If you are using zsh and you want to run ./configure directly, you must pass ${=CONFIGURE_ARGS} instead; otherwise zsh will escape the spaces in $CONFIGURE_ARGS and interpret it as one single argument. See also https://unix.stackexchange.com/a/19533/61132.

When you want to let Nix fetch Hadrian dependencies enter the shell with

$ nix-shell ~/ghc.nix/shell.nix --arg withHadrianDeps true

When using flakes, this argument is automatically applied.

Using `haskell-language-server`

You can also use ghc.nix to provide the right version of haskell-language-server (hls) if you want to use hls whilst developing on GHC. In order to do so, pass the withIde argument to your nix-shell invocation.

nix-shell ~/.ghc.nix/shell.nix --arg withIde true

When using flakes, this argument is also automatically applied.

$ nix develop github:alpmestan/ghc.nix
# HLS is already available

Running `./validate`

$ nix-shell ~/ghc.nix/shell.nix --pure --run 'THREADS=4 ./validate'

See other flags of validate by invoking ./validate --help or just by reading its source code.

Note ./validate --slow builds the compiler in debug mode which has the side-effect of disabling performance tests.

Building and running for i686-linux from x86_64-linux

It's trivial!

$ nix-shell ~/ghc.nix/shell.nix --arg nixpkgs '(import <nixpkgs> {}).pkgsi686Linux'

Building a WebAsm or JavaScript cross-compiler

Both cross-compilers are supported with nix-shell or the flake-based nix develop.

CC, CONFIGURE_ARGS, etc. environment variables will be overridden to configure the cross-compiler.

Once in the shell, use ./boot && configure_ghc, then proceed with hadrian as usual.

HLS should also just work.

For WebAsm:

nix-shell ~/ghc.nix --arg withWasm true
# or
nix develop github:alpmestan/ghc.nix#wasm-cross

For JavaScript:

nix-shell ~/ghc.nix --arg withEMSDK true
# or
nix develop github:alpmestan/ghc.nix#js-cross

Note for the JavaScript backend, use bignum=native or the native_bignum transformer.

Cachix

There is a Cachix cache (ghc-nix) which is filled by our CI. To use it, run the following command and follow the instructions:

cachix use ghc-nix

The cache contains Linux x64 binaries of all packages that are used during a default build (i.e. a build without any overridden arguments).

Updating `ghc.nix`

to update everything: nix flake update
to update other inputs: run nix flake lock --update-input other-input-name
available inputs:
- nixpkgs (used to provide some tooling, like texlive)
- flake-compat (to ensure compatibility with pre-flake nix)
- all-cabal-hashes (for the cabal-hashes of the haskell packages used)
to use a certain commit for any of the inputs: use flag --override-input, e.g.
```
nix develop --override-input all-cabal-hashes "github:commercialhaskell/all-cabal-hashes/f4b3c68d6b5b128503bc1139cfc66e0537bccedd"
```
this is not yet support in flake-compat mode, you will have to manually set the version in the flake.nix by appending /your-commit-hash to the input you want to change, then running nix flake lock --update-input input-you-want-to-update. Of course you can also just manually pass your own nixpkgs version to the shell.nix, this will override the one provided by the flake.
if you plan to upstream your modifications to ghc.nix, don't forget to run the formatter using nix fmt

Flake support

ghc.nix now also has basic flake support, nixpkgs and the cabal-hashes are pinned in the flake inputs.

To format all nix code in this repository, run nix fmt, to enter a development shell, run nix develop.

To change the settings of the devShell to your liking, just adjust the userSettings attribute-set in the top-level flake.

Warning Building a derivation from the local (ghc) hadrian requires builtins.getEnv which is only available if --impure is passed.

Using the flake template

It is common that you want to change the settings that ghc.nix uses to set up a devShell. Currently there is no good way in nix to pass nix expressions to flakes.

This is why we provide a flake template that you can add to your git worktree as follows:

$ nix flake init -t github:alpmestan/ghc.nix

This will add three files to your worktree:

a flake.nix which you can edit your userSettings in as usual
a flake.lock file which pins the ghc.nix version and transitively nixpkgs and all-cabal-hashes
a .envrc file for convenient use with direnv

Legacy nix-commands support

We use flake-compat to ensure compatibility of the old nix commands with the new flake commands and to use the flake inputs pinned by nix itself. Unfortunately there is a shortcoming of the current implementation of the flake nix commands that makes it so that you cannot pass arguments to the devShells. To ensure backwards compatibility, we call a function that we keep as flake output from the ./shell.nix file. Most importantly, this means that the shell.nix in this repo doesn't behave like a normal flake-compat shell but rather like a legacy shell.nix that can indeed be passed arguments. The default.nix behaves just like you would expect it to behave with the use of flake-compat.

The following table shows what ./ghc.nix can be configured with; the first column is the name of the attribute to be configured, the second argument the description of that argument, the third the default value for that argument and the third one, whether or not the flake.nix takes over orchestration of this attribute, this is the case if they're either pinned by the lock-file (e.g. nixpkgs) or can introduce impurity (e.g. system)

If you do not want to pass your arguments with --arg, but rather capture your passed arguments in a .nix file, you can locally create a file, say shell.nix with the following contents:

import ./path/to/ghc.nix/shell.nix {
  withHadrianDeps = true;
  withIde = true;
  # ... and so on
}

be careful to specify the path to the shell.nix, not to the default.nix.

attribute-name	description	default	orchestrated by nix flake
`system`	the system this is run on	`builtins.currentSystem` or flake system	✅
`nixpkgs`	the stable `nixpkgs` set used	`nixpkgs` as pinned in the lock-file	✅
`all-cabal-hashes`	the `all-cabal-hashes` version used	`all-cabal-hashes` as pinned in the lock-file	✅
`bootghc`	the bootstrap `ghc` version	`"ghc924"`	❌
`version`	the version of `ghc` to be bootstrapped	`"9.3"`	❌
`hadrianCabal`	where `hadrian` is to be found	`(builtins.getEnv "PWD") + "/hadrian/hadrian.cabal"`	❌
`useClang`	whether Clang is to be used for C compilation	`false`	❌
`withLlvm`	whether `llvm` should be included in the `librarySystemDepends`	`false`	❌
`withDocs`	whether to include dependencies to compile docs	`true`	❌
`withGhcid`	whether to include `ghci`	`false`	❌
`withIde`	whether to include `hls`	`false`	❌
`withHadrianDeps`	whether to include dependencies for `hadrian`	`false`	❌
`withDwarf`	whether to enable `libdw` unwinding support	`nixpkgs.stdenv.isLinux`	❌
`withNuma`	whether to enable `numa` support	`nixpkgs.stdenv.isLinux`	❌
`withDtrace`	whether to include `linuxPackage.systemtap`	`nixpkgs.stdenv.isLinux`	❌
`withGrind`	whether to include `valgrind`	`true`	❌
`withEMSDK`	whether to include `emscripten` for the js-backend, will create an `.emscripten_cache` folder in your working directory of the shell for writing. `EM_CACHE` is set to that path, prevents sub word sized atomic kinds of issues	`false`	❌
`withWasm`	whether to include `wasi-sdk` & `wasmtime` for the ghc wasm backend	`false`	❌
`withFindNoteDef`	install a shell script `find_note_def`; `find_note_def "Adding a language extension"` will point to the definition of the Note "Adding a language extension"	`true`	❌

`direnv`

With nix-direnv support, it is possible to make direnv load ghc.nix upon entering your local ghc directory. Just put a .envrc containing use flake /home/theUser/path/to/ghc.nix# in the ghc directory. This works for all flake URLs, so you can also put use flake github:alpmestan/ghc.nix# in there and it should work.

Warning If you're building an older GHC (not including this commit), be careful about not checking out .direnv, it's the local cache of your development shell which makes loading it upon entering the directory instant.

contributing

we check formatting and linting in our CI, so please be careful to run nix flake check --allow-import-from-derivation --impure before submitting changes as a PR
the tooling to run the linting is provided by a nix devShell which you can easily obtain by running nix develop .#formatting. Now you only have to run pre-commit run --all to check for linting and to reformat; using this devShell, the formatting will also be checked before committing. You can skip the check by passing --no-verify to the git commit command
ghc.nix also offers direnv integration, so if you have it installed, just run direnv allow to automatically load the formatting devShell and the accompanying pre-commit hook.

alpmestan / ghc.nix

readme

Simple usage

Quickstart

Using flakes

Building GHC

Using `haskell-language-server`

Running `./validate`

Building and running for i686-linux from x86_64-linux

Building a WebAsm or JavaScript cross-compiler

For WebAsm:

For JavaScript:

Cachix

Updating `ghc.nix`

Flake support

Using the flake template

Legacy nix-commands support

`direnv`

contributing

alpmestan / ghc.nix

readme

Simple usage

Quickstart

Using flakes

Building GHC

Using haskell-language-server

Running ./validate

Building and running for i686-linux from x86_64-linux

Building a WebAsm or JavaScript cross-compiler

For WebAsm:

For JavaScript:

Cachix

Updating ghc.nix

Flake support

Using the flake template

Legacy nix-commands support

direnv

contributing

Using `haskell-language-server`

Running `./validate`

Updating `ghc.nix`

`direnv`