Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+There are multiple components that play a part in the haskell.nix
+infrastructure. These are nix-tools, haskell.nix, hackage.nix,
+and stackage.nix.
.-------------. .-------------.
+.- nix-tools ------. | haskell.nix | .- | hackage.nix |
+| .--------------. | .----------------. '-------------' | '-------------'
+| | stack-to-nix |---> | stack-pkgs.nix |-. | | |
+| '--------------' | '----------------' | v | v
+| .-------------. | .----------. '--> .----------. <-' .--------------.
+| | plan-to-nix |----> | plan.nix |------.---> | pkgs.nix | <--- | stackage.nix |
+| '-------------' | '----------' | '----------' '--------------'
+| .--------------. | .--------------. | |
+| | cabal-to-nix |---> | $package.nix |--' v
+| '--------------' | '--------------' .-------------.
+'------------------' | default.nix |
+ '-------------'
+ |
+ v
+ .-------------.
+ | release.nix |
+ '-------------'
+haskell.nix diagram
+nix-tools is a Haskell package that provides the following tools:
+cabal-to-nix: a .cabal to .nix transformer that retains
+conditional expressions.
stack-to-nix: a stack.yaml to .nix transformer that will read
+in a stack.yaml expression an generate a pkgs.nix file suited for
+use with haskell.nix.
plan-to-nix: a plan.json to .nix transformer that will read in
+a plan.json file and generate a pkgs.nix file suited for use
+with haskell.nix.
as well as a few other tools used to generate hackage.nix and stackage.nix.
Haskell.nix is the runtime system for this Haskell infrastructure.
+It contains the component builder, as well as the system package and
+license mapping. Without haskell.nix the expressions generated by
+either of the nix-tools tools make little sense on their own.
hackage.nix provides all cabal expressions from hackage as nix +expressions. It is periodically updated to keep in sync with the set +of packages available on hackage.
+stackage.nix is similar to hackage.nix but provides all stackage +snapshots (lts, and nightly) as nix expressions. It naturally depends +on hackage.nix to resolve package names, versions and revisions to the +respective packages from hackage.nix.
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+This file contains a summary of changes to Haskell.nix and nix-tools
+that will impact users.
Some time ago the behavior of shellFor changed so that the arguments
+are now checked against modules/shell.nix. This was done as part of a fix
+for bugs in the way shellFor arguments and project shell arguments
+interacted (both are now modules and the normal module merge rules apply).
This means it is no longer possible to pass arbitrarily named arguments
+to shellFor in order to set environment variables.
Instead of:
+p.shellFor {
+ FOO = "bar";
+}
+Use:
+p.shellFor {
+ shellHook = ''
+ export FOO="bar"
+ '';
+}
+or
+(p.shellFor {}).overrideAttrs {
+ FOO = "bar";
+}
+Removed GHC <9.6 from CI.
+The latest nixpkgs-unstable caused problems with
Cabal projects now use the more granular Unit IDs from plan.json
+to identify packages. This allows for different versions of a
+package to be used when building built-tool-depends and setup
+dependencies.
Overrides in the modules argument apply to all versions of
+the package. However to make this work we needed to make
+each packages.somepackage an option (instead of using an
+attrsOf the submodule type).
It is now an error to override a package that is not in the
+plan. This can be a problem if different GHC versions, target
+platforms, or cabal flag settings cause the package to be
+excluded from the plan. Adding package-keys can tell
+haskell.nix to include the option anyway:
modules = [{
+ # Tell haskell.nix that `somepackage` may exist.
+ package-keys = ["somepackage"];
+ # Now the following will not cause an error even
+ # if `somepackage` is not in the plan
+ packages.somepackage.flags.someflag = true;
+ }];
+There is a helper function you can use to add package-keys
+for all of the builtins.attrNames of packages:
modules = [(pkgs.haskell-nix.haskellLib.addPackageKeys {
+ packages.somepackage.flags.someflag = true;
+ })];
+Do not use the module's pkgs arg to look addPackageKeys up
+though or it will result an infinite recursion error.
Code that uses options.packages will also need to be updated.
+For instance the following code that uses options.packages
+to set --Werror for local packages:
({ lib, ... }: {
+ options.packages = lib.mkOption {
+ type = lib.types.attrsOf (lib.types.submodule (
+ { config, lib, ... }:
+ lib.mkIf config.package.isLocal
+ {
+ configureFlags = [ "--ghc-option=-Werror"];
+ }
+ ));
+ };
+ })
+Now needs to do it for each of the entry in config.package-keys
+instead of using attrsOf:
({ config, lib, ... }: {
+ options.packages = lib.genAttrs config.package-keys (_:
+ lib.mkOption {
+ type = lib.types.submodule (
+ { config, lib, ... }:
+ lib.mkIf config.package.isLocal
+ {
+ configureFlags = [ "--ghc-option=-Werror"];
+ }
+ );
+ });
+ })
+Haskell.nix now respects the pre-existing packages selected
+by the cabal planner. The selection made by the planner
+is used to set nonReinstallablePkgs.
Instead setting nonReinstallablePkgs and reinstallableLibGhc
+haskell.nix projects should add constraints to the cabal project.
For instance to force the use of the pre-exising text
+package add:
constraints: text installed
+To make sure text is reinstalled use:
constraints: text source
+The pre-existing ghc will now be used by default as
+that is what cabal will choose (haskell.nix used to choose
+reinstallableLibGhc=true by default).
To allow cabal to choose reinstalling ghc add:
allow-boot-library-installs: True
+To force cabal to choose reinstalling:
+ constraints: ghc source
+ allow-boot-library-installs: True
+It may also need allow-newer: ghc:Cabal
Haskell.nix will no longer parse the cabal.project file to
+determine the index-state. This decision was made due to
+the function's inability to handle more than one index-state
+or a qualified index-state as the first index-state
+field in the file.
As a result, there will be some drawbacks:
+There will no longer be a warning in the trace output +if an index state is not found.
+Even if the index-state: in the cabal.project has not changed,
+the plan will be recomputed when hackage.nix is bumped. However, this
+is not expected to be a problem since plan recomputations are typically
+quick.
project.index-state cannot be used to obtain the found index-state.
+However, the parse function is still available if required
+(haskell-nix.haskellLib.parseIndexState).
Removed reliance on builtins.currentSystem. It was used it to provide
+pkgs.evalPackages via an overlay that it used to run derivations
+used in imports from derivation (IFDs).
These derivations are now run on buildPackages by default.
Passsing evalPackages to a project function will change where all the
+derivations used in IFDs are run for that project (including shell tools):
+evalPackages = import nixpkgs haskellNix.nixpkgsArgs;
Passing evalSystem instead will use create a suitable nixpkgs using pkgs.path
+and pkgs.overlay:
+evalSystem = "x86_64-linux";
+or
+evalSystem = builtins.currentSystem;
The haskellLib.cleanGit function is also affected by this change. If you are cross
+compiling and using cleanGit you should probably do something like:
+pkgs = import nixpkgs haskellNix.nixpkgsArgs;
+evalPackages = import nixpkgs (haskellNix.nixpkgsArgs // { system = evalSystem; });
+p = pkgs.pkgsCross.mingwW64.haskell-nix.cabalProject {
+inherit evalPackages;
+src = evalPackages.haskell-nix.haskellLib.cleanGit { src = ./.; };
+};
sha256map instead.repository in cabal.project. These
+blocks should now work without the need for passing extra-hackages and
+extra-hackage-tarballs.nix/sources.json
+as flake inputs (flake.lock replaces nix/sources.json).flake-compat to continue to provide a compatible interface for non
+flake projects.source-repository-package references in cabal.project files are now
+left as a source-repository-package when calculating the the plan-nix for
+cabalProject based functions.
+This makes haskell.nix match the behaviour of cabal better.
+Materialized files for projects that use source-repository-package
+references will need to be updated.plan.json file it
+will not be present in hsPkgs.pkg.components..dwarf to build any component with DWARF dubug info on linux
+(ghc >=8.10.2).enableDWARF to shellFor for to get a shell where all the
+components are the .dwarf ones.ghcOptions has been moved from package and is now a list of strings.
+old: packages.x.package.ghcOptions = "someGHCoption";
+new: packages.x.ghcOptions = ["someGHCoption"];
+To specify ghcOptions for all packages:
+ghcOptions = ["someGHCoption"];
+For a single component:
+packages.x.compoents.library.ghcOptions = ["someGHCoption"];includeSiblings to cleanSourceWith. When true it
+prevents the subDir arg from causing filtering of other directories.keepGitDir to cleanGit to allow .git directory to be kept
+(useful for components that use the githash package).otherShells arg for shellFor to `inputsFromshellFor makeConfigFiles ghcWithHoogle and ghcWithPackages
+functions have been removed from project.hsPkgs. Instead access
+them from project itself (e.g. change p.hsPkgs.shellFor to p.shellFor).project.shells.ghc has been removed.
+If needed, add something like p // { shells.ghc = p.shellFor {} }
+to shell.nix.${targetPrefix}cabal wrapper script for running cross
+compilers in shellFor.otherShells arg added to shellFor.tools.hoogle to shellFor with a value suitable for haskel-nix.tool will
+use the specified hoogle inside shellFor. This allows for materialization
+of hoogle.compiler-nix-name to project functions for stack.yaml
+based projects now overrides the compiler used (was ignored before).doCoverage module option that allows users to choose
+packages to enable coverage for.doCoverage flag to the component builder that outputs HPC
+information when coverage is enabled.components.all, use symlinkJoin on components.exes or
+shellFor if you need a shell.components argument to shellFor.haskell-nix.roots and p.roots to single derivations.sources.nixpkgs-default, use sources.nixpkgs instead../nixpkgs directory, use (import ./. {}).sources
+or ./nix/sources.nix instead.compiler-nix-name argument.haskell-nix.tool and .tools now require a compiler-nix-name argument.
+New functions p.tool and p.tools (where p is a project) do not.
+Like shellFor { tools = ... } they will use the compiler nix name
+from the project (including stack projects where it is derived from
+the resolver).haskell-nix.alex and haskell-nix.happy have been removed. Use
+p.tool "alex" "3.2.5" or shellFor { tools = { alex = "3.2.5"; } }.haskell-nix.nix-tools -> haskell-nix.nix-tools.ghc883 (it includes
+the hpack exe now).haskell-nix.cabal-install ->
+p.tool "cabal" "3.2.0.0" or shellFor { tools = { cabal = "3.2.0.0"; } }haskell-nix.haskellNixRoots -> haskell-nix.roots ghc883 or p.rootsshellFor) attempts
+to accesses the .doc attribute of component.cleanSourceHaskell to accept an attrset of src and
+(optional) name parameters. This allows you to keep the source
+derivation name constant, so that your builds are always
+cached. Usage of cleanSourceHaskell will need to be updated.shellFor no longer sets CABAL_CONFIG by default.
+This avoids surprising users, but means that Cabal may select a plan which is different to your Haskell.nix package set.
+If you would like the old behaviour, use shellFor { exactDeps = true; }.haskellLib.collectComponents function.ghcWithPackages and ghcWithHoogle to hsPkgs (documentation.shellFor function to package set.snaphots and haskellPackages attributes to the
+Haskell.nix top-level.cleanSourceHaskell utility function to the Haskell.nix
+top-level.callCabalProjectToNix function, which uses "import from
+derivation" (IFD) so that nix-tools doesn't need to be run
+manually.hackage.nix update process has changed, so that Cabal index
+state hashes are also included in the generated repo.callStackToNix function, which uses "import from
+derivation" (IFD) so that stack-to-nix doesn't need to be run
+manually.overlays was renamed to extras in
+#79
+to prevent confusion between the notion of Nix overlays.
Therefore plan-pkgs and stack-pkgs as generated by plan-to-nix and stack-to-nix will
+expose extras instead of overlay. Similarly mkStackPkgSet, mkPkgSet and mkCabalProjectPkgSet
+take a pkg-def-extras instead of pkg-def-overlay argument. If you are using iohk-nix, the
+iohk-overlay was parameter was renamed to iohk-extras.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+overlays/bootstrap.nixEach ghc version is defined in this file. Duplicate one of the existing
+ghc version definitions and replace the version numbers. Make sure
+you update the spec.sha256 or the other versions source will be used.
+Check the LLVM version that should be used in the
+ghc wiki.
ci.nixIn the haskell.nix repo run:
+mkdir materialized/ghc884
+nix-build scripts/check-compiler-materialization --argstr compiler-nix-name ghc884
+The nix-build command will fail with something like:
Materialized nix used for dummy-data-x86_64-unknown-linux-musl-ghc-8.10.1 incorrect. To fix run: /nix/store/wnwpyrhv4nxgyljz3f20gdpspjxvm7h4-updateMaterialized
+Run the updateMaterialized script and repeat the nix-build until it no longer fails.
+If the failure is not a problem with materialization and no updateMaterialized script
+is provided then you may need to fix the failure another way or (if it only relates to
+one of the cross compilers) modify scripts/check-compiler-materialization/default.nix
+so that it skips that compiler.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The implementation of coverage starts with the "doCoverage" flag on
+the builder in comp-builder.nix. The doCoverage flag enables and
+disables the Cabal coverage flag and copies any generated coverage
+data to "$out/share/hpc".
The coverage information for any derivation consists of "mix" and +"tix" files.
+Mix files record static information about a source file and are +generated at build time. They primarily contain a path to the source +file and information about expressions and regions of the source file, +which are later referenced by tix files.
+Tix files contain dynamic information about a test run, recording when +a portion of a source file is touched by a test. These are generated +when the test is run.
+In the context of multiple local packages, there are a few types of +coverage we might be interested in:
+To facilitate expressing any of these classifications of coverage, the
+lib/cover.nix function provides the mixLibraries argument. If
+you're just interested in how the tests cover the package library, you
+provide that library as an argument to mixLibraries. If you're
+interested in how the tests also cover other local packages in the
+project, you can also provide those libraries as arguments to
+mixLibraries.
The projectCoverageReport and coverageReport attributes that are
+provided by default on projects and packages respectively provide
+coverage information for all local packages in the project. This is
+to mimic the behaviour of Stack, which seems to be the expectation of
+most people. Of course, you can use the projectCoverageReport and
+coverageReport functions to construct your own custom coverage
+reports (as detailed in the coverage tutorial).
The coverage information generated will look something like this:
+/nix/store/...-my-project-0.1.0.0-coverage-report/
+└── share
+ └── hpc
+ └── vanilla
+ ├── html
+ │ └── my-library-0.1.0.0
+ │ ├── my-library-0.1.0.0-48EVZBwW9Kj29VTaRMhBDf
+ │ │ ├── My.Lib.Config.hs.html
+ │ │ ├── My.Lib.Types.hs.html
+ │ │ └── My.Lib.Util.hs.html
+ │ ├── hpc_index_alt.html
+ │ ├── hpc_index_exp.html
+ │ ├── hpc_index_fun.html
+ │ └── hpc_index.html
+ ├── mix
+ │ └── my-library-0.1.0.0
+ │ └── my-library-0.1.0.0-48EVZBwW9Kj29VTaRMhBDf
+ │ ├── My.Lib.Config.mix
+ │ ├── My.Lib.Types.mix
+ │ └── My.Lib.Util.mix
+ └── tix
+ └── my-library-0.1.0.0
+ ├── my-library-0.1.0.0.tix
+ ├── my-test-1
+ │ └── my-test-1.tix
+ └── unit-test
+ └── unit-test.tix
+my-project.checks.my-test-1.config.modules)share/hpc/vanilla/html/my-library-0.1.0.0 report is generated from
+the
+share/hpc/vanilla/tix/my-library-0.1.0.0/my-library-0.1.0.0.tix
+file)The coverage information for an entire project will look something +like this:
+/nix/store/...-coverage-report
+└── share
+ └── hpc
+ └── vanilla
+ ├── html
+ │ ├── index.html
+ │ ├── all
+ │ │ ├── my-library-0.1.0.0-ERSaOroBZhe9awsoBkhmcV
+ │ │ │ ├── My.Lib.Config.hs.html
+ │ │ │ ├── My.Lib.Types.hs.html
+ │ │ │ └── My.Lib.Util.hs.html
+ │ │ ├── other-library-0.1.0.0-48EVZBwW9Kj29VTaRMhBDf
+ │ │ │ ├── Other.Lib.A.hs.html
+ │ │ │ └── Other.Lib.B.hs.html
+ │ │ ├── hpc_index_alt.html
+ │ │ ├── hpc_index_exp.html
+ │ │ ├── hpc_index_fun.html
+ │ │ └── hpc_index.html
+ │ ├── my-library-0.1.0.0
+ │ │ ├── my-library-0.1.0.0-ERSaOroBZhe9awsoBkhmcV
+ │ │ │ ├── My.Lib.Config.hs.html
+ │ │ │ ├── My.Lib.Types.hs.html
+ │ │ │ └── My.Lib.Util.hs.html
+ │ │ ├── hpc_index_alt.html
+ │ │ ├── hpc_index_exp.html
+ │ │ ├── hpc_index_fun.html
+ │ │ └── hpc_index.html
+ │ └── other-libray-0.1.0.0
+ │ ├── other-library-0.1.0.0-48EVZBwW9Kj29VTaRMhBDf
+ │ │ ├── Other.Lib.A.hs.html
+ │ │ └── Other.Lib.B.hs.html
+ │ ├── hpc_index_alt.html
+ │ ├── hpc_index_exp.html
+ │ ├── hpc_index_fun.html
+ │ └── hpc_index.html
+ ├── mix
+ │ ├── my-library-0.1.0.0-ERSaOroBZhe9awsoBkhmcV
+ │ │ ├── My.Lib.Config.mix
+ │ │ ├── My.Lib.Types.mix
+ │ │ └── My.Lib.Util.mix
+ │ └── other-library-0.1.0.0-48EVZBwW9Kj29VTaRMhBDf
+ │ ├── Other.Lib.A.mix
+ │ └── Other.Lib.B.mix
+ └── tix
+ ├── all
+ │ └── all.tix
+ ├── my-library-0.1.0.0
+ │ ├── my-library-0.1.0.0.tix
+ │ ├── my-test-1
+ │ │ └── my-test-1.tix
+ │ └── unit-test
+ │ └── unit-test.tix
+ └── another-library-0.1.0.0
+ ├── another-library-0.1.0.0.tix
+ ├── my-test-2
+ │ └── my-test-2.tix
+ └── unit-test
+ └── unit-test.tix
+All of the coverage information is copied verbatim from the coverage +reports for each of the constituent packages. A few additions are +made:
+tix/all/all.tix is generated from the union of all the library
+tix files.
+html/index.html) is generated which links to the
+HTML coverage reports of the constituent packages.tix/all/all.tix
+file. This shows the union of all the coverage information
+generated by each constituent coverage report.Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+This shall give a sufficiently good overview over the haskell.nix +ideas, such that a new developer can navigate around without too +much trouble.
+haskell.nix is centered around packages (haskell package
+descriptions as nix-expressions). These are generated by
+cabal-to-nix from the nix-tools package. stack-to-nix and
+plan-to-nix will delegate the transformation of cabal packages to
+nix expressions to the same code that cabal-to-nix uses.
These packages will look similar to the following:
+{ system, compiler, flags, pkgs, hsPkgs, pkgconfPkgs, ... }:
+{
+ flags = {};
+ package = { ... };
+ components = {
+ "library" = { depends = [ ... ]; };
+ exes = { "..." = { depends = [ ... ]; }; ... };
+ sublibs = { "..." = { depends = [ ... ]; }; ... };
+ tests = { "..." = { depends = [ ... ]; }; ... };
+ benchmarks = { "..." = { depends = [ ... ]; }; ... };
+ };
+};
+The exact specification can be found in modules/package.nix.
Packages (unless specified directly in the packages attribute of the
+module) usually come from a plan. A plan is either a Stackage snapshot
+(nightly or LTS) or a build plan as produced by cabal.
Plan files usually look like the following:
+hackage:
+{
+ packages = {
+ "$pkg".revision = hackage.$pkg.$version.revisions.default;
+ "$pkg".flags = { flag1 = true; flag2 = false; ... };
+ ...
+ };
+ compiler = {
+ version = "8.4.4";
+ nix-name = "ghc844";
+ packages = {
+ "binary" = "0.8.5.1";
+ ...
+ };
+ };
+}
+This provides enough information about the compiler, what packages the +compiler ships with and the packages we want to use in our plan.
+This revision and flag information will be inlined into a list of
+packages in config.packages in modules/plan.nix. Thus
+config.packages will only contains packages as described in the
+previous section.
We finally tie this all together in package-set.nix where we use
+modules/component-driver.nix to produce the derivations for each
+packages component to produce the final config.hsPkgs value.
There is also a modules/compat-driver.nix that should produce the
+same packageset to be used with the stock haskell infrastructure in
+nixpkgs (This has undergone substantially less testing).
To prevent depending on multiple instances of the same libraries, the
+component builder will try to build every package from scratch and
+rely as little as possible on packages that are shipped with the GHC
+distribution. The exceptions are packages that are known to not be
+reinstallable. See config.nonReinstallablePkgs.
The component builder can be found in modules/component-driver.nix
+and builder/default.nix. The component-driver will ensure that we do
+not try to rebuild non-reinstallable packages, and call the
+builder/default.nix on each package in config.packages to produce
+config.hsPkgs.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+When making changes to the way Hix works it is often useful to be able to +test the changes locally before uploading them to github.
+Install the hix command wrappers after making changes to a local clone of haskell.nix:
+nix-env -iA hix -f /path/to/local/haskell.nix
+hix-shell
+Or override the version of haskell.nix used by the commands with the HIX_ROOT environment variable:
HIX_ROOT=/path/to/local/haskell.nix hix-shell
+For flakes use --override-input to point to the modified haskell.nix:
nix develop --override-input haskellNix /path/to/local/haskell.nix
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+nix-toolsTo build the latest nix-tools and store the result at ./nt, run:
nix build -f https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz pkgs.haskell-nix.nix-tools.ghc884 --out-link nt
+If you would like to then install nix-tools into your profile, run an install
+command:
nix-env -i ./nt
+nix profile install ./nt
+The Haskell.nix and nix-tools source will be useful if you would
+like to contribute improvements, or read the source code to fully
+understand something that the documentation doesn't cover.
git clone https://github.com/input-output-hk/nix-tools
+git clone https://github.com/input-output-hk/haskell.nix
+cd haskell.nix
+nix build -f . pkgs.haskell-nix.nix-tools.ghc884 --arg sourcesOverride '{ nix-tools = ../nix-tools; }' --out-link nt
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+The hackage.nix
+and stackage.nix
+repos and corresponding files hackage-src.json and
+stackage-src.json will be regularly and automatically updated using
+scripts in this repo.
To run the updater scripts manually, use:
+nix-build build.nix -A maintainer-scripts.update-hackage -o update-hackage.sh
+./update-hackage.sh
+
+nix-build build.nix -A maintainer-scripts.update-stackage -o update-stackage.sh
+./update-stackage.sh
+The scripts will clone the repo, generate the latest data, then +attempt to push back to the repo and update the source JSON file.
+ +Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+We believe that imports from derivations (IFDs) provide tremendous +value in nix and the aversion towards them stems mostly from +poor tooling and ci support for them. We do not believe +that poor tooling or ci support should cripple nix capability +of abstraction. Hence haskell.nix makes excessive use of +IFDs.
+We do note however that there are users who prefer to +have IFD-free expressions. For this group of users we +detail how to expand the IFD dependent high level functions +into their IFD free building blocks.
+The general structure will be the same, independent of the use of +Stack or Cabal.
+Let us assume for now that we have already generated a pkgs.nix
+expression (see the links bellow). The following file then produces a package set:
# default.nix
+let
+ # Import the Haskell.nix library,
+ pkgs = import <nixpkgs> (import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz") {}).nixpkgsArgs;
+
+ # Import the file you will create in the stack-to-nix or cabal-to-nix step.
+ my-pkgs = import ./pkgs.nix;
+
+ # Stack projects use this:
+ # pkgSet = pkgs.haskell-nix.mkStackPkgSet {
+ # stack-pkgs = my-pkgs;
+ # pkg-def-extras = [
+ # # these extras will provide additional packages
+ # # ontop of the package set. E.g. extra-deps
+ # # for stack packages. or local packages for
+ # # cabal.projects
+ # ];
+ # modules = [
+ # # specific package overrides would go here
+ # # example:
+ # # packages.cbors.package.ghcOptions = "-Werror";
+ # # packages.cbors.patches = [ ./one.patch ];
+ # # packages.cbors.flags.optimize-gmp = false;
+ # # It may be better to set flags in stack.yaml instead
+ # # (`stack-to-nix` will include them as defaults).
+ # ];
+ # };
+
+ # Cabal projects use this:
+ pkgSet = pkgs.haskell-nix.mkCabalProjectPkgSet {
+ plan-pkgs = my-pkgs;
+ pkg-def-extras = [];
+ modules = [
+ # specific package overrides would go here
+ # example:
+ # packages.cbors.package.ghcOptions = "-Werror";
+ # packages.cbors.patches = [ ./one.patch ];
+ # packages.cbors.flags.optimize-gmp = false;
+ # It may be better to set flags in `cabal.project` instead
+ # (`plan-to-nix` will include them as defaults).
+ ];
+ };
+
+in pkgSet.config.hsPkgs // { _config = pkgSet.config; }
+With this setup you can then start building the components of +interest:
+nix build -f default.nix $pkg.components.library
+to build the library for $pkg or
nix build -f default.nix $pkg.components.exes.$exe
+to build a specific executable. The same holds for test suites and benchmarks.
+With nix-tools installed, we can simply run the +following command on a stack project:
+stack-to-nix --output . --stack-yaml stack.yaml
+This will produce a pkgs.nix file that looks like the following:
{
+ resolver = "lts-12.17";
+ extras = hackage:
+ {
+ packages = {
+ "o-clock" = hackage.o-clock."0.1.1".revisions.default;
+ ...
+ } // {
+ my-package = ./my-package.nix;
+ ...
+ };
+ };
+}
+This file contains the stackage resolver, as well as set of extra
+packages. The extras specifies which extra-deps (here:
+o-clock-0.1.1) we wanted to add over the stackage snapshot, and what
+local packages we want (here: my-package).
plan.jsonTo get a plan, you need Cabal and GHC. See the How to install a +compiler section of the Nixpkgs Manual for information +about how to choose a specific compiler version.
+++Note: Cabal version
+The minimum Cabal version is 2.4. This version is available +in the NixOS 19.03 release.
+
For this example, we will run a nix-shell with the default GHC
+version for Nixpkgs.
nix-shell -p haskellPackages.cabal-install haskellPackages.ghc \
+ --run "cabal new-configure"
+If all goes well, you should now have the file
+dist-newstyle/cache/plan.json.
++Tip: Specifying the GHC version
+To use a specific compiler version, replace
+haskellPackages.ghc+with something likehaskell-nix.compiler.ghc865. The given compiler +must exist in your Nixpkgs version, of course. See also the +Nixpkgs Manual.
plan-to-nixWith nix-tools installed, we can then run the
+following command on a Cabal project and its build plan. Omit the
+--cabal-project option if you don't have a project file.
# convert the plan.json file into a pkgs.nix file
+plan-to-nix --output . \
+ --plan-json dist-newstyle/cache/plan.json
+ --cabal-project cabal.project
+This will produce a pkgs.nix file that looks like the following:
{
+ pkgs = hackage:
+ {
+ packages = {
+ "o-clock" = hackage.o-clock."0.1.1".revisions.default;
+ ...
+ };
+ compiler = { ... };
+ };
+
+ extras = hackage:
+ { packages = { my-package = ./.plan.nix/my-package.nix; }; };
+}
+It has converted Cabal's build plan into a Nix expression that selects
+dependencies from hackage.nix. All local packages in the project are
+generated with cabal-to-nix and added to the package set
+description.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+nix-toolsUse niv to update the sources.json:
+nix flake update nix-tools
+If nix-tools.cabal or plan-to-nix have changed, check the
+materialized files for each of the compiler nix name in
+ls -d materialized/ghc*/nix-tools with:
nix-build scripts/check-compiler-materialization --argstr compiler-nix-name ghc884
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+Haskell.nix contains several Nixpkgs pins imanaged by niv in
+nix/sources.json.
These are used in testing various versions of nixpkgs.
+To use haskell.nix the config and overlays need to be applied to
+Nixpkgs. Users should probably pin a suitable version of nixpkgs, although things might not work for them if their Nixpkgs version is
+too different.
We aim to keep this pin somewhere on a channel of the Nixpkgs latest +stable release. That is currently 20.09.
+We also execute tests on MacOS (darwin). The darwin channel is usually
+behind the NixOS channel. So we follow the nixpkgs-20.09-darwin
+channel.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+ghcWithPackages wrapper removalThe current Nixpkgs Haskell infrastructure and haskell.nix both
+provide a ghcWithPackages derivation which contains shell script
+wrappers that wrap ghc and ghc-pkg.
In the Nixpkgs Haskell infrastructure, the wrapper scripts are used
+for building Haskell packages. However, in haskell.nix, the wrappers
+are only used for development environments.
The wrapper scripts provide a ghc command that "knows" about the
+package set and has all Haskell package dependencies available to it.
We would like to remove the wrapper scripts, but it's currently not +possible to configure all build tools using environment variables +alone.
+ghcWhen using ghc or ghci by itself, the GHC_ENVIRONMENT variable
+can point to a configuration file containing an exact package
+set. This works quite well.
ghc-pkgThe package tool ghc-pkg does not recognize GHC_ENVIRONMENT, but
+does recognize a GHC_PACKAGE_PATH pointing to a package.conf.d.
This works well. However, the cabal command will refuse to start if
+GHC_PACKAGE_PATH is set.
Setup.hsWhen invoking Setup.hs configure, the package database is provided
+with the --package-db argument and exact dependencies in the package
+set can be provided as --dependency arguments.
The haskell.nix component builder uses Setup.hs with these
+command-line options to build Haskell packages.
cabal new-buildCabal-install will observe the CABAL_CONFIG environment variable,
+which points to a cabal config file. This config file can provide a
+package-db value, but it can't specify exact versions of packages.
Cabal is designed to solve dependencies, not simply take the package +set which is given to it.
+Therefore, cabal does not use GHC_ENVIRONMENT, but instead creates
+its own environment file. It will not accept --dependency arguments.
As far as I know, the best way to force cabal to take a pre-computed
+package set is to use a new-freeze file. However there is no
+environment variable (or config file entry) which can specify a path
+to a freeze file.
Specifying a package-db path in the cabal config file is not enough
+for it to successfully resolve dependencies.
As mentioned before, cabal does not work when GHC_PACKAGE_PATH is
+set. The best way to work around this is to wrap ghc and ghc-pkg
+in shell scripts.
Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+To build the test cases, run from the test directory:
nix-build --no-out-link default.nix
+To run all tests (includes impure tests), use the script:
+./tests.sh
+If you change the test Cabal files or need to regenerate the code with
+nix-tools, then see regen.nix. Run it like this:
$(nix-build --no-out-link regen.nix)
+Press ← or → to navigate between chapters
+Press S or / to search in the book
+Press ? to show this help
+Press Esc to hide this help
+haskell.nix is an infrastructure based on nix to build Haskell code.
The following report shows how each module is covered by any test in the project:
-The following reports show how the tests of each package cover modules in the project:
-