From 18ea31126f04dd9820430781ade74dd54f9824b5 Mon Sep 17 00:00:00 2001 From: sternenseemann Date: Sat, 14 Jan 2023 02:02:11 +0100 Subject: [PATCH] improve docs on `env` attribute --- doc/languages-frameworks/haskell.section.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/doc/languages-frameworks/haskell.section.md b/doc/languages-frameworks/haskell.section.md index 717606e511ab8..2412193105915 100644 --- a/doc/languages-frameworks/haskell.section.md +++ b/doc/languages-frameworks/haskell.section.md @@ -465,10 +465,19 @@ $ nix-shell -A haskellPackages.random.env '' ``` As you can see, the environment contains a GHC which is set up so it finds all -dependencies of `random`. Since nixpkgs only relies on `Setup.hs` for actually -building the package, the environment doesn't contain familiar development tools -like `cabal-install`. If you have it installed on your system anyway, it will -work as expected in the `nix-shell` (as long as you don't use `--pure`). +dependencies of `random`. Note that this environment does not mirror +the environment used to build the package, but is intended as a convenient +tool for development and simple debugging. `env` relies on the `ghcWithPackages` +wrapper which automatically injects a pre-populated package-db into every +GHC invocation. When building the derivation, the appropriate flags would always +be passed explicitly. + +`env` mirrors the normal derivation environment in one aspect: It does not include +familiar development tools like `cabal-install`, since we rely on plain `Setup.hs` +to build all packages. However, `cabal-install` will work as expected if in +`PATH` (e.g. when installed globally and using a `nix-shell` without `--pure`). +A declarative and pure way of adding arbitrary development tools is provided +via [`shellFor`](#ssec-haskell-shellFor).