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` or `separateBinOutput` 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] (a curated set of known to be
49compatible packages), we use the version prescribed by a Stackage snapshot
50(usually the current LTS one) as the default version. For all other packages we
51use the latest version from [Hackage](https://hackage.org) (the repository of
52basically all open source Haskell packages). See [below](#haskell-available-
53versions) for a few more details on this.
54
55Roughly half of the 16K packages contained in `haskellPackages` don’t actually
56build and are [marked as broken semi-automatically](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/broken.yaml).
57Most of those packages are deprecated or unmaintained, but sometimes packages
58that should build, do not build. Very often fixing them is not a lot of work.
59
60<!--
61TODO(@sternenseemann):
62How you can help with that is
63described in [Fixing a broken package](#haskell-fixing-a-broken-package).
64-->
65
66`haskellPackages` is built with our default compiler, but we also provide other
67releases of GHC and package sets built with them. You can list all available
68compilers like this:
69
70```console
71$ nix-env -f '<nixpkgs>' -qaP -A haskell.compiler
72haskell.compiler.ghc810 ghc-8.10.7
73haskell.compiler.ghc90 ghc-9.0.2
74haskell.compiler.ghc925 ghc-9.2.5
75haskell.compiler.ghc926 ghc-9.2.6
76haskell.compiler.ghc927 ghc-9.2.7
77haskell.compiler.ghc92 ghc-9.2.8
78haskell.compiler.ghc945 ghc-9.4.5
79haskell.compiler.ghc946 ghc-9.4.6
80haskell.compiler.ghc947 ghc-9.4.7
81haskell.compiler.ghc94 ghc-9.4.8
82haskell.compiler.ghc963 ghc-9.6.3
83haskell.compiler.ghc96 ghc-9.6.4
84haskell.compiler.ghc98 ghc-9.8.1
85haskell.compiler.ghcHEAD ghc-9.9.20231121
86haskell.compiler.ghc8107Binary ghc-binary-8.10.7
87haskell.compiler.ghc865Binary ghc-binary-8.6.5
88haskell.compiler.ghc924Binary ghc-binary-9.2.4
89haskell.compiler.integer-simple.ghc8107 ghc-integer-simple-8.10.7
90haskell.compiler.integer-simple.ghc810 ghc-integer-simple-8.10.7
91haskell.compiler.native-bignum.ghc90 ghc-native-bignum-9.0.2
92haskell.compiler.native-bignum.ghc902 ghc-native-bignum-9.0.2
93haskell.compiler.native-bignum.ghc925 ghc-native-bignum-9.2.5
94haskell.compiler.native-bignum.ghc926 ghc-native-bignum-9.2.6
95haskell.compiler.native-bignum.ghc927 ghc-native-bignum-9.2.7
96haskell.compiler.native-bignum.ghc92 ghc-native-bignum-9.2.8
97haskell.compiler.native-bignum.ghc928 ghc-native-bignum-9.2.8
98haskell.compiler.native-bignum.ghc945 ghc-native-bignum-9.4.5
99haskell.compiler.native-bignum.ghc946 ghc-native-bignum-9.4.6
100haskell.compiler.native-bignum.ghc947 ghc-native-bignum-9.4.7
101haskell.compiler.native-bignum.ghc94 ghc-native-bignum-9.4.8
102haskell.compiler.native-bignum.ghc948 ghc-native-bignum-9.4.8
103haskell.compiler.native-bignum.ghc963 ghc-native-bignum-9.6.3
104haskell.compiler.native-bignum.ghc96 ghc-native-bignum-9.6.4
105haskell.compiler.native-bignum.ghc964 ghc-native-bignum-9.6.4
106haskell.compiler.native-bignum.ghc98 ghc-native-bignum-9.8.1
107haskell.compiler.native-bignum.ghc981 ghc-native-bignum-9.8.1
108haskell.compiler.native-bignum.ghcHEAD ghc-native-bignum-9.9.20231121
109haskell.compiler.ghcjs ghcjs-8.10.7
110```
111
112Each of those compiler versions has a corresponding attribute set built using
113it. However, the non-standard package sets are not tested regularly and, as a
114result, contain fewer working packages. The corresponding package set for GHC
1159.4.5 is `haskell.packages.ghc945`. In fact `haskellPackages` is just an alias
116for `haskell.packages.ghc964`:
117
118```console
119$ nix-env -f '<nixpkgs>' -qaP -A haskell.packages.ghc927
120haskell.packages.ghc927.a50 a50-0.5
121haskell.packages.ghc927.AAI AAI-0.2.0.1
122haskell.packages.ghc927.aasam aasam-0.2.0.0
123haskell.packages.ghc927.abacate abacate-0.0.0.0
124haskell.packages.ghc927.abc-puzzle abc-puzzle-0.2.1
125…
126```
127
128Every package set also re-exposes the GHC used to build its packages as `haskell.packages.*.ghc`.
129
130### Available package versions {#haskell-available-versions}
131
132We aim for a “blessed” package set which only contains one version of each
133package, like [Stackage], which is a curated set of known to be compatible
134packages. We use the version information from Stackage snapshots and extend it
135with more packages. Normally in Nixpkgs the number of building Haskell packages
136is roughly two to three times the size of Stackage. For choosing the version to
137use for a certain package we use the following rules:
138
1391. By default, for `haskellPackages.foo` is the newest version of the package
140`foo` found on [Hackage](https://hackage.org), which is the central registry
141of all open source Haskell packages. Nixpkgs contains a reference to a pinned
142Hackage snapshot, thus we use the state of Hackage as of the last time we
143updated this pin.
1442. If the [Stackage] snapshot that we use (usually the newest LTS snapshot)
145contains a package, [we use instead the version in the Stackage snapshot as
146default version for that package.](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/stackage.yaml)
1473. For some packages, which are not on Stackage, we have if necessary [manual
148overrides to set the default version to a version older than the newest on
149Hackage.](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/main.yaml)
1504. For all packages, for which the newest Hackage version is not the default
151version, there will also be a `haskellPackages.foo_x_y_z` package with the
152newest version. The `x_y_z` part encodes the version with dots replaced by
153underscores. When the newest version changes by a new release to Hackage the
154old package will disappear under that name and be replaced by a newer one under
155the name with the new version. The package name including the version will
156also disappear when the default version e.g. from Stackage catches up with the
157newest version from Hackage. E.g. if `haskellPackages.foo` gets updated from
1581.0.0 to 1.1.0 the package `haskellPackages.foo_1_1_0` becomes obsolete and
159gets dropped.
1605. For some packages, we also [manually add other `haskellPackages.foo_x_y_z`
161versions](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/main.yaml),
162if they are required for a certain build.
163
164Relying on `haskellPackages.foo_x_y_z` attributes in derivations outside
165nixpkgs is discouraged because they may change or disappear with every package
166set update.
167<!-- TODO(@maralorn) We should add a link to callHackage, etc. once we added
168them to the docs. -->
169
170All `haskell.packages.*` package sets use the same package descriptions and the same sets
171of versions by default. There are however GHC version specific override `.nix`
172files to loosen this a bit.
173
174### Dependency resolution {#haskell-dependency-resolution}
175
176Normally when you build Haskell packages with `cabal-install`, `cabal-install`
177does dependency resolution. It will look at all Haskell package versions known
178on Hackage and tries to pick for every (transitive) dependency of your build
179exactly one version. Those versions need to satisfy all the version constraints
180given in the `.cabal` file of your package and all its dependencies.
181
182The [Haskell builder in nixpkgs](#haskell-mkderivation) does no such thing.
183It will take as input packages with names off the desired dependencies
184and just check whether they fulfill the version bounds and fail if they don’t
185(by default, see `jailbreak` to circumvent this).
186
187The `haskellPackages.callPackage` function does the package resolution.
188It will, e.g., use `haskellPackages.aeson`which has the default version as
189described above for a package input of name `aeson`. (More general:
190`<packages>.callPackage f` will call `f` with named inputs provided from the
191package set `<packages>`.)
192While this is the default behavior, it is possible to override the dependencies
193for a specific package, see
194[`override` and `overrideScope`](#haskell-overriding-haskell-packages).
195
196### Limitations {#haskell-limitations}
197
198Our main objective with `haskellPackages` is to package Haskell software in
199nixpkgs. This entails some limitations, partially due to self-imposed
200restrictions of nixpkgs, partially in the name of maintainability:
201
202* Only the packages built with the default compiler see extensive testing of the
203 whole package set. For other GHC versions only a few essential packages are
204 tested and cached.
205* As described above we only build one version of most packages.
206
207The experience using an older or newer packaged compiler or using different
208versions may be worse, because builds will not be cached on `cache.nixos.org`
209or may fail.
210
211Thus, to get the best experience, make sure that your project can be compiled
212using the default compiler of nixpkgs and recent versions of its dependencies.
213
214A result of this setup is, that getting a valid build plan for a given
215package can sometimes be quite painful, and in fact this is where most of the
216maintenance work for `haskellPackages` is required. Besides that, it is not
217possible to get the dependencies of a legacy project from nixpkgs or to use a
218specific stack solver for compiling a project.
219
220Even though we couldn’t use them directly in nixpkgs, it would be desirable
221to have tooling to generate working Nix package sets from build plans generated
222by `cabal-install` or a specific Stackage snapshot via import-from-derivation.
223Sadly we currently don’t have tooling for this. For this you might be
224interested in the alternative [haskell.nix] framework, which, be warned, is
225completely incompatible with packages from `haskellPackages`.
226
227<!-- TODO(@maralorn) Link to package set generation docs in the contributors guide below. -->
228
229## `haskellPackages.mkDerivation` {#haskell-mkderivation}
230
231Every haskell package set has its own haskell-aware `mkDerivation` which is used
232to build its packages. Generally you won't have to interact with this builder
233since [cabal2nix](#haskell-cabal2nix) can generate packages
234using it for an arbitrary cabal package definition. Still it is useful to know
235the parameters it takes when you need to
236[override](#haskell-overriding-haskell-packages) a generated Nix expression.
237
238`haskellPackages.mkDerivation` is a wrapper around `stdenv.mkDerivation` which
239re-defines the default phases to be haskell aware and handles dependency
240specification, test suites, benchmarks etc. by compiling and invoking the
241package's `Setup.hs`. It does *not* use or invoke the `cabal-install` binary,
242but uses the underlying `Cabal` library instead.
243
244### General arguments {#haskell-derivation-args}
245
246`pname`
247: Package name, assumed to be the same as on Hackage (if applicable)
248
249`version`
250: Packaged version, assumed to be the same as on Hackage (if applicable)
251
252`src`
253: Source of the package. If omitted, fetch package corresponding to `pname`
254and `version` from Hackage.
255
256`sha256`
257: Hash to use for the default case of `src`.
258
259`revision`
260: Revision number of the updated cabal file to fetch from Hackage.
261If `null` (which is the default value), the one included in `src` is used.
262
263`editedCabalFile`
264: `sha256` hash of the cabal file identified by `revision` or `null`.
265
266`configureFlags`
267: Extra flags passed when executing the `configure` command of `Setup.hs`.
268
269`buildFlags`
270: Extra flags passed when executing the `build` command of `Setup.hs`.
271
272`haddockFlags`
273: Extra flags passed to `Setup.hs haddock` when building the documentation.
274
275`doCheck`
276: Whether to execute the package's test suite if it has one. Defaults to `true` unless cross-compiling.
277
278`doBenchmark`
279: Whether to execute the package's benchmark if it has one. Defaults to `false`.
280
281`doHoogle`
282: Whether to generate an index file for [hoogle][hoogle] as part of
283`haddockPhase` by passing the [`--hoogle` option][haddock-hoogle-option].
284Defaults to `true`.
285
286`doHaddockQuickjump`
287: Whether to generate an index for interactive navigation of the HTML documentation.
288Defaults to `true` if supported.
289
290`doInstallIntermediates`
291: Whether to install intermediate build products (files written to `dist/build`
292by GHC during the build process). With `enableSeparateIntermediatesOutput`,
293these files are instead installed to [a separate `intermediates`
294output.][multiple-outputs] The output can then be passed into a future build of
295the same package with the `previousIntermediates` argument to support
296incremental builds. See [“Incremental builds”](#haskell-incremental-builds) for
297more information. Defaults to `false`.
298
299`enableLibraryProfiling`
300: Whether to enable [profiling][profiling] for libraries contained in the
301package. Enabled by default if supported.
302
303`enableExecutableProfiling`
304: Whether to enable [profiling][profiling] for executables contained in the
305package. Disabled by default.
306
307`profilingDetail`
308: [Profiling detail level][profiling-detail] to set. Defaults to `exported-functions`.
309
310`enableSharedExecutables`
311: Whether to link executables dynamically. By default, executables are linked statically.
312
313`enableSharedLibraries`
314: Whether to build shared Haskell libraries. This is enabled by default unless we are using
315`pkgsStatic` or shared libraries have been disabled in GHC.
316
317`enableStaticLibraries`
318: Whether to build static libraries. Enabled by default if supported.
319
320`enableDeadCodeElimination`
321: Whether to enable linker based dead code elimination in GHC.
322Enabled by default if supported.
323
324`enableHsc2hsViaAsm`
325: Whether to pass `--via-asm` to `hsc2hs`. Enabled by default only on Windows.
326
327`hyperlinkSource`
328: Whether to render the source as well as part of the haddock documentation
329by passing the [`--hyperlinked-source` flag][haddock-hyperlinked-source-option].
330Defaults to `true`.
331
332`isExecutable`
333: Whether the package contains an executable.
334
335`isLibrary`
336: Whether the package contains a library.
337
338`jailbreak`
339: Whether to execute [jailbreak-cabal][jailbreak-cabal] before `configurePhase`
340to lift any version constraints in the cabal file. Note that this can't
341lift version bounds if they are conditional, i.e. if a dependency is hidden
342behind a flag.
343
344`enableParallelBuilding`
345: Whether to use the `-j` flag to make GHC/Cabal start multiple jobs in parallel.
346
347`maxBuildCores`
348: Upper limit of jobs to use in parallel for compilation regardless of
349`$NIX_BUILD_CORES`. Defaults to 16 as Haskell compilation with GHC currently
350sees a [performance regression](https://gitlab.haskell.org/ghc/ghc/-/issues/9221)
351if too many parallel jobs are used.
352
353`doCoverage`
354: Whether to generate and install files needed for [HPC][haskell-program-coverage].
355Defaults to `false`.
356
357`doHaddock`
358: Whether to build (HTML) documentation using [haddock][haddock].
359Defaults to `true` if supported.
360
361`testTarget`
362: Name of the test suite to build and run. If unset, all test suites will be executed.
363
364`preCompileBuildDriver`
365: Shell code to run before compiling `Setup.hs`.
366
367`postCompileBuildDriver`
368: Shell code to run after compiling `Setup.hs`.
369
370`preHaddock`
371: Shell code to run before building documentation using haddock.
372
373`postHaddock`
374: Shell code to run after building documentation using haddock.
375
376`coreSetup`
377: Whether to only allow core libraries to be used while building `Setup.hs`.
378Defaults to `false`.
379
380`useCpphs`
381: Whether to enable the [cpphs][cpphs] preprocessor. Defaults to `false`.
382
383`enableSeparateBinOutput`
384: Whether to install executables to a separate `bin` output. Defaults to `false`.
385
386`enableSeparateDataOutput`
387: Whether to install data files shipped with the package to a separate `data` output.
388Defaults to `false`.
389
390`enableSeparateDocOutput`
391: Whether to install documentation to a separate `doc` output.
392Is automatically enabled if `doHaddock` is `true`.
393
394`enableSeparateIntermediatesOutput`
395: When `doInstallIntermediates` is true, whether to install intermediate build
396products to a separate `intermediates` output. See [“Incremental
397builds”](#haskell-incremental-builds) for more information. Defaults to
398`false`.
399
400`allowInconsistentDependencies`
401: If enabled, allow multiple versions of the same Haskell package in the
402dependency tree at configure time. Often in such a situation compilation would
403later fail because of type mismatches. Defaults to `false`.
404
405`enableLibraryForGhci`
406: Build and install a special object file for GHCi. This improves performance
407when loading the library in the REPL, but requires extra build time and
408disk space. Defaults to `false`.
409
410`previousIntermediates`
411: If non-null, intermediate build artifacts are copied from this input to
412`dist/build` before performing compiling. See [“Incremental
413builds”](#haskell-incremental-builds) for more information. Defaults to `null`.
414
415`buildTarget`
416: Name of the executable or library to build and install.
417If unset, all available targets are built and installed.
418
419### Specifying dependencies {#haskell-derivation-deps}
420
421Since `haskellPackages.mkDerivation` is intended to be generated from cabal
422files, it reflects cabal's way of specifying dependencies. For one, dependencies
423are grouped by what part of the package they belong to. This helps to reduce the
424dependency closure of a derivation, for example benchmark dependencies are not
425included if `doBenchmark == false`.
426
427`setup*Depends`
428: dependencies necessary to compile `Setup.hs`
429
430`library*Depends`
431: dependencies of a library contained in the package
432
433`executable*Depends`
434: dependencies of an executable contained in the package
435
436`test*Depends`
437: dependencies of a test suite contained in the package
438
439`benchmark*Depends`
440: dependencies of a benchmark contained in the package
441
442The other categorization relates to the way the package depends on the dependency:
443
444`*ToolDepends`
445: Tools we need to run as part of the build process.
446They are added to the derivation's `nativeBuildInputs`.
447
448`*HaskellDepends`
449: Haskell libraries the package depends on.
450They are added to `propagatedBuildInputs`.
451
452`*SystemDepends`
453: Non-Haskell libraries the package depends on.
454They are added to `buildInputs`
455
456`*PkgconfigDepends`
457: `*SystemDepends` which are discovered using `pkg-config`.
458They are added to `buildInputs` and it is additionally
459ensured that `pkg-config` is available at build time.
460
461`*FrameworkDepends`
462: Apple SDK Framework which the package depends on when compiling it on Darwin.
463
464Using these two distinctions, you should be able to categorize most of the dependency
465specifications that are available:
466`benchmarkFrameworkDepends`,
467`benchmarkHaskellDepends`,
468`benchmarkPkgconfigDepends`,
469`benchmarkSystemDepends`,
470`benchmarkToolDepends`,
471`executableFrameworkDepends`,
472`executableHaskellDepends`,
473`executablePkgconfigDepends`,
474`executableSystemDepends`,
475`executableToolDepends`,
476`libraryFrameworkDepends`,
477`libraryHaskellDepends`,
478`libraryPkgconfigDepends`,
479`librarySystemDepends`,
480`libraryToolDepends`,
481`setupHaskellDepends`,
482`testFrameworkDepends`,
483`testHaskellDepends`,
484`testPkgconfigDepends`,
485`testSystemDepends` and
486`testToolDepends`.
487
488That only leaves the following extra ways for specifying dependencies:
489
490`buildDepends`
491: Allows specifying Haskell dependencies which are added to `propagatedBuildInputs` unconditionally.
492
493`buildTools`
494: Like `*ToolDepends`, but are added to `nativeBuildInputs` unconditionally.
495
496`extraLibraries`
497: Like `*SystemDepends`, but are added to `buildInputs` unconditionally.
498
499`pkg-configDepends`
500: Like `*PkgconfigDepends`, but are added to `buildInputs` unconditionally.
501
502`testDepends`
503: Deprecated, use either `testHaskellDepends` or `testSystemDepends`.
504
505`benchmarkDepends`
506: Deprecated, use either `benchmarkHaskellDepends` or `benchmarkSystemDepends`.
507
508The dependency specification methods in this list which are unconditional
509are especially useful when writing [overrides](#haskell-overriding-haskell-packages)
510when you want to make sure that they are definitely included. However, it is
511recommended to use the more accurate ones listed above when possible.
512
513### Meta attributes {#haskell-derivation-meta}
514
515`haskellPackages.mkDerivation` accepts the following attributes as direct
516arguments which are transparently set in `meta` of the resulting derivation. See
517the [Meta-attributes section](#chap-meta) for their documentation.
518
519* These attributes are populated with a default value if omitted:
520 * `homepage`: defaults to the Hackage page for `pname`.
521 * `platforms`: defaults to `lib.platforms.all` (since GHC can cross-compile)
522* These attributes are only set if given:
523 * `description`
524 * `license`
525 * `changelog`
526 * `maintainers`
527 * `broken`
528 * `hydraPlatforms`
529
530### Incremental builds {#haskell-incremental-builds}
531
532`haskellPackages.mkDerivation` supports incremental builds for GHC 9.4 and
533newer with the `doInstallIntermediates`, `enableSeparateIntermediatesOutput`,
534and `previousIntermediates` arguments.
535
536The basic idea is to first perform a full build of the package in question,
537save its intermediate build products for later, and then copy those build
538products into the build directory of an incremental build performed later.
539Then, GHC will use those build artifacts to avoid recompiling unchanged
540modules.
541
542For more detail on how to store and use incremental build products, see
543[Gabriella Gonzalez’ blog post “Nixpkgs support for incremental Haskell
544builds”.][incremental-builds] motivation behind this feature.
545
546An incremental build for [the `turtle` package][turtle] can be performed like
547so:
548
549```nix
550let
551 pkgs = import <nixpkgs> {};
552 inherit (pkgs) haskell;
553 inherit (haskell.lib.compose) overrideCabal;
554
555 # Incremental builds work with GHC >=9.4.
556 turtle = haskell.packages.ghc944.turtle;
557
558 # This will do a full build of `turtle`, while writing the intermediate build products
559 # (compiled modules, etc.) to the `intermediates` output.
560 turtle-full-build-with-incremental-output = overrideCabal (drv: {
561 doInstallIntermediates = true;
562 enableSeparateIntermediatesOutput = true;
563 }) turtle;
564
565 # This will do an incremental build of `turtle` by copying the previously
566 # compiled modules and intermediate build products into the source tree
567 # before running the build.
568 #
569 # GHC will then naturally pick up and reuse these products, making this build
570 # complete much more quickly than the previous one.
571 turtle-incremental-build = overrideCabal (drv: {
572 previousIntermediates = turtle-full-build-with-incremental-output.intermediates;
573 }) turtle;
574in
575 turtle-incremental-build
576```
577
578## Development environments {#haskell-development-environments}
579
580In addition to building and installing Haskell software, nixpkgs can also
581provide development environments for Haskell projects. This has the obvious
582advantage that you benefit from `cache.nixos.org` and no longer need to compile
583all project dependencies yourself. While it is often very useful, this is not
584the primary use case of our package set. Have a look at the section
585[available package versions](#haskell-available-versions) to learn which
586versions of packages we provide and the section
587[limitations](#haskell-limitations), to judge whether a `haskellPackages`
588based development environment for your project is feasible.
589
590By default, every derivation built using
591[`haskellPackages.mkDerivation`](#haskell-mkderivation) exposes an environment
592suitable for building it interactively as the `env` attribute. For example, if
593you have a local checkout of `random`, you can enter a development environment
594for it like this (if the dependencies in the development and packaged version
595match):
596
597```console
598$ cd ~/src/random
599$ nix-shell -A haskellPackages.random.env '<nixpkgs>'
600[nix-shell:~/src/random]$ ghc-pkg list
601/nix/store/a8hhl54xlzfizrhcf03c1l3f6l9l8qwv-ghc-9.2.4-with-packages/lib/ghc-9.2.4/package.conf.d
602 Cabal-3.6.3.0
603 array-0.5.4.0
604 base-4.16.3.0
605 binary-0.8.9.0
606 …
607 ghc-9.2.4
608 …
609```
610
611As you can see, the environment contains a GHC which is set up so it finds all
612dependencies of `random`. Note that this environment does not mirror
613the environment used to build the package, but is intended as a convenient
614tool for development and simple debugging. `env` relies on the `ghcWithPackages`
615wrapper which automatically injects a pre-populated package-db into every
616GHC invocation. In contrast, using `nix-shell -A haskellPackages.random` will
617not result in an environment in which the dependencies are in GHCs package
618database. Instead, the Haskell builder will pass in all dependencies explicitly
619via configure flags.
620
621`env` mirrors the normal derivation environment in one aspect: It does not include
622familiar development tools like `cabal-install`, since we rely on plain `Setup.hs`
623to build all packages. However, `cabal-install` will work as expected if in
624`PATH` (e.g. when installed globally and using a `nix-shell` without `--pure`).
625A declarative and pure way of adding arbitrary development tools is provided
626via [`shellFor`](#haskell-shellFor).
627
628When using `cabal-install` for dependency resolution you need to be a bit
629careful to achieve build purity. `cabal-install` will find and use all
630dependencies installed from the packages `env` via Nix, but it will also
631consult Hackage to potentially download and compile dependencies if it can’t
632find a valid build plan locally. To prevent this you can either never run
633`cabal update`, remove the cabal database from your `~/.cabal` folder or run
634`cabal` with `--offline`. Note though, that for some usecases `cabal2nix` needs
635the local Hackage db.
636
637Often you won't work on a package that is already part of `haskellPackages` or
638Hackage, so we first need to write a Nix expression to obtain the development
639environment from. Luckily, we can generate one very easily from an already
640existing cabal file using `cabal2nix`:
641
642```console
643$ ls
644my-project.cabal src …
645$ cabal2nix ./. > my-project.nix
646```
647
648The generated Nix expression evaluates to a function ready to be
649`callPackage`-ed. For now, we can add a minimal `default.nix` which does just
650that:
651
652```nix
653# Retrieve nixpkgs impurely from NIX_PATH for now, you can pin it instead, of course.
654{ pkgs ? import <nixpkgs> {} }:
655
656# use the nixpkgs default haskell package set
657pkgs.haskellPackages.callPackage ./my-project.nix { }
658```
659
660Using `nix-build default.nix` we can now build our project, but we can also
661enter a shell with all the package's dependencies available using `nix-shell
662-A env default.nix`. If you have `cabal-install` installed globally, it'll work
663inside the shell as expected.
664
665### shellFor {#haskell-shellFor}
666
667Having to install tools globally is obviously not great, especially if you want
668to provide a batteries-included `shell.nix` with your project. Luckily there's a
669proper tool for making development environments out of packages' build
670environments: `shellFor`, a function exposed by every haskell package set. It
671takes the following arguments and returns a derivation which is suitable as a
672development environment inside `nix-shell`:
673
674`packages`
675: This argument is used to select the packages for which to build the
676development environment. This should be a function which takes a haskell package
677set and returns a list of packages. `shellFor` will pass the used package set to
678this function and include all dependencies of the returned package in the build
679environment. This means you can reuse Nix expressions of packages included in
680nixpkgs, but also use local Nix expressions like this: `hpkgs: [
681(hpkgs.callPackage ./my-project.nix { }) ]`.
682
683`nativeBuildInputs`
684: Expects a list of derivations to add as build tools to the build environment.
685This is the place to add packages like `cabal-install`, `doctest` or `hlint`.
686Defaults to `[]`.
687
688`buildInputs`
689: Expects a list of derivations to add as library dependencies, like `openssl`.
690This is rarely necessary as the haskell package expressions usually track system
691dependencies as well. Defaults to `[]`. (see also
692[derivation dependencies](#haskell-derivation-deps))
693
694`withHoogle`
695: If this is true, `hoogle` will be added to `nativeBuildInputs`.
696Additionally, its database will be populated with all included dependencies,
697so you'll be able search through the documentation of your dependencies.
698Defaults to `false`.
699
700`genericBuilderArgsModifier`
701: This argument accepts a function allowing you to modify the arguments passed
702to `mkDerivation` in order to create the development environment. For example,
703`args: { doCheck = false; }` would cause the environment to not include any test
704dependencies. Defaults to `lib.id`.
705
706`doBenchmark`
707: This is a shortcut for enabling `doBenchmark` via `genericBuilderArgsModifier`.
708Setting it to `true` will cause the development environment to include all
709benchmark dependencies which would be excluded by default. Defaults to `false`.
710
711One neat property of `shellFor` is that it allows you to work on multiple
712packages using the same environment in conjunction with
713[cabal.project files][cabal-project-files].
714Say our example above depends on `distribution-nixpkgs` and we have a project
715file set up for both, we can add the following `shell.nix` expression:
716
717```nix
718{ pkgs ? import <nixpkgs> {} }:
719
720pkgs.haskellPackages.shellFor {
721 packages = hpkgs: [
722 # reuse the nixpkgs for this package
723 hpkgs.distribution-nixpkgs
724 # call our generated Nix expression manually
725 (hpkgs.callPackage ./my-project/my-project.nix { })
726 ];
727
728 # development tools we use
729 nativeBuildInputs = [
730 pkgs.cabal-install
731 pkgs.haskellPackages.doctest
732 pkgs.cabal2nix
733 ];
734
735 # Extra arguments are added to mkDerivation's arguments as-is.
736 # Since it adds all passed arguments to the shell environment,
737 # we can use this to set the environment variable the `Paths_`
738 # module of distribution-nixpkgs uses to search for bundled
739 # files.
740 # See also: https://cabal.readthedocs.io/en/latest/cabal-package.html#accessing-data-files-from-package-code
741 distribution_nixpkgs_datadir = toString ./distribution-nixpkgs;
742}
743```
744
745<!-- TODO(@sternenseemann): deps are not included if not selected -->
746
747### haskell-language-server {#haskell-language-server}
748
749To use HLS in short: Install `pkgs.haskell-language-server` e.g. in
750`nativeBuildInputs` in `shellFor` and use the `haskell-language-server-wrapper`
751command to run it. See the [HLS user guide] on how to configure your text
752editor to use HLS and how to test your setup.
753
754HLS needs to be compiled with the GHC version of the project you use it
755on.
756
757``pkgs.haskell-language-server`` provides
758``haskell-language-server-wrapper``, ``haskell-language-server``
759and ``haskell-language-server-x.x.x``
760binaries, where ``x.x.x`` is the GHC version for which it is compiled. By
761default, it only includes binaries for the current GHC version, to reduce
762closure size. The closure size is large, because HLS needs to be dynamically
763linked to work reliably. You can override the list of supported GHC versions
764with e.g.
765
766```nix
767pkgs.haskell-language-server.override { supportedGhcVersions = [ "90" "94" ]; }
768```
769Where all strings `version` are allowed such that
770`haskell.packages.ghc${version}` is an existing package set.
771
772When you run `haskell-language-server-wrapper` it will detect the GHC
773version used by the project you are working on (by asking e.g. cabal or
774stack) and pick the appropriate versioned binary from your path.
775
776Be careful when installing HLS globally and using a pinned nixpkgs for a
777Haskell project in a `nix-shell`. If the nixpkgs versions deviate to much
778(e.g., use different `glibc` versions) the `haskell-language-server-?.?.?`
779executable will try to detect these situations and refuse to start. It is
780recommended to obtain HLS via `nix-shell` from the nixpkgs version pinned in
781there instead.
782
783The top level `pkgs.haskell-language-server` attribute is just a convenience
784wrapper to make it possible to install HLS for multiple GHC versions at the
785same time. If you know, that you only use one GHC version, e.g., in a project
786specific `nix-shell` you can use
787`pkgs.haskellPackages.haskell-language-server` or
788`pkgs.haskell.packages.*.haskell-language-server` from the package set you use.
789
790If you use `nix-shell` for your development environments remember to start your
791editor in that environment. You may want to use something like `direnv` and/or an
792editor plugin to achieve this.
793
794## Overriding Haskell packages {#haskell-overriding-haskell-packages}
795
796### Overriding a single package {#haskell-overriding-a-single-package}
797
798<!-- TODO(@sternenseemann): we should document /somewhere/ that base == null etc. -->
799
800Like many language specific subsystems in nixpkgs, the Haskell infrastructure
801also has its own quirks when it comes to overriding. Overriding of the *inputs*
802to a package at least follows the standard procedure. For example, imagine you
803need to build `nix-tree` with a more recent version of `brick` than the default
804one provided by `haskellPackages`:
805
806```nix
807haskellPackages.nix-tree.override {
808 brick = haskellPackages.brick_0_67;
809}
810```
811
812<!-- TODO(@sternenseemann): This belongs in the next section
813One common problem you may run into with such an override is the build failing
814with “abort because of serious configure-time warning from Cabal”. When scrolling
815up, you'll usually notice that Cabal noticed that more than one versions of the same
816package was present in the dependency graph. This typically causes a later compilation
817failure (the error message `haskellPackages.mkDerivation` produces tries to save
818you the time of finding this out yourself, but if you wish to do so, you can
819disable it using `allowInconsistentDependencies`). Luckily, `haskellPackages` provides
820you with a tool to deal with this. `overrideScope` creates a new `haskellPackages`
821instance with the override applied *globally* for this package, so the dependency
822closure automatically uses a consistent version of the overridden package. E. g.
823if `haskell-ci` needs a recent version of `Cabal`, but also uses other packages
824that depend on that library, you may want to use:
825
826```nix
827haskellPackages.haskell-ci.overrideScope (self: super: {
828 Cabal = self.Cabal_3_6_2_0;
829})
830```
831
832-->
833
834The custom interface comes into play when you want to override the arguments
835passed to `haskellPackages.mkDerivation`. For this, the function `overrideCabal`
836from `haskell.lib.compose` is used. E.g., if you want to install a man page
837that is distributed with the package, you can do something like this:
838
839```nix
840haskell.lib.compose.overrideCabal (drv: {
841 postInstall = ''
842 ${drv.postInstall or ""}
843 install -Dm644 man/pnbackup.1 -t $out/share/man/man1
844 '';
845}) haskellPackages.pnbackup
846```
847
848`overrideCabal` takes two arguments:
849
8501. A function which receives all arguments passed to `haskellPackages.mkDerivation`
851 before and returns a set of arguments to replace (or add) with a new value.
8522. The Haskell derivation to override.
853
854The arguments are ordered so that you can easily create helper functions by making
855use of currying:
856
857```nix
858let
859 installManPage = haskell.lib.compose.overrideCabal (drv: {
860 postInstall = ''
861 ${drv.postInstall or ""}
862 install -Dm644 man/${drv.pname}.1 -t "$out/share/man/man1"
863 '';
864 });
865in
866
867installManPage haskellPackages.pnbackup
868```
869
870In fact, `haskell.lib.compose` already provides lots of useful helpers for common
871tasks, detailed in the next section. They are also structured in such a way that
872they can be combined using `lib.pipe`:
873
874```nix
875lib.pipe my-haskell-package [
876 # lift version bounds on dependencies
877 haskell.lib.compose.doJailbreak
878 # disable building the haddock documentation
879 haskell.lib.compose.dontHaddock
880 # pass extra package flag to Cabal's configure step
881 (haskell.lib.compose.enableCabalFlag "myflag")
882]
883```
884
885#### `haskell.lib.compose` {#haskell-haskell.lib.compose}
886
887The base interface for all overriding is the following function:
888
889`overrideCabal f drv`
890: Takes the arguments passed to obtain `drv` to `f` and uses the resulting
891attribute set to update the argument set. Then a recomputed version of `drv`
892using the new argument set is returned.
893
894<!--
895TODO(@sternenseemann): ideally we want to be more detailed here as well, but
896I want to avoid the documentation having to be kept in sync in too many places.
897We already document this stuff in the mkDerivation section and lib/compose.nix.
898Ideally this section would be generated from the latter in the future.
899-->
900
901All other helper functions are implemented in terms of `overrideCabal` and make
902common overrides shorter and more complicate ones trivial. The simple overrides
903which only change a single argument are only described very briefly in the
904following overview. Refer to the
905[documentation of `haskellPackages.mkDerivation`](#haskell-mkderivation)
906for a more detailed description of the effects of the respective arguments.
907
908##### Packaging Helpers {#haskell-packaging-helpers}
909
910`overrideSrc { src, version } drv`
911: Replace the source used for building `drv` with the path or derivation given
912as `src`. The `version` attribute is optional. Prefer this function over
913overriding `src` via `overrideCabal`, since it also automatically takes care of
914removing any Hackage revisions.
915
916<!-- TODO(@sternenseemann): deprecated
917
918`generateOptparseApplicativeCompletions list drv`
919: Generate and install shell completion files for the installed executables whose
920names are given via `list`. The executables need to be using `optparse-applicative`
921for this to work.
922-->
923
924`justStaticExecutables drv`
925: Only build and install the executables produced by `drv`, removing everything
926that may refer to other Haskell packages' store paths (like libraries and
927documentation). This dramatically reduces the closure size of the resulting
928derivation. Note that the executables are only statically linked against their
929Haskell dependencies, but will still link dynamically against libc, GMP and
930other system library dependencies. If dependencies use their Cabal-generated
931`Paths_*` module, this may not work as well if GHC's dead code elimination
932is unable to remove the references to the dependency's store path that module
933contains.
934
935`enableSeparateBinOutput drv`
936: Install executables produced by `drv` to a separate `bin` output. This
937has a similar effect as `justStaticExecutables`, but preserves the libraries
938and documentation in the `out` output alongside the `bin` output with a
939much smaller closure size.
940
941`markBroken drv`
942: Sets the `broken` flag to `true` for `drv`.
943
944`markUnbroken drv`, `unmarkBroken drv`
945: Set the `broken` flag to `false` for `drv`.
946
947`doDistribute drv`
948: Updates `hydraPlatforms` so that Hydra will build `drv`. This is
949sometimes necessary when working with versioned packages in
950`haskellPackages` which are not built by default.
951
952`dontDistribute drv`
953: Sets `hydraPlatforms` to `[]`, causing Hydra to skip this package
954altogether. Useful if it fails to evaluate cleanly and is causing
955noise in the evaluation errors tab on Hydra.
956
957##### Development Helpers {#haskell-development-helpers}
958
959`sdistTarball drv`
960: Create a source distribution tarball like those found on Hackage
961instead of building the package `drv`.
962
963`documentationTarball drv`
964: Create a documentation tarball suitable for uploading to Hackage
965instead of building the package `drv`.
966
967`buildFromSdist drv`
968: Uses `sdistTarball drv` as the source to compile `drv`. This helps to catch
969packaging bugs when building from a local directory, e.g. when required files
970are missing from `extra-source-files`.
971
972`failOnAllWarnings drv`
973: Enables all warnings GHC supports and makes it fail the build if any of them
974are emitted.
975
976<!-- TODO(@sternenseemann):
977`checkUnusedPackages opts drv`
978: Adds an extra check to `postBuild` which fails the build if any dependency
979taken as an input is not used. The `opts` attribute set allows relaxing this
980check.
981-->
982
983`enableDWARFDebugging drv`
984: Compiles the package with additional debug symbols enabled, useful
985for debugging with e.g. `gdb`.
986
987`doStrip drv`
988: Sets `doStrip` to `true` for `drv`.
989
990`dontStrip drv`
991: Sets `doStrip` to `false` for `drv`.
992
993<!-- TODO(@sternenseemann): shellAware -->
994
995##### Trivial Helpers {#haskell-trivial-helpers}
996
997`doJailbreak drv`
998: Sets the `jailbreak` argument to `true` for `drv`.
999
1000`dontJailbreak drv`
1001: Sets the `jailbreak` argument to `false` for `drv`.
1002
1003`doHaddock drv`
1004: Sets `doHaddock` to `true` for `drv`.
1005
1006`dontHaddock drv`
1007: Sets `doHaddock` to `false` for `drv`. Useful if the build of a package is
1008failing because of e.g. a syntax error in the Haddock documentation.
1009
1010`doHyperlinkSource drv`
1011: Sets `hyperlinkSource` to `true` for `drv`.
1012
1013`dontHyperlinkSource drv`
1014: Sets `hyperlinkSource` to `false` for `drv`.
1015
1016`doCheck drv`
1017: Sets `doCheck` to `true` for `drv`.
1018
1019`dontCheck drv`
1020: Sets `doCheck` to `false` for `drv`. Useful if a package has a broken,
1021flaky or otherwise problematic test suite breaking the build.
1022
1023`dontCheckIf condition drv`
1024: Sets `doCheck` to `false` for `drv`, but only if `condition` applies.
1025Otherwise it's a no-op. Useful to conditionally disable tests for a package
1026without interfering with previous overrides or default values.
1027
1028<!-- Purposefully omitting the non-list variants here. They are a bit
1029ugly, and we may want to deprecate them at some point. -->
1030
1031`appendConfigureFlags list drv`
1032: Adds the strings in `list` to the `configureFlags` argument for `drv`.
1033
1034`enableCabalFlag flag drv`
1035: Makes sure that the Cabal flag `flag` is enabled in Cabal's configure step.
1036
1037`disableCabalFlag flag drv`
1038: Makes sure that the Cabal flag `flag` is disabled in Cabal's configure step.
1039
1040`appendBuildFlags list drv`
1041: Adds the strings in `list` to the `buildFlags` argument for `drv`.
1042
1043<!-- TODO(@sternenseemann): removeConfigureFlag -->
1044
1045`appendPatches list drv`
1046: Adds the `list` of derivations or paths to the `patches` argument for `drv`.
1047
1048<!-- TODO(@sternenseemann): link dep section -->
1049
1050`addBuildTools list drv`
1051: Adds the `list` of derivations to the `buildTools` argument for `drv`.
1052
1053`addExtraLibraries list drv`
1054: Adds the `list` of derivations to the `extraLibraries` argument for `drv`.
1055
1056`addBuildDepends list drv`
1057: Adds the `list` of derivations to the `buildDepends` argument for `drv`.
1058
1059`addTestToolDepends list drv`
1060: Adds the `list` of derivations to the `testToolDepends` argument for `drv`.
1061
1062`addPkgconfigDepends list drv`
1063: Adds the `list` of derivations to the `pkg-configDepends` argument for `drv`.
1064
1065`addSetupDepends list drv`
1066: Adds the `list` of derivations to the `setupHaskellDepends` argument for `drv`.
1067
1068`doBenchmark drv`
1069: Set `doBenchmark` to `true` for `drv`. Useful if your development
1070environment is missing the dependencies necessary for compiling the
1071benchmark component.
1072
1073`dontBenchmark drv`
1074: Set `doBenchmark` to `false` for `drv`.
1075
1076`setBuildTargets drv list`
1077: Sets the `buildTarget` argument for `drv` so that the targets specified in `list` are built.
1078
1079`doCoverage drv`
1080: Sets the `doCoverage` argument to `true` for `drv`.
1081
1082`dontCoverage drv`
1083: Sets the `doCoverage` argument to `false` for `drv`.
1084
1085`enableExecutableProfiling drv`
1086: Sets the `enableExecutableProfiling` argument to `true` for `drv`.
1087
1088`disableExecutableProfiling drv`
1089: Sets the `enableExecutableProfiling` argument to `false` for `drv`.
1090
1091`enableLibraryProfiling drv`
1092: Sets the `enableLibraryProfiling` argument to `true` for `drv`.
1093
1094`disableLibraryProfiling drv`
1095: Sets the `enableLibraryProfiling` argument to `false` for `drv`.
1096
1097#### Library functions in the Haskell package sets {#haskell-package-set-lib-functions}
1098
1099Some library functions depend on packages from the Haskell package sets. Thus they are
1100exposed from those instead of from `haskell.lib.compose` which can only access what is
1101passed directly to it. When using the functions below, make sure that you are obtaining them
1102from the same package set (`haskellPackages`, `haskell.packages.ghc944` etc.) as the packages
1103you are working with or – even better – from the `self`/`final` fix point of your overlay to
1104`haskellPackages`.
1105
1106Note: Some functions like `shellFor` that are not intended for overriding per se, are omitted
1107in this section. <!-- TODO(@sternenseemann): note about ifd section -->
1108
1109`cabalSdist { src, name ? ... }`
1110: Generates the Cabal sdist tarball for `src`, suitable for uploading to Hackage.
1111Contrary to `haskell.lib.compose.sdistTarball`, it uses `cabal-install` over `Setup.hs`,
1112so it is usually faster: No build dependencies need to be downloaded, and we can
1113skip compiling `Setup.hs`.
1114
1115`buildFromCabalSdist drv`
1116: Build `drv`, but run its `src` attribute through `cabalSdist` first. Useful for catching
1117files necessary for compilation that are missing from the sdist.
1118
1119`generateOptparseApplicativeCompletions list drv`
1120: Generate and install shell completion files for the installed executables whose
1121names are given via `list`. The executables need to be using `optparse-applicative`
1122for [this to work][optparse-applicative-completions].
1123Note that this feature is automatically disabled when cross-compiling, since it
1124requires executing the binaries in question.
1125
1126## Import-from-Derivation helpers {#haskell-import-from-derivation}
1127
1128### cabal2nix {#haskell-cabal2nix}
1129
1130[`cabal2nix`][cabal2nix] can generate Nix package definitions for arbitrary
1131Haskell packages using [import from derivation][import-from-derivation].
1132`cabal2nix` will generate Nix expressions that look like this:
1133
1134```nix
1135# cabal get mtl-2.2.1 && cd mtl-2.2.1 && cabal2nix .
1136{ mkDerivation, base, lib, transformers }:
1137mkDerivation {
1138 pname = "mtl";
1139 version = "2.2.1";
1140 src = ./.;
1141 libraryHaskellDepends = [ base transformers ];
1142 homepage = "http://github.com/ekmett/mtl";
1143 description = "Monad classes, using functional dependencies";
1144 license = lib.licenses.bsd3;
1145}
1146```
1147
1148This expression should be called with `haskellPackages.callPackage`, which will
1149supply [`haskellPackages.mkDerivation`](#haskell-mkderivation) and the Haskell
1150dependencies as arguments.
1151
1152`callCabal2nix name src args`
1153: Create a package named `name` from the source derivation `src` using
1154 `cabal2nix`.
1155
1156 `args` are extra arguments provided to `haskellPackages.callPackage`.
1157
1158`callCabal2nixWithOptions name src opts args`
1159: Create a package named `name` from the source derivation `src` using
1160 `cabal2nix`.
1161
1162 `opts` are extra options for calling `cabal2nix`. If `opts` is a string, it
1163 will be used as extra command line arguments for `cabal2nix`, e.g. `--subpath
1164 path/to/dir/containing/cabal-file`. Otherwise, `opts` should be an AttrSet
1165 which can contain the following attributes:
1166
1167 `extraCabal2nixOptions`
1168 : Extra command line arguments for `cabal2nix`.
1169
1170 `srcModifier`
1171 : A function which is used to modify the given `src` instead of the default
1172 filter.
1173
1174 The default source filter will remove all files from `src` except for
1175 `.cabal` files and `package.yaml` files.
1176
1177<!--
1178
1179`callHackage`
1180: TODO
1181
1182`callHackageDirect`
1183: TODO
1184
1185`developPackage`
1186: TODO
1187
1188-->
1189
1190<!--
1191
1192TODO(@NixOS/haskell): finish these planned sections
1193### Overriding the entire package set
1194
1195## Contributing {#haskell-contributing}
1196
1197### Fixing a broken package {#haskell-fixing-a-broken-package}
1198
1199### Package set generation {#haskell-package-set-generation}
1200
1201### Packaging a Haskell project
1202
1203### Backporting {#haskell-backporting}
1204
1205Backporting changes to a stable NixOS version in general is covered
1206in nixpkgs' `CONTRIBUTING.md` in general. In particular refer to the
1207[backporting policy](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#criteria-for-backporting-changes)
1208to check if the change you have in mind may be backported.
1209
1210This section focuses on how to backport a package update (e.g. a
1211bug fix or security release). Fixing a broken package works like
1212it does for the unstable branches.
1213
1214-->
1215
1216## F.A.Q. {#haskell-faq}
1217
1218### Why is topic X not covered in this section? Why is section Y missing? {#haskell-why-not-covered}
1219
1220We have been working on [moving the nixpkgs Haskell documentation back into the
1221nixpkgs manual](https://github.com/NixOS/nixpkgs/issues/121403). Since this
1222process has not been completed yet, you may find some topics missing here
1223covered in the old [haskell4nix docs](https://haskell4nix.readthedocs.io/).
1224
1225If you feel any important topic is not documented at all, feel free to comment
1226on the issue linked above.
1227
1228### How to enable or disable profiling builds globally? {#haskell-faq-override-profiling}
1229
1230By default, Nixpkgs builds a profiling version of each Haskell library. The
1231exception to this rule are some platforms where it is disabled due to concerns
1232over output size. You may want to…
1233
1234* …enable profiling globally so that you can build a project you are working on
1235 with profiling ability giving you insight in the time spent across your code
1236 and code you depend on using [GHC's profiling feature][profiling].
1237
1238* …disable profiling (globally) to reduce the time spent building the profiling
1239 versions of libraries which a significant amount of build time is spent on
1240 (although they are not as expensive as the “normal” build of a Haskell library).
1241
1242::: {.note}
1243The method described below affects the build of all libraries in the
1244respective Haskell package set as well as GHC. If your choices differ from
1245Nixpkgs' default for your (host) platform, you will lose the ability to
1246substitute from the official binary cache.
1247
1248If you are concerned about build times and thus want to disable profiling, it
1249probably makes sense to use `haskell.lib.compose.disableLibraryProfiling` (see
1250[](#haskell-trivial-helpers)) on the packages you are building locally while
1251continuing to substitute their dependencies and GHC.
1252:::
1253
1254Since we need to change the profiling settings for the desired Haskell package
1255set _and_ GHC (as the core libraries like `base`, `filepath` etc. are bundled
1256with GHC), it is recommended to use overlays for Nixpkgs to change them.
1257Since the interrelated parts, i.e. the package set and GHC, are connected
1258via the Nixpkgs fixpoint, we need to modify them both in a way that preserves
1259their connection (or else we'd have to wire it up again manually). This is
1260achieved by changing GHC and the package set in separate overlays to prevent
1261the package set from pulling in GHC from `prev`.
1262
1263The result is two overlays like the ones shown below. Adjustable parts are
1264annotated with comments, as are any optional or alternative ways to achieve
1265the desired profiling settings without causing too many rebuilds.
1266
1267<!-- TODO(@sternenseemann): buildHaskellPackages != haskellPackages with this overlay,
1268affected by https://github.com/NixOS/nixpkgs/issues/235960 which needs to be fixed
1269properly still.
1270-->
1271
1272```nix
1273let
1274 # Name of the compiler and package set you want to change. If you are using
1275 # the default package set `haskellPackages`, you need to look up what version
1276 # of GHC it currently uses (note that this is subject to change).
1277 ghcName = "ghc92";
1278 # Desired new setting
1279 enableProfiling = true;
1280in
1281
1282[
1283 # The first overlay modifies the GHC derivation so that it does or does not
1284 # build profiling versions of the core libraries bundled with it. It is
1285 # recommended to only use such an overlay if you are enabling profiling on a
1286 # platform that doesn't by default, because compiling GHC from scratch is
1287 # quite expensive.
1288 (final: prev:
1289 let
1290 inherit (final) lib;
1291 in
1292
1293 {
1294 haskell = prev.haskell // {
1295 compiler = prev.haskell.compiler // {
1296 ${ghcName} = prev.haskell.compiler.${ghcName}.override {
1297 # Unfortunately, the GHC setting is named differently for historical reasons
1298 enableProfiledLibs = enableProfiling;
1299 };
1300 };
1301 };
1302 })
1303
1304 (final: prev:
1305 let
1306 inherit (final) lib;
1307 haskellLib = final.haskell.lib.compose;
1308 in
1309
1310 {
1311 haskell = prev.haskell // {
1312 packages = prev.haskell.packages // {
1313 ${ghcName} = prev.haskell.packages.${ghcName}.override {
1314 overrides = hfinal: hprev: {
1315 mkDerivation = args: hprev.mkDerivation (args // {
1316 # Since we are forcing our ideas upon mkDerivation, this change will
1317 # affect every package in the package set.
1318 enableLibraryProfiling = enableProfiling;
1319
1320 # To actually use profiling on an executable, executable profiling
1321 # needs to be enabled for the executable you want to profile. You
1322 # can either do this globally or…
1323 enableExecutableProfiling = enableProfiling;
1324 });
1325
1326 # …only for the package that contains an executable you want to profile.
1327 # That saves on unnecessary rebuilds for packages that you only depend
1328 # on for their library, but also contain executables (e.g. pandoc).
1329 my-executable = haskellLib.enableExecutableProfiling hprev.my-executable;
1330
1331 # If you are disabling profiling to save on build time, but want to
1332 # retain the ability to substitute from the binary cache. Drop the
1333 # override for mkDerivation above and instead have an override like
1334 # this for the specific packages you are building locally and want
1335 # to make cheaper to build.
1336 my-library = haskellLib.disableLibraryProfiling hprev.my-library;
1337 };
1338 };
1339 };
1340 };
1341 })
1342]
1343```
1344
1345<!-- TODO(@sternenseemann): write overriding mkDerivation, overriding GHC, and
1346overriding the entire package set sections and link to them from here where
1347relevant.
1348-->
1349
1350[Stackage]: https://www.stackage.org
1351[cabal-project-files]: https://cabal.readthedocs.io/en/latest/cabal-project.html
1352[cabal2nix]: https://github.com/nixos/cabal2nix
1353[cpphs]: https://Hackage.haskell.org/package/cpphs
1354[haddock-hoogle-option]: https://haskell-haddock.readthedocs.io/en/latest/invoking.html#cmdoption-hoogle
1355[haddock-hyperlinked-source-option]: https://haskell-haddock.readthedocs.io/en/latest/invoking.html#cmdoption-hyperlinked-source
1356[haddock]: https://www.haskell.org/haddock/
1357[haskell-program-coverage]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html#observing-code-coverage
1358[haskell.nix]: https://input-output-hk.github.io/haskell.nix/index.html
1359[HLS user guide]: https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-editor
1360[hoogle]: https://wiki.haskell.org/Hoogle
1361[incremental-builds]: https://www.haskellforall.com/2022/12/nixpkgs-support-for-incremental-haskell.html
1362[jailbreak-cabal]: https://github.com/NixOS/jailbreak-cabal/
1363[multiple-outputs]: https://nixos.org/manual/nixpkgs/stable/#chap-multiple-output
1364[optparse-applicative-completions]: https://github.com/pcapriotti/optparse-applicative/blob/7726b63796aa5d0df82e926d467f039b78ca09e2/README.md#bash-zsh-and-fish-completions
1365[profiling-detail]: https://cabal.readthedocs.io/en/latest/cabal-project.html#cfg-field-profiling-detail
1366[profiling]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html
1367[search.nixos.org]: https://search.nixos.org
1368[turtle]: https://hackage.haskell.org/package/turtle
1369[import-from-derivation]: https://nixos.org/manual/nix/stable/language/import-from-derivation