pyrox.dev
1# Haskell {#haskell}
2
3The Haskell infrastructure in Nixpkgs has two main purposes: The primary purpose
4is to provide a Haskell compiler and build tools as well as infrastructure for
5packaging Haskell-based packages.
6
7The secondary purpose is to provide support for Haskell development environments
8including prebuilt Haskell libraries. However, in this area sacrifices have been
9made due to self-imposed restrictions in Nixpkgs, to lessen the maintenance
10effort and to improve performance. (More details in the subsection
11[Limitations.](#haskell-limitations))
12
13## Available packages {#haskell-available-packages}
14
15The compiler and most build tools are exposed at the top level:
16
17* `ghc` is the default version of GHC
18* Language specific tools: `cabal-install`, `stack`, `hpack`, …
19
20Many “normal” user facing packages written in Haskell, like `niv` or `cachix`,
21are also exposed at the top level, and there is nothing Haskell specific to
22installing and using them.
23
24All of these packages are originally defined in the `haskellPackages` package
25set and are re-exposed with a reduced dependency closure for convenience.
26(see `justStaticExecutables` below)
27
28The `haskellPackages` set includes at least one version of every package from
29Hackage as well as some manually injected packages. This amounts to a lot of
30packages, so it is hidden from `nix-env -qa` by default for performance reasons.
31You can still list all packages in the set like this:
32
33```console
34$ nix-env -f '<nixpkgs>' -qaP -A haskellPackages
35haskellPackages.a50 a50-0.5
36haskellPackages.AAI AAI-0.2.0.1
37haskellPackages.aasam aasam-0.2.0.0
38haskellPackages.abacate abacate-0.0.0.0
39haskellPackages.abc-puzzle abc-puzzle-0.2.1
40…
41```
42Also, the `haskellPackages` set is included on [search.nixos.org].
43
44The attribute names in `haskellPackages` always correspond with their name on
45Hackage. Since Hackage allows names that are not valid Nix without escaping,
46you need to take care when handling attribute names like `3dmodels`.
47
48For packages that are part of [Stackage], we use the version prescribed by a
49Stackage solver (usually the current LTS one) as the default version. For all
50other packages we use the latest version from Hackage. See
51[below](#haskell-available-versions) to learn which versions are provided
52exactly.
53
54Roughly half of the 16K packages contained in `haskellPackages` don't actually
55build and are marked as broken semi-automatically. Most of those packages are
56deprecated or unmaintained, but sometimes packages that should build, do not
57build. Very often fixing them is not a lot of work.
58
59<!--
60TODO(@sternenseemann):
61How you can help with that is
62described in [Fixing a broken package](#haskell-fixing-a-broken-package).
63-->
64
65`haskellPackages` is built with our default compiler, but we also provide other
66releases of GHC and package sets built with them. You can list all available
67compilers like this:
68
69```console
70$ nix-env -f '<nixpkgs>' -qaP -A haskell.compiler
71haskell.compiler.ghc810 ghc-8.10.7
72haskell.compiler.ghc88 ghc-8.8.4
73haskell.compiler.ghc90 ghc-9.0.2
74haskell.compiler.ghc924 ghc-9.2.4
75haskell.compiler.ghc925 ghc-9.2.5
76haskell.compiler.ghc926 ghc-9.2.6
77haskell.compiler.ghc92 ghc-9.2.7
78haskell.compiler.ghc942 ghc-9.4.2
79haskell.compiler.ghc943 ghc-9.4.3
80haskell.compiler.ghc94 ghc-9.4.4
81haskell.compiler.ghcHEAD ghc-9.7.20221224
82haskell.compiler.ghc8102Binary ghc-binary-8.10.2
83haskell.compiler.ghc8102BinaryMinimal ghc-binary-8.10.2
84haskell.compiler.ghc8107BinaryMinimal ghc-binary-8.10.7
85haskell.compiler.ghc8107Binary ghc-binary-8.10.7
86haskell.compiler.ghc865Binary ghc-binary-8.6.5
87haskell.compiler.ghc924Binary ghc-binary-9.2.4
88haskell.compiler.ghc924BinaryMinimal ghc-binary-9.2.4
89haskell.compiler.integer-simple.ghc810 ghc-integer-simple-8.10.7
90haskell.compiler.integer-simple.ghc8107 ghc-integer-simple-8.10.7
91haskell.compiler.integer-simple.ghc88 ghc-integer-simple-8.8.4
92haskell.compiler.integer-simple.ghc884 ghc-integer-simple-8.8.4
93haskell.compiler.native-bignum.ghc90 ghc-native-bignum-9.0.2
94haskell.compiler.native-bignum.ghc902 ghc-native-bignum-9.0.2
95haskell.compiler.native-bignum.ghc924 ghc-native-bignum-9.2.4
96haskell.compiler.native-bignum.ghc925 ghc-native-bignum-9.2.5
97haskell.compiler.native-bignum.ghc926 ghc-native-bignum-9.2.6
98haskell.compiler.native-bignum.ghc92 ghc-native-bignum-9.2.7
99haskell.compiler.native-bignum.ghc927 ghc-native-bignum-9.2.7
100haskell.compiler.native-bignum.ghc942 ghc-native-bignum-9.4.2
101haskell.compiler.native-bignum.ghc943 ghc-native-bignum-9.4.3
102haskell.compiler.native-bignum.ghc94 ghc-native-bignum-9.4.4
103haskell.compiler.native-bignum.ghc944 ghc-native-bignum-9.4.4
104haskell.compiler.native-bignum.ghcHEAD ghc-native-bignum-9.7.20221224
105haskell.compiler.ghcjs ghcjs-8.10.7
106```
107
108Each of those compiler versions has a corresponding attribute set built using
109it. However, the non-standard package sets are not tested regularly and, as a
110result, contain fewer working packages. The corresponding package set for GHC
1119.4.5 is `haskell.packages.ghc945`. In fact `haskellPackages` is just an alias
112for `haskell.packages.ghc927`:
113
114```console
115$ nix-env -f '<nixpkgs>' -qaP -A haskell.packages.ghc927
116haskell.packages.ghc927.a50 a50-0.5
117haskell.packages.ghc927.AAI AAI-0.2.0.1
118haskell.packages.ghc927.aasam aasam-0.2.0.0
119haskell.packages.ghc927.abacate abacate-0.0.0.0
120haskell.packages.ghc927.abc-puzzle abc-puzzle-0.2.1
121…
122```
123
124Every package set also re-exposes the GHC used to build its packages as `haskell.packages.*.ghc`.
125
126### Available package versions {#haskell-available-versions}
127
128We aim for a “blessed” package set which only contains one version of each
129package, like Stackage (and based on it) but with more packages. Normally in
130nixpkgs the number of building Haskell packages is roughly two to three times
131the size of Stackage. For choosing the version to use for a certain package we
132use the following rules:
133
1341. By default, for every package `haskellPackages.foo` is the newest version
135found on Hackage (at the time of the last update of our package set).
1362. If the Stackage snapshot that we use (usually the newest LTS snapshot)
137contains a package, we use the Stackage version as default version for that
138package.
1393. For some packages, which are not on Stackage, we have manual overrides to
140set the default version to a version older than the newest on Hackage. We do
141this to get them or their reverse dependencies to compile in our package set.
1424. For all packages, for which the newest Hackage version is not the default
143version, there will also be a `haskellPackages.foo_x_y_z` package with the
144newest version. The `x_y_z` part encodes the version with dots replaced by
145underscores. When the newest version changes by a new release to Hackage the
146old package will disappear under that name and be replaced by a newer one under
147the name with the new version. The package name including the version will
148also disappear when the default version e.g. from Stackage catches up with the
149newest version from Hackage.
1505. For some packages, we also manually add other `haskellPackages.foo_x_y_z`
151versions, if they are required for a certain build.
152
153Relying on `haskellPackages.foo_x_y_z` attributes in derivations outside
154nixpkgs is discouraged because they may change or disappear with every package
155set update.
156<!-- TODO(@maralorn) We should add a link to callHackage, etc. once we added
157them to the docs. -->
158
159All `haskell.packages.*` package sets use the same package descriptions and the same sets
160of versions by default. There are however GHC version specific override `.nix`
161files to loosen this a bit.
162
163### Dependency resolution {#haskell-dependency-resolution}
164
165Normally when you build Haskell packages with `cabal-install`, `cabal-install`
166does dependency resolution. It will look at all Haskell package versions known
167on Hackage and tries to pick for every (transitive) dependency of your build
168exactly one version. Those versions need to satisfy all the version constraints
169given in the `.cabal` file of your package and all its dependencies.
170
171The [Haskell builder in nixpkgs](#haskell-mkderivation) does no such thing.
172It will simply take as input packages with names off the desired dependencies
173and just check whether they fulfill the version bounds and fail if they don’t
174(by default, see `jailbreak` to circumvent this).
175
176The `haskellPackages.callPackage` function does the package resolution.
177It will, e.g., use `haskellPackages.aeson`which has the default version as
178described above for a package input of name `aeson`. (More general:
179`<packages>.callPackage f` will call `f` with named inputs provided from the
180package set `<packages>`.)
181While this is the default behavior, it is possible to override the dependencies
182for a specific package, see
183[`override` and `overrideScope`](#haskell-overriding-haskell-packages).
184
185### Limitations {#haskell-limitations}
186
187Our main objective with `haskellPackages` is to package Haskell software in
188nixpkgs. This entails some limitations, partially due to self-imposed
189restrictions of nixpkgs, partially in the name of maintainability:
190
191* Only the packages built with the default compiler see extensive testing of the
192 whole package set. For other GHC versions only a few essential packages are
193 tested and cached.
194* As described above we only build one version of most packages.
195
196The experience using an older or newer packaged compiler or using different
197versions may be worse, because builds will not be cached on `cache.nixos.org`
198or may fail.
199
200Thus, to get the best experience, make sure that your project can be compiled
201using the default compiler of nixpkgs and recent versions of its dependencies.
202
203A result of this setup is, that getting a valid build plan for a given
204package can sometimes be quite painful, and in fact this is where most of the
205maintenance work for `haskellPackages` is required. Besides that, it is not
206possible to get the dependencies of a legacy project from nixpkgs or to use a
207specific stack solver for compiling a project.
208
209Even though we couldn’t use them directly in nixpkgs, it would be desirable
210to have tooling to generate working Nix package sets from build plans generated
211by `cabal-install` or a specific Stackage snapshot via import-from-derivation.
212Sadly we currently don’t have tooling for this. For this you might be
213interested in the alternative [haskell.nix] framework, which, be warned, is
214completely incompatible with packages from `haskellPackages`.
215
216<!-- TODO(@maralorn) Link to package set generation docs in the contributers guide below. -->
217
218## `haskellPackages.mkDerivation` {#haskell-mkderivation}
219
220Every haskell package set has its own haskell-aware `mkDerivation` which is used
221to build its packages. Generally you won't have to interact with this builder
222since [cabal2nix][cabal2nix] can generate packages
223using it for an arbitrary cabal package definition. Still it is useful to know
224the parameters it takes when you need to
225[override](#haskell-overriding-haskell-packages) a generated Nix expression.
226
227`haskellPackages.mkDerivation` is a wrapper around `stdenv.mkDerivation` which
228re-defines the default phases to be haskell aware and handles dependency
229specification, test suites, benchmarks etc. by compiling and invoking the
230package's `Setup.hs`. It does *not* use or invoke the `cabal-install` binary,
231but uses the underlying `Cabal` library instead.
232
233### General arguments {#haskell-derivation-args}
234
235`pname`
236: Package name, assumed to be the same as on Hackage (if applicable)
237
238`version`
239: Packaged version, assumed to be the same as on Hackage (if applicable)
240
241`src`
242: Source of the package. If omitted, fetch package corresponding to `pname`
243and `version` from Hackage.
244
245`sha256`
246: Hash to use for the default case of `src`.
247
248`revision`
249: Revision number of the updated cabal file to fetch from Hackage.
250If `null` (which is the default value), the one included in `src` is used.
251
252`editedCabalFile`
253: `sha256` hash of the cabal file identified by `revision` or `null`.
254
255`configureFlags`
256: Extra flags passed when executing the `configure` command of `Setup.hs`.
257
258`buildFlags`
259: Extra flags passed when executing the `build` command of `Setup.hs`.
260
261`haddockFlags`
262: Extra flags passed to `Setup.hs haddock` when building the documentation.
263
264`doCheck`
265: Whether to execute the package's test suite if it has one. Defaults to `true` unless cross-compiling.
266
267`doBenchmark`
268: Whether to execute the package's benchmark if it has one. Defaults to `false`.
269
270`doHoogle`
271: Whether to generate an index file for [hoogle][hoogle] as part of
272`haddockPhase` by passing the [`--hoogle` option][haddock-hoogle-option].
273Defaults to `true`.
274
275`doHaddockQuickjump`
276: Whether to generate an index for interactive navigation of the HTML documentation.
277Defaults to `true` if supported.
278
279`enableLibraryProfiling`
280: Whether to enable [profiling][profiling] for libraries contained in the
281package. Enabled by default if supported.
282
283`enableExecutableProfiling`
284: Whether to enable [profiling][profiling] for executables contained in the
285package. Disabled by default.
286
287`profilingDetail`
288: [Profiling detail level][profiling-detail] to set. Defaults to `exported-functions`.
289
290`enableSharedExecutables`
291: Whether to link executables dynamically. By default, executables are linked statically.
292
293`enableSharedLibraries`
294: Whether to build shared Haskell libraries. This is enabled by default unless we are using
295`pkgsStatic` or shared libraries have been disabled in GHC.
296
297`enableStaticLibraries`
298: Whether to build static libraries. Enabled by default if supported.
299
300`enableDeadCodeElimination`
301: Whether to enable linker based dead code elimination in GHC.
302Enabled by default if supported.
303
304`enableHsc2hsViaAsm`
305: Whether to pass `--via-asm` to `hsc2hs`. Enabled by default only on Windows.
306
307`hyperlinkSource`
308: Whether to render the source as well as part of the haddock documentation
309by passing the [`--hyperlinked-source` flag][haddock-hyperlinked-source-option].
310Defaults to `true`.
311
312`isExecutable`
313: Whether the package contains an executable.
314
315`isLibrary`
316: Whether the package contains a library.
317
318`jailbreak`
319: Whether to execute [jailbreak-cabal][jailbreak-cabal] before `configurePhase`
320to lift any version constraints in the cabal file. Note that this can't
321lift version bounds if they are conditional, i.e. if a dependency is hidden
322behind a flag.
323
324`enableParallelBuilding`
325: Whether to use the `-j` flag to make GHC/Cabal start multiple jobs in parallel.
326
327`maxBuildCores`
328: Upper limit of jobs to use in parallel for compilation regardless of
329`$NIX_BUILD_CORES`. Defaults to 16 as Haskell compilation with GHC currently
330sees a [performance regression](https://gitlab.haskell.org/ghc/ghc/-/issues/9221)
331if too many parallel jobs are used.
332
333`doCoverage`
334: Whether to generate and install files needed for [HPC][haskell-program-coverage].
335Defaults to `false`.
336
337`doHaddock`
338: Whether to build (HTML) documentation using [haddock][haddock].
339Defaults to `true` if supported.
340
341`testTarget`
342: Name of the test suite to build and run. If unset, all test suites will be executed.
343
344`preCompileBuildDriver`
345: Shell code to run before compiling `Setup.hs`.
346
347`postCompileBuildDriver`
348: Shell code to run after compiling `Setup.hs`.
349
350`preHaddock`
351: Shell code to run before building documentation using haddock.
352
353`postHaddock`
354: Shell code to run after building documentation using haddock.
355
356`coreSetup`
357: Whether to only allow core libraries to be used while building `Setup.hs`.
358Defaults to `false`.
359
360`useCpphs`
361: Whether to enable the [cpphs][cpphs] preprocessor. Defaults to `false`.
362
363`enableSeparateBinOutput`
364: Whether to install executables to a separate `bin` output. Defaults to `false`.
365
366`enableSeparateDataOutput`
367: Whether to install data files shipped with the package to a separate `data` output.
368Defaults to `false`.
369
370`enableSeparateDocOutput`
371: Whether to install documentation to a separate `doc` output.
372Is automatically enabled if `doHaddock` is `true`.
373
374`allowInconsistentDependencies`
375: If enabled, allow multiple versions of the same Haskell package in the
376dependency tree at configure time. Often in such a situation compilation would
377later fail because of type mismatches. Defaults to `false`.
378
379`enableLibraryForGhci`
380: Build and install a special object file for GHCi. This improves performance
381when loading the library in the REPL, but requires extra build time and
382disk space. Defaults to `false`.
383
384`buildTarget`
385: Name of the executable or library to build and install.
386If unset, all available targets are built and installed.
387
388### Specifying dependencies {#haskell-derivation-deps}
389
390Since `haskellPackages.mkDerivation` is intended to be generated from cabal
391files, it reflects cabal's way of specifying dependencies. For one, dependencies
392are grouped by what part of the package they belong to. This helps to reduce the
393dependency closure of a derivation, for example benchmark dependencies are not
394included if `doBenchmark == false`.
395
396`setup*Depends`
397: dependencies necessary to compile `Setup.hs`
398
399`library*Depends`
400: dependencies of a library contained in the package
401
402`executable*Depends`
403: dependencies of an executable contained in the package
404
405`test*Depends`
406: dependencies of a test suite contained in the package
407
408`benchmark*Depends`
409: dependencies of a benchmark contained in the package
410
411The other categorization relates to the way the package depends on the dependency:
412
413`*ToolDepends`
414: Tools we need to run as part of the build process.
415They are added to the derivation's `nativeBuildInputs`.
416
417`*HaskellDepends`
418: Haskell libraries the package depends on.
419They are added to `propagatedBuildInputs`.
420
421`*SystemDepends`
422: Non-Haskell libraries the package depends on.
423They are added to `buildInputs`
424
425`*PkgconfigDepends`
426: `*SystemDepends` which are discovered using `pkg-config`.
427They are added to `buildInputs` and it is additionally
428ensured that `pkg-config` is available at build time.
429
430`*FrameworkDepends`
431: Apple SDK Framework which the package depends on when compiling it on Darwin.
432
433Using these two distinctions, you should be able to categorize most of the dependency
434specifications that are available:
435`benchmarkFrameworkDepends`,
436`benchmarkHaskellDepends`,
437`benchmarkPkgconfigDepends`,
438`benchmarkSystemDepends`,
439`benchmarkToolDepends`,
440`executableFrameworkDepends`,
441`executableHaskellDepends`,
442`executablePkgconfigDepends`,
443`executableSystemDepends`,
444`executableToolDepends`,
445`libraryFrameworkDepends`,
446`libraryHaskellDepends`,
447`libraryPkgconfigDepends`,
448`librarySystemDepends`,
449`libraryToolDepends`,
450`setupHaskellDepends`,
451`testFrameworkDepends`,
452`testHaskellDepends`,
453`testPkgconfigDepends`,
454`testSystemDepends` and
455`testToolDepends`.
456
457That only leaves the following extra ways for specifying dependencies:
458
459`buildDepends`
460: Allows specifying Haskell dependencies which are added to `propagatedBuildInputs` unconditionally.
461
462`buildTools`
463: Like `*ToolDepends`, but are added to `nativeBuildInputs` unconditionally.
464
465`extraLibraries`
466: Like `*SystemDepends`, but are added to `buildInputs` unconditionally.
467
468`pkg-configDepends`
469: Like `*PkgconfigDepends`, but are added to `buildInputs` unconditionally.
470
471`testDepends`
472: Deprecated, use either `testHaskellDepends` or `testSystemDepends`.
473
474`benchmarkDepends`
475: Deprecated, use either `benchmarkHaskellDepends` or `benchmarkSystemDepends`.
476
477The dependency specification methods in this list which are unconditional
478are especially useful when writing [overrides](#haskell-overriding-haskell-packages)
479when you want to make sure that they are definitely included. However, it is
480recommended to use the more accurate ones listed above when possible.
481
482### Meta attributes {#haskell-derivation-meta}
483
484`haskellPackages.mkDerivation` accepts the following attributes as direct
485arguments which are transparently set in `meta` of the resulting derivation. See
486the [Meta-attributes section](#chap-meta) for their documentation.
487
488* These attributes are populated with a default value if omitted:
489 * `homepage`: defaults to the Hackage page for `pname`.
490 * `platforms`: defaults to `lib.platforms.all` (since GHC can cross-compile)
491* These attributes are only set if given:
492 * `description`
493 * `license`
494 * `changelog`
495 * `maintainers`
496 * `broken`
497 * `hydraPlatforms`
498
499## Development environments {#haskell-development-environments}
500
501In addition to building and installing Haskell software, nixpkgs can also
502provide development environments for Haskell projects. This has the obvious
503advantage that you benefit from `cache.nixos.org` and no longer need to compile
504all project dependencies yourself. While it is often very useful, this is not
505the primary use case of our package set. Have a look at the section
506[available package versions](#haskell-available-versions) to learn which
507versions of packages we provide and the section
508[limitations](#haskell-limitations), to judge whether a `haskellPackages`
509based development environment for your project is feasible.
510
511By default, every derivation built using
512[`haskellPackages.mkDerivation`](#haskell-mkderivation) exposes an environment
513suitable for building it interactively as the `env` attribute. For example, if
514you have a local checkout of `random`, you can enter a development environment
515for it like this (if the dependencies in the development and packaged version
516match):
517
518```console
519$ cd ~/src/random
520$ nix-shell -A haskellPackages.random.env '<nixpkgs>'
521[nix-shell:~/src/random]$ ghc-pkg list
522/nix/store/a8hhl54xlzfizrhcf03c1l3f6l9l8qwv-ghc-9.2.4-with-packages/lib/ghc-9.2.4/package.conf.d
523 Cabal-3.6.3.0
524 array-0.5.4.0
525 base-4.16.3.0
526 binary-0.8.9.0
527 …
528 ghc-9.2.4
529 …
530```
531
532As you can see, the environment contains a GHC which is set up so it finds all
533dependencies of `random`. Note that this environment does not mirror
534the environment used to build the package, but is intended as a convenient
535tool for development and simple debugging. `env` relies on the `ghcWithPackages`
536wrapper which automatically injects a pre-populated package-db into every
537GHC invocation. In contrast, using `nix-shell -A haskellPackages.random` will
538not result in an environment in which the dependencies are in GHCs package
539database. Instead, the Haskell builder will pass in all dependencies explicitly
540via configure flags.
541
542`env` mirrors the normal derivation environment in one aspect: It does not include
543familiar development tools like `cabal-install`, since we rely on plain `Setup.hs`
544to build all packages. However, `cabal-install` will work as expected if in
545`PATH` (e.g. when installed globally and using a `nix-shell` without `--pure`).
546A declarative and pure way of adding arbitrary development tools is provided
547via [`shellFor`](#haskell-shellFor).
548
549When using `cabal-install` for dependency resolution you need to be a bit
550careful to achieve build purity. `cabal-install` will find and use all
551dependencies installed from the packages `env` via Nix, but it will also
552consult Hackage to potentially download and compile dependencies if it can’t
553find a valid build plan locally. To prevent this you can either never run
554`cabal update`, remove the cabal database from your `~/.cabal` folder or run
555`cabal` with `--offline`. Note though, that for some usecases `cabal2nix` needs
556the local Hackage db.
557
558Often you won't work on a package that is already part of `haskellPackages` or
559Hackage, so we first need to write a Nix expression to obtain the development
560environment from. Luckily, we can generate one very easily from an already
561existing cabal file using `cabal2nix`:
562
563```console
564$ ls
565my-project.cabal src …
566$ cabal2nix ./. > my-project.nix
567```
568
569The generated Nix expression evaluates to a function ready to be
570`callPackage`-ed. For now, we can add a minimal `default.nix` which does just
571that:
572
573```nix
574# Retrieve nixpkgs impurely from NIX_PATH for now, you can pin it instead, of course.
575{ pkgs ? import <nixpkgs> {} }:
576
577# use the nixpkgs default haskell package set
578pkgs.haskellPackages.callPackage ./my-project.nix { }
579```
580
581Using `nix-build default.nix` we can now build our project, but we can also
582enter a shell with all the package's dependencies available using `nix-shell
583-A env default.nix`. If you have `cabal-install` installed globally, it'll work
584inside the shell as expected.
585
586### shellFor {#haskell-shellFor}
587
588Having to install tools globally is obviously not great, especially if you want
589to provide a batteries-included `shell.nix` with your project. Luckily there's a
590proper tool for making development environments out of packages' build
591environments: `shellFor`, a function exposed by every haskell package set. It
592takes the following arguments and returns a derivation which is suitable as a
593development environment inside `nix-shell`:
594
595`packages`
596: This argument is used to select the packages for which to build the
597development environment. This should be a function which takes a haskell package
598set and returns a list of packages. `shellFor` will pass the used package set to
599this function and include all dependencies of the returned package in the build
600environment. This means you can reuse Nix expressions of packages included in
601nixpkgs, but also use local Nix expressions like this: `hpkgs: [
602(hpkgs.callPackage ./my-project.nix { }) ]`.
603
604`nativeBuildInputs`
605: Expects a list of derivations to add as build tools to the build environment.
606This is the place to add packages like `cabal-install`, `doctest` or `hlint`.
607Defaults to `[]`.
608
609`buildInputs`
610: Expects a list of derivations to add as library dependencies, like `openssl`.
611This is rarely necessary as the haskell package expressions usually track system
612dependencies as well. Defaults to `[]`. (see also
613[derivation dependencies](#haskell-derivation-deps))
614
615`withHoogle`
616: If this is true, `hoogle` will be added to `nativeBuildInputs`.
617Additionally, its database will be populated with all included dependencies,
618so you'll be able search through the documentation of your dependencies.
619Defaults to `false`.
620
621`genericBuilderArgsModifier`
622: This argument accepts a function allowing you to modify the arguments passed
623to `mkDerivation` in order to create the development environment. For example,
624`args: { doCheck = false; }` would cause the environment to not include any test
625dependencies. Defaults to `lib.id`.
626
627`doBenchmark`
628: This is a shortcut for enabling `doBenchmark` via `genericBuilderArgsModifier`.
629Setting it to `true` will cause the development environment to include all
630benchmark dependencies which would be excluded by default. Defaults to `false`.
631
632One neat property of `shellFor` is that it allows you to work on multiple
633packages using the same environment in conjunction with
634[cabal.project files][cabal-project-files].
635Say our example above depends on `distribution-nixpkgs` and we have a project
636file set up for both, we can add the following `shell.nix` expression:
637
638```nix
639{ pkgs ? import <nixpkgs> {} }:
640
641pkgs.haskellPackages.shellFor {
642 packages = hpkgs: [
643 # reuse the nixpkgs for this package
644 hpkgs.distribution-nixpkgs
645 # call our generated Nix expression manually
646 (hpkgs.callPackage ./my-project/my-project.nix { })
647 ];
648
649 # development tools we use
650 nativeBuildInputs = [
651 pkgs.cabal-install
652 pkgs.haskellPackages.doctest
653 pkgs.cabal2nix
654 ];
655
656 # Extra arguments are added to mkDerivation's arguments as-is.
657 # Since it adds all passed arguments to the shell environment,
658 # we can use this to set the environment variable the `Paths_`
659 # module of distribution-nixpkgs uses to search for bundled
660 # files.
661 # See also: https://cabal.readthedocs.io/en/latest/cabal-package.html#accessing-data-files-from-package-code
662 distribution_nixpkgs_datadir = toString ./distribution-nixpkgs;
663}
664```
665
666<!-- TODO(@sternenseemann): deps are not included if not selected -->
667
668### haskell-language-server {#haskell-language-server}
669
670To use HLS in short: Install `pkgs.haskell-language-server` e.g. in
671`nativeBuildInputs` in `shellFor` and use the `haskell-language-server-wrapper`
672command to run it. See the [HLS user guide] on how to configure your text
673editor to use HLS and how to test your setup.
674
675HLS needs to be compiled with the GHC version of the project you use it
676on.
677
678``pkgs.haskell-language-server`` provides
679``haskell-language-server-wrapper``, ``haskell-language-server``
680and ``haskell-language-server-x.x.x``
681binaries, where ``x.x.x`` is the GHC version for which it is compiled. By
682default, it only includes binaries for the current GHC version, to reduce
683closure size. The closure size is large, because HLS needs to be dynamically
684linked to work reliably. You can override the list of supported GHC versions
685with e.g.
686
687```nix
688pkgs.haskell-language-server.override { supportedGhcVersions = [ "90" "94" ]; }
689```
690Where all strings `version` are allowed such that
691`haskell.packages.ghc${version}` is an existing package set.
692
693When you run `haskell-language-server-wrapper` it will detect the GHC
694version used by the project you are working on (by asking e.g. cabal or
695stack) and pick the appropriate versioned binary from your path.
696
697Be careful when installing HLS globally and using a pinned nixpkgs for a
698Haskell project in a `nix-shell`. If the nixpkgs versions deviate to much
699(e.g., use different `glibc` versions) the `haskell-language-server-?.?.?`
700executable will try to detect these situations and refuse to start. It is
701recommended to obtain HLS via `nix-shell` from the nixpkgs version pinned in
702there instead.
703
704The top level `pkgs.haskell-language-server` attribute is just a convenience
705wrapper to make it possible to install HLS for multiple GHC versions at the
706same time. If you know, that you only use one GHC version, e.g., in a project
707specific `nix-shell` you can simply use
708`pkgs.haskellPackages.haskell-language-server` or
709`pkgs.haskell.packages.*.haskell-language-server` from the package set you use.
710
711If you use `nix-shell` for your development environments remember to start your
712editor in that environment. You may want to use something like `direnv` and/or an
713editor plugin to achieve this.
714
715## Overriding Haskell packages {#haskell-overriding-haskell-packages}
716
717### Overriding a single package {#haskell-overriding-a-single-package}
718
719<!-- TODO(@sternenseemann): we should document /somewhere/ that base == null etc. -->
720
721Like many language specific subsystems in nixpkgs, the Haskell infrastructure
722also has its own quirks when it comes to overriding. Overriding of the *inputs*
723to a package at least follows the standard procedure. For example, imagine you
724need to build `nix-tree` with a more recent version of `brick` than the default
725one provided by `haskellPackages`:
726
727```nix
728haskellPackages.nix-tree.override {
729 brick = haskellPackages.brick_0_67;
730}
731```
732
733<!-- TODO(@sternenseemann): This belongs in the next section
734One common problem you may run into with such an override is the build failing
735with “abort because of serious configure-time warning from Cabal”. When scrolling
736up, you'll usually notice that Cabal noticed that more than one versions of the same
737package was present in the dependency graph. This typically causes a later compilation
738failure (the error message `haskellPackages.mkDerivation` produces tries to save
739you the time of finding this out yourself, but if you wish to do so, you can
740disable it using `allowInconsistentDependencies`). Luckily, `haskellPackages` provides
741you with a tool to deal with this. `overrideScope` creates a new `haskellPackages`
742instance with the override applied *globally* for this package, so the dependency
743closure automatically uses a consistent version of the overridden package. E. g.
744if `haskell-ci` needs a recent version of `Cabal`, but also uses other packages
745that depend on that library, you may want to use:
746
747```nix
748haskellPackages.haskell-ci.overrideScope (self: super: {
749 Cabal = self.Cabal_3_6_2_0;
750})
751```
752
753-->
754
755The custom interface comes into play when you want to override the arguments
756passed to `haskellPackages.mkDerivation`. For this, the function `overrideCabal`
757from `haskell.lib.compose` is used. E.g., if you want to install a man page
758that is distributed with the package, you can do something like this:
759
760```nix
761haskell.lib.compose.overrideCabal (drv: {
762 postInstall = ''
763 ${drv.postInstall or ""}
764 install -Dm644 man/pnbackup.1 -t $out/share/man/man1
765 '';
766}) haskellPackages.pnbackup
767```
768
769`overrideCabal` takes two arguments:
770
7711. A function which receives all arguments passed to `haskellPackages.mkDerivation`
772 before and returns a set of arguments to replace (or add) with a new value.
7732. The Haskell derivation to override.
774
775The arguments are ordered so that you can easily create helper functions by making
776use of currying:
777
778```nix
779let
780 installManPage = haskell.lib.compose.overrideCabal (drv: {
781 postInstall = ''
782 ${drv.postInstall or ""}
783 install -Dm644 man/${drv.pname}.1 -t "$out/share/man/man1"
784 '';
785 });
786in
787
788installManPage haskellPackages.pnbackup
789```
790
791In fact, `haskell.lib.compose` already provides lots of useful helpers for common
792tasks, detailed in the next section. They are also structured in such a way that
793they can be combined using `lib.pipe`:
794
795```nix
796lib.pipe my-haskell-package [
797 # lift version bounds on dependencies
798 haskell.lib.compose.doJailbreak
799 # disable building the haddock documentation
800 haskell.lib.compose.dontHaddock
801 # pass extra package flag to Cabal's configure step
802 (haskell.lib.compose.enableCabalFlag "myflag")
803]
804```
805
806#### `haskell.lib.compose` {#haskell-haskell.lib.compose}
807
808The base interface for all overriding is the following function:
809
810`overrideCabal f drv`
811: Takes the arguments passed to obtain `drv` to `f` and uses the resulting
812attribute set to update the argument set. Then a recomputed version of `drv`
813using the new argument set is returned.
814
815<!--
816TODO(@sternenseemann): ideally we want to be more detailed here as well, but
817I want to avoid the documentation having to be kept in sync in too many places.
818We already document this stuff in the mkDerivation section and lib/compose.nix.
819Ideally this section would be generated from the latter in the future.
820-->
821
822All other helper functions are implemented in terms of `overrideCabal` and make
823common overrides shorter and more complicate ones trivial. The simple overrides
824which only change a single argument are only described very briefly in the
825following overview. Refer to the
826[documentation of `haskellPackages.mkDerivation`](#haskell-mkderivation)
827for a more detailed description of the effects of the respective arguments.
828
829##### Packaging Helpers {#haskell-packaging-helpers}
830
831`overrideSrc { src, version } drv`
832: Replace the source used for building `drv` with the path or derivation given
833as `src`. The `version` attribute is optional. Prefer this function over
834overriding `src` via `overrideCabal`, since it also automatically takes care of
835removing any Hackage revisions.
836
837<!-- TODO(@sternenseemann): deprecated
838
839`generateOptparseApplicativeCompletions list drv`
840: Generate and install shell completion files for the installed executables whose
841names are given via `list`. The executables need to be using `optparse-applicative`
842for this to work.
843-->
844
845`justStaticExecutables drv`
846: Only build and install the executables produced by `drv`, removing everything
847that may refer to other Haskell packages' store paths (like libraries and
848documentation). This dramatically reduces the closure size of the resulting
849derivation. Note that the executables are only statically linked against their
850Haskell dependencies, but will still link dynamically against libc, GMP and
851other system library dependencies. If dependencies use their Cabal-generated
852`Paths_*` module, this may not work as well if GHC's dead code elimination
853is unable to remove the references to the dependency's store path that module
854contains.
855
856`enableSeparateBinOutput drv`
857: Install executables produced by `drv` to a separate `bin` output. This
858has a similar effect as `justStaticExecutables`, but preserves the libraries
859and documentation in the `out` output alongside the `bin` output with a
860much smaller closure size.
861
862`markBroken drv`
863: Sets the `broken` flag to `true` for `drv`.
864
865`markUnbroken drv`, `unmarkBroken drv`
866: Set the `broken` flag to `false` for `drv`.
867
868`doDistribute drv`
869: Updates `hydraPlatforms` so that Hydra will build `drv`. This is
870sometimes necessary when working with versioned packages in
871`haskellPackages` which are not built by default.
872
873`dontDistribute drv`
874: Sets `hydraPlatforms` to `[]`, causing Hydra to skip this package
875altogether. Useful if it fails to evaluate cleanly and is causing
876noise in the evaluation errors tab on Hydra.
877
878##### Development Helpers {#haskell-development-helpers}
879
880`sdistTarball drv`
881: Create a source distribution tarball like those found on Hackage
882instead of building the package `drv`.
883
884`documentationTarball drv`
885: Create a documentation tarball suitable for uploading to Hackage
886instead of building the package `drv`.
887
888`buildFromSdist drv`
889: Uses `sdistTarball drv` as the source to compile `drv`. This helps to catch
890packaging bugs when building from a local directory, e.g. when required files
891are missing from `extra-source-files`.
892
893`failOnAllWarnings drv`
894: Enables all warnings GHC supports and makes it fail the build if any of them
895are emitted.
896
897<!-- TODO(@sternenseemann):
898`checkUnusedPackages opts drv`
899: Adds an extra check to `postBuild` which fails the build if any dependency
900taken as an input is not used. The `opts` attribute set allows relaxing this
901check.
902-->
903
904`enableDWARFDebugging drv`
905: Compiles the package with additional debug symbols enabled, useful
906for debugging with e.g. `gdb`.
907
908`doStrip drv`
909: Sets `doStrip` to `true` for `drv`.
910
911`dontStrip drv`
912: Sets `doStrip` to `false` for `drv`.
913
914<!-- TODO(@sternenseemann): shellAware -->
915
916##### Trivial Helpers {#haskell-trivial-helpers}
917
918`doJailbreak drv`
919: Sets the `jailbreak` argument to `true` for `drv`.
920
921`dontJailbreak drv`
922: Sets the `jailbreak` argument to `false` for `drv`.
923
924`doHaddock drv`
925: Sets `doHaddock` to `true` for `drv`.
926
927`dontHaddock drv`
928: Sets `doHaddock` to `false` for `drv`. Useful if the build of a package is
929failing because of e.g. a syntax error in the Haddock documentation.
930
931`doHyperlinkSource drv`
932: Sets `hyperlinkSource` to `true` for `drv`.
933
934`dontHyperlinkSource drv`
935: Sets `hyperlinkSource` to `false` for `drv`.
936
937`doCheck drv`
938: Sets `doCheck` to `true` for `drv`.
939
940`dontCheck drv`
941: Sets `doCheck` to `false` for `drv`. Useful if a package has a broken,
942flaky or otherwise problematic test suite breaking the build.
943
944<!-- Purposefully omitting the non-list variants here. They are a bit
945ugly, and we may want to deprecate them at some point. -->
946
947`appendConfigureFlags list drv`
948: Adds the strings in `list` to the `configureFlags` argument for `drv`.
949
950`enableCabalFlag flag drv`
951: Makes sure that the Cabal flag `flag` is enabled in Cabal's configure step.
952
953`disableCabalFlag flag drv`
954: Makes sure that the Cabal flag `flag` is disabled in Cabal's configure step.
955
956`appendBuildflags list drv`
957: Adds the strings in `list` to the `buildFlags` argument for `drv`.
958
959<!-- TODO(@sternenseemann): removeConfigureFlag -->
960
961`appendPatches list drv`
962: Adds the `list` of derivations or paths to the `patches` argument for `drv`.
963
964<!-- TODO(@sternenseemann): link dep section -->
965
966`addBuildTools list drv`
967: Adds the `list` of derivations to the `buildTools` argument for `drv`.
968
969`addExtraLibraries list drv`
970: Adds the `list` of derivations to the `extraLibraries` argument for `drv`.
971
972`addBuildDepends list drv`
973: Adds the `list` of derivations to the `buildDepends` argument for `drv`.
974
975`addTestToolDepends list drv`
976: Adds the `list` of derivations to the `testToolDepends` argument for `drv`.
977
978`addPkgconfigDepends list drv`
979: Adds the `list` of derivations to the `pkg-configDepends` argument for `drv`.
980
981`addSetupDepends list drv`
982: Adds the `list` of derivations to the `setupHaskellDepends` argument for `drv`.
983
984`doBenchmark drv`
985: Set `doBenchmark` to `true` for `drv`. Useful if your development
986environment is missing the dependencies necessary for compiling the
987benchmark component.
988
989`dontBenchmark drv`
990: Set `doBenchmark` to `false` for `drv`.
991
992`setBuildTargets list drv`
993: Sets the `buildTarget` argument for `drv` so that the targets specified in `list` are built.
994
995`doCoverage drv`
996: Sets the `doCoverage` argument to `true` for `drv`.
997
998`dontCoverage drv`
999: Sets the `doCoverage` argument to `false` for `drv`.
1000
1001#### Library functions in the Haskell package sets {#haskell-package-set-lib-functions}
1002
1003Some library functions depend on packages from the Haskell package sets. Thus they are
1004exposed from those instead of from `haskell.lib.compose` which can only access what is
1005passed directly to it. When using the functions below, make sure that you are obtaining them
1006from the same package set (`haskellPackages`, `haskell.packages.ghc944` etc.) as the packages
1007you are working with or – even better – from the `self`/`final` fix point of your overlay to
1008`haskellPackages`.
1009
1010Note: Some functions like `shellFor` that are not intended for overriding per se, are omitted
1011in this section. <!-- TODO(@sternenseemann): note about ifd section -->
1012
1013`cabalSdist { src, name ? ... }`
1014: Generates the Cabal sdist tarball for `src`, suitable for uploading to Hackage.
1015Contrary to `haskell.lib.compose.sdistTarball`, it uses `cabal-install` over `Setup.hs`,
1016so it is usually faster: No build dependencies need to be downloaded, and we can
1017skip compiling `Setup.hs`.
1018
1019`buildFromCabalSdist drv`
1020: Build `drv`, but run its `src` attribute through `cabalSdist` first. Useful for catching
1021files necessary for compilation that are missing from the sdist.
1022
1023`generateOptparseApplicativeCompletions list drv`
1024: Generate and install shell completion files for the installed executables whose
1025names are given via `list`. The executables need to be using `optparse-applicative`
1026for [this to work][optparse-applicative-completions].
1027Note that this feature is automatically disabled when cross-compiling, since it
1028requires executing the binaries in question.
1029
1030<!--
1031
1032TODO(@NixOS/haskell): finish these planned sections
1033### Overriding the entire package set
1034
1035
1036## Import-from-Derivation helpers
1037
1038* `callCabal2nix`
1039* `callHackage`, `callHackageDirect`
1040* `developPackage`
1041
1042## Contributing {#haskell-contributing}
1043
1044### Fixing a broken package {#haskell-fixing-a-broken-package}
1045
1046### Package set generation {#haskell-package-set-generation}
1047
1048### Packaging a Haskell project
1049
1050### Backporting {#haskell-backporting}
1051
1052Backporting changes to a stable NixOS version in general is covered
1053in nixpkgs' `CONTRIBUTING.md` in general. In particular refer to the
1054[backporting policy](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#criteria-for-backporting-changes)
1055to check if the change you have in mind may be backported.
1056
1057This section focuses on how to backport a package update (e.g. a
1058bug fix or security release). Fixing a broken package works like
1059it does for the unstable branches.
1060
1061-->
1062
1063## F.A.Q. {#haskell-faq}
1064
1065### Why is topic X not covered in this section? Why is section Y missing? {#haskell-why-not-covered}
1066
1067We have been working on [moving the nixpkgs Haskell documentation back into the
1068nixpkgs manual](https://github.com/NixOS/nixpkgs/issues/121403). Since this
1069process has not been completed yet, you may find some topics missing here
1070covered in the old [haskell4nix docs](https://haskell4nix.readthedocs.io/).
1071
1072If you feel any important topic is not documented at all, feel free to comment
1073on the issue linked above.
1074
1075[Stackage]: https://www.stackage.org
1076[cabal-project-files]: https://cabal.readthedocs.io/en/latest/cabal-project.html
1077[cabal2nix]: https://github.com/nixos/cabal2nix
1078[cpphs]: https://Hackage.haskell.org/package/cpphs
1079[haddock-hoogle-option]: https://haskell-haddock.readthedocs.io/en/latest/invoking.html#cmdoption-hoogle
1080[haddock-hyperlinked-source-option]: https://haskell-haddock.readthedocs.io/en/latest/invoking.html#cmdoption-hyperlinked-source
1081[haddock]: https://www.haskell.org/haddock/
1082[haskell-program-coverage]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html#observing-code-coverage
1083[haskell.nix]: https://input-output-hk.github.io/haskell.nix/index.html
1084[HLS user guide]: https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-editor
1085[hoogle]: https://wiki.haskell.org/Hoogle
1086[jailbreak-cabal]: https://github.com/NixOS/jailbreak-cabal/
1087[optparse-applicative-completions]: https://github.com/pcapriotti/optparse-applicative/blob/7726b63796aa5d0df82e926d467f039b78ca09e2/README.md#bash-zsh-and-fish-completions
1088[profiling-detail]: https://cabal.readthedocs.io/en/latest/cabal-project.html#cfg-field-profiling-detail
1089[profiling]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html
1090[search.nixos.org]: https://search.nixos.org