From 02b3ef828b49d157dc1fe1a2ac9ea5c7ae2256c7 Mon Sep 17 00:00:00 2001 From: Hamish Mackenzie Date: Thu, 3 Jul 2025 11:22:20 +1200 Subject: [PATCH 1/2] Update shellFor documentation Fixes #2401 --- changelog.md | 36 ++++++++++++++++++++++++++++ docs/reference/library.md | 50 ++++++++++++++++++++++++++++++++++++--- modules/shell.nix | 2 +- 3 files changed, 84 insertions(+), 4 deletions(-) diff --git a/changelog.md b/changelog.md index a14e3b974..95fa3c362 100644 --- a/changelog.md +++ b/changelog.md @@ -1,6 +1,42 @@ This file contains a summary of changes to Haskell.nix and `nix-tools` that will impact users. +## Jul 3, 2025 + +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"; +} +``` + ## Jan 29, 2025 Removed GHC <9.6 from CI. diff --git a/docs/reference/library.md b/docs/reference/library.md index c6014831c..26b7891bb 100644 --- a/docs/reference/library.md +++ b/docs/reference/library.md @@ -428,18 +428,62 @@ shellFor = { packages, withHoogle ? true, exactDeps ? false, ...}: ... ``` - | Argument | Type | Description | |----------------|------|---------------------| +| `name` | String | Name of the derivation | | `packages` | Function | Package selection function. It takes a list of [Haskell packages](#haskell-package) and returns a subset of these packages. | | `components` | Function | Similar to `packages`, by default all the components of the selected packages are selected. | | `additional` | Function | Similar to `packages`, but the selected packages are built and included in `ghc-pkg list` (not just their dependencies). | | `withHoogle` | Boolean | Whether to build a Hoogle documentation index and provide the `hoogle` command. | | `exactDeps` | Boolean | Prevents the Cabal solver from choosing any package dependency other than what are in the package set. | +| `allToolDeps` | Boolean | Indicates if the shell should include all the tool dependencies of the haskell packages in the project. | | `tools` | Function | AttrSet of tools to make available e.g. `{ cabal = "3.2.0.0"; }` or `{ cabal = { version = "3.2.0.0"; }; }`. If an AttrSet is provided for a tool, the additional arguments will be passed to the function creating the derivation for that tool. So you can provide an `index-state` or a `materialized` argument like that `{ cabal = { version = "3.2.0.0"; index-state = "2020-10-30T00:00:00Z"; materialized = ./cabal.materialized; }; }` for example. You can specify and materialize the version of hoogle used to construct the hoogle index by including something like `{ hoogle = { version = "5.0.17.15"; index-state = "2020-05-31T00:00:00Z"; materialized = ./hoogle.materialized; }`. Uses a default version of hoogle if omitted. | -| `inputsFrom` | List | List of other shells to include in this one. The `buildInputs` and `nativeBuildInputs` of each will be included using [mkShell](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell). +| `packageSetupDeps` | Boolean | Set this to `false` to exclude custom-setup dependencies. +| `enableDWARF` | Boolean | Include debug info | | `crossPlatforms` | Function | Platform selection function for cross compilation targets to support eg. `ps: with ps; [ghcjs mingwW64]` (see nixpkgs lib.systems.examples for list of platform names). | -| `{ ... }` | Attrset | All the other arguments are passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv). | +| `inputsFrom` | List | List of other shells to include in this one. The `buildInputs` and `nativeBuildInputs` of each will be included using [mkShell](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell). +| `shellHook` | String | Bash statements that are executed when the shell starts. | +| `buildInputs` | | Passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv) (via [mkShell](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell)). | +| `nativeBuildInputs` | | Passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv) (via [mkShell](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell)). | +| `passthru` | | Passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv) (via [mkShell](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell)). | + +The arguments are checked using the module `modules/shell.nix`. + +To set environment variables in the shell use: + +``` + shellHook = '' + export FOO="bar" + ''; +``` + +or + +``` +(p.shellFor {}).overrideAttrs { + FOO = "bar"; +} +``` + +The `shellFor` argments can also be passed to to the project `shell` +argument. For instance: + +``` +(pkgs.haskell-nix.project { + ... + shell.tools.cabal = {} +).shellFor {} +``` + +Is the same as: + +``` +(pkgs.haskell-nix.project { + ... +).shellFor { + tools.cabal = {} +} +``` **Return value**: a derivation diff --git a/modules/shell.nix b/modules/shell.nix index 19c4a7ebc..51014692b 100644 --- a/modules/shell.nix +++ b/modules/shell.nix @@ -34,7 +34,7 @@ default = !config.exactDeps; description = '' Indicates if the shell should include all the tool dependencies - of in the haskell packages in the project. Defaulted to `false` in + of the haskell packages in the project. Defaulted to `false` in stack projects (to avoid trying to build the tools used by every `stackage` package). ''; From e36ad46037d8b472a6a17fad0cadf64a7107f0d1 Mon Sep 17 00:00:00 2001 From: Hamish Mackenzie Date: Thu, 3 Jul 2025 11:24:57 +1200 Subject: [PATCH 2/2] Update docs/reference/library.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/reference/library.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/library.md b/docs/reference/library.md index 26b7891bb..c0039bc98 100644 --- a/docs/reference/library.md +++ b/docs/reference/library.md @@ -465,7 +465,7 @@ or } ``` -The `shellFor` argments can also be passed to to the project `shell` +The `shellFor` arguments can also be passed to the project `shell` argument. For instance: ```