mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-09-11 15:08:33 +01:00
Document incremental build support for Haskell
This commit is contained in:
parent
1535bd0c58
commit
ec2938bfa5
|
@ -276,6 +276,15 @@ Defaults to `true`.
|
||||||
: Whether to generate an index for interactive navigation of the HTML documentation.
|
: Whether to generate an index for interactive navigation of the HTML documentation.
|
||||||
Defaults to `true` if supported.
|
Defaults to `true` if supported.
|
||||||
|
|
||||||
|
`doInstallIntermediates`
|
||||||
|
: Whether to install intermediate build products (files written to `dist/build`
|
||||||
|
by GHC during the build process). With `enableSeparateIntermediatesOutput`,
|
||||||
|
these files are instead installed to [a separate `intermediates`
|
||||||
|
output.][multiple-outputs] The output can then be passed into a future build of
|
||||||
|
the same package with the `previousIntermediates` argument to support
|
||||||
|
incremental builds. See [“Incremental builds”](#haskell-incremental-builds) for
|
||||||
|
more information. Defaults to `false`.
|
||||||
|
|
||||||
`enableLibraryProfiling`
|
`enableLibraryProfiling`
|
||||||
: Whether to enable [profiling][profiling] for libraries contained in the
|
: Whether to enable [profiling][profiling] for libraries contained in the
|
||||||
package. Enabled by default if supported.
|
package. Enabled by default if supported.
|
||||||
|
@ -371,6 +380,12 @@ Defaults to `false`.
|
||||||
: Whether to install documentation to a separate `doc` output.
|
: Whether to install documentation to a separate `doc` output.
|
||||||
Is automatically enabled if `doHaddock` is `true`.
|
Is automatically enabled if `doHaddock` is `true`.
|
||||||
|
|
||||||
|
`enableSeparateIntermediatesOutput`
|
||||||
|
: When `doInstallIntermediates` is true, whether to install intermediate build
|
||||||
|
products to a separate `intermediates` output. See [“Incremental
|
||||||
|
builds”](#haskell-incremental-builds) for more information. Defaults to
|
||||||
|
`false`.
|
||||||
|
|
||||||
`allowInconsistentDependencies`
|
`allowInconsistentDependencies`
|
||||||
: If enabled, allow multiple versions of the same Haskell package in the
|
: If enabled, allow multiple versions of the same Haskell package in the
|
||||||
dependency tree at configure time. Often in such a situation compilation would
|
dependency tree at configure time. Often in such a situation compilation would
|
||||||
|
@ -381,6 +396,11 @@ later fail because of type mismatches. Defaults to `false`.
|
||||||
when loading the library in the REPL, but requires extra build time and
|
when loading the library in the REPL, but requires extra build time and
|
||||||
disk space. Defaults to `false`.
|
disk space. Defaults to `false`.
|
||||||
|
|
||||||
|
`previousIntermediates`
|
||||||
|
: If non-null, intermediate build artifacts are copied from this input to
|
||||||
|
`dist/build` before performing compiling. See [“Incremental
|
||||||
|
builds”](#haskell-incremental-builds) for more information. Defaults to `null`.
|
||||||
|
|
||||||
`buildTarget`
|
`buildTarget`
|
||||||
: Name of the executable or library to build and install.
|
: Name of the executable or library to build and install.
|
||||||
If unset, all available targets are built and installed.
|
If unset, all available targets are built and installed.
|
||||||
|
@ -496,6 +516,54 @@ the [Meta-attributes section](#chap-meta) for their documentation.
|
||||||
* `broken`
|
* `broken`
|
||||||
* `hydraPlatforms`
|
* `hydraPlatforms`
|
||||||
|
|
||||||
|
### Incremental builds {#haskell-incremental-builds}
|
||||||
|
|
||||||
|
`haskellPackages.mkDerivation` supports incremental builds for GHC 9.4 and
|
||||||
|
newer with the `doInstallIntermediates`, `enableSeparateIntermediatesOutput`,
|
||||||
|
and `previousIntermediates` arguments.
|
||||||
|
|
||||||
|
The basic idea is to first perform a full build of the package in question,
|
||||||
|
save its intermediate build products for later, and then copy those build
|
||||||
|
products into the build directory of an incremental build performed later.
|
||||||
|
Then, GHC will use those build artifacts to avoid recompiling unchanged
|
||||||
|
modules.
|
||||||
|
|
||||||
|
For more detail on how to store and use incremental build products, see
|
||||||
|
[Gabriella Gonzalez’ blog post “Nixpkgs support for incremental Haskell
|
||||||
|
builds”.][incremental-builds] motivation behind this feature.
|
||||||
|
|
||||||
|
An incremental build for [the `turtle` package][turtle] can be performed like
|
||||||
|
so:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
let
|
||||||
|
pkgs = import <nixpkgs> {};
|
||||||
|
inherit (pkgs) haskell;
|
||||||
|
inherit (haskell.lib.compose) overrideCabal;
|
||||||
|
|
||||||
|
# Incremental builds work with GHC >=9.4.
|
||||||
|
turtle = haskell.packages.ghc944.turtle;
|
||||||
|
|
||||||
|
# This will do a full build of `turtle`, while writing the intermediate build products
|
||||||
|
# (compiled modules, etc.) to the `intermediates` output.
|
||||||
|
turtle-full-build-with-incremental-output = overrideCabal (drv: {
|
||||||
|
doInstallIntermediates = true;
|
||||||
|
enableSeparateIntermediatesOutput = true;
|
||||||
|
}) turtle;
|
||||||
|
|
||||||
|
# This will do an incremental build of `turtle` by copying the previously
|
||||||
|
# compiled modules and intermediate build products into the source tree
|
||||||
|
# before running the build.
|
||||||
|
#
|
||||||
|
# GHC will then naturally pick up and reuse these products, making this build
|
||||||
|
# complete much more quickly than the previous one.
|
||||||
|
turtle-incremental-build = overrideCabal (drv: {
|
||||||
|
previousIntermediates = turtle-full-build-with-incremental-output.intermediates;
|
||||||
|
}) turtle;
|
||||||
|
in
|
||||||
|
turtle-incremental-build
|
||||||
|
```
|
||||||
|
|
||||||
## Development environments {#haskell-development-environments}
|
## Development environments {#haskell-development-environments}
|
||||||
|
|
||||||
In addition to building and installing Haskell software, nixpkgs can also
|
In addition to building and installing Haskell software, nixpkgs can also
|
||||||
|
@ -1083,8 +1151,11 @@ on the issue linked above.
|
||||||
[haskell.nix]: https://input-output-hk.github.io/haskell.nix/index.html
|
[haskell.nix]: https://input-output-hk.github.io/haskell.nix/index.html
|
||||||
[HLS user guide]: https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-editor
|
[HLS user guide]: https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-editor
|
||||||
[hoogle]: https://wiki.haskell.org/Hoogle
|
[hoogle]: https://wiki.haskell.org/Hoogle
|
||||||
|
[incremental-builds]: https://www.haskellforall.com/2022/12/nixpkgs-support-for-incremental-haskell.html
|
||||||
[jailbreak-cabal]: https://github.com/NixOS/jailbreak-cabal/
|
[jailbreak-cabal]: https://github.com/NixOS/jailbreak-cabal/
|
||||||
|
[multiple-outputs]: https://nixos.org/manual/nixpkgs/stable/#chap-multiple-output
|
||||||
[optparse-applicative-completions]: https://github.com/pcapriotti/optparse-applicative/blob/7726b63796aa5d0df82e926d467f039b78ca09e2/README.md#bash-zsh-and-fish-completions
|
[optparse-applicative-completions]: https://github.com/pcapriotti/optparse-applicative/blob/7726b63796aa5d0df82e926d467f039b78ca09e2/README.md#bash-zsh-and-fish-completions
|
||||||
[profiling-detail]: https://cabal.readthedocs.io/en/latest/cabal-project.html#cfg-field-profiling-detail
|
[profiling-detail]: https://cabal.readthedocs.io/en/latest/cabal-project.html#cfg-field-profiling-detail
|
||||||
[profiling]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html
|
[profiling]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html
|
||||||
[search.nixos.org]: https://search.nixos.org
|
[search.nixos.org]: https://search.nixos.org
|
||||||
|
[turtle]: https://hackage.haskell.org/package/turtle
|
||||||
|
|
Loading…
Reference in a new issue