diff options
Diffstat (limited to 'doc/languages-frameworks/haskell.section.md')
| -rw-r--r-- | doc/languages-frameworks/haskell.section.md | 135 |
1 files changed, 120 insertions, 15 deletions
diff --git a/doc/languages-frameworks/haskell.section.md b/doc/languages-frameworks/haskell.section.md index 5d7796b554de4..6c2af33c8c9eb 100644 --- a/doc/languages-frameworks/haskell.section.md +++ b/doc/languages-frameworks/haskell.section.md @@ -230,7 +230,7 @@ completely incompatible with packages from `haskellPackages`. Every haskell package set has its own haskell-aware `mkDerivation` which is used to build its packages. Generally you won't have to interact with this builder -since [cabal2nix][cabal2nix] can generate packages +since [cabal2nix](#haskell-cabal2nix) can generate packages using it for an arbitrary cabal package definition. Still it is useful to know the parameters it takes when you need to [override](#haskell-overriding-haskell-packages) a generated Nix expression. @@ -923,14 +923,61 @@ for this to work. `justStaticExecutables drv` : Only build and install the executables produced by `drv`, removing everything -that may refer to other Haskell packages' store paths (like libraries and -documentation). This dramatically reduces the closure size of the resulting -derivation. Note that the executables are only statically linked against their -Haskell dependencies, but will still link dynamically against libc, GMP and -other system library dependencies. If dependencies use their Cabal-generated -`Paths_*` module, this may not work as well if GHC's dead code elimination -is unable to remove the references to the dependency's store path that module -contains. + that may refer to other Haskell packages' store paths (like libraries and + documentation). This dramatically reduces the closure size of the resulting + derivation. Note that the executables are only statically linked against their + Haskell dependencies, but will still link dynamically against libc, GMP and + other system library dependencies. + + If a library or its dependencies use their Cabal-generated + `Paths_*` module, this may not work as well if GHC's dead code elimination is + unable to remove the references to the dependency's store path that module + contains. + As a consequence, an unused reference may be created from the static binary to such a _library_ store path. + (See [nixpkgs#164630][164630] for more information.) + + Importing the `Paths_*` module may cause builds to fail with this message: + + ``` + error: output '/nix/store/64k8iw0ryz76qpijsnl9v87fb26v28z8-my-haskell-package-1.0.0.0' is not allowed to refer to the following paths: + /nix/store/5q5s4a07gaz50h04zpfbda8xjs8wrnhg-ghc-9.6.3 + ``` + + If that happens, first disable the check for GHC references and rebuild the + derivation: + + ```nix + pkgs.haskell.lib.overrideCabal + (pkgs.haskell.lib.justStaticExecutables my-haskell-package) + (drv: { + disallowGhcReference = false; + }) + ``` + + Then use `strings` to determine which libraries are responsible: + + ``` + $ nix-build ... + $ strings result/bin/my-haskell-binary | grep /nix/store/ + ... + /nix/store/n7ciwdlg8yyxdhbrgd6yc2d8ypnwpmgq-hs-opentelemetry-sdk-0.0.3.6/bin + ... + ``` + + Finally, use `remove-references-to` to delete those store paths from the produced output: + + ```nix + pkgs.haskell.lib.overrideCabal + (pkgs.haskell.lib.justStaticExecutables my-haskell-package) + (drv: { + postInstall = '' + ${drv.postInstall or ""} + remove-references-to -t ${pkgs.haskellPackages.hs-opentelemetry-sdk} + ''; + }) + ``` + +[164630]: https://github.com/NixOS/nixpkgs/issues/164630 `enableSeparateBinOutput drv` : Install executables produced by `drv` to a separate `bin` output. This @@ -1123,17 +1170,74 @@ for [this to work][optparse-applicative-completions]. Note that this feature is automatically disabled when cross-compiling, since it requires executing the binaries in question. +## Import-from-Derivation helpers {#haskell-import-from-derivation} + +### cabal2nix {#haskell-cabal2nix} + +[`cabal2nix`][cabal2nix] can generate Nix package definitions for arbitrary +Haskell packages using [import from derivation][import-from-derivation]. +`cabal2nix` will generate Nix expressions that look like this: + +```nix +# cabal get mtl-2.2.1 && cd mtl-2.2.1 && cabal2nix . +{ mkDerivation, base, lib, transformers }: +mkDerivation { + pname = "mtl"; + version = "2.2.1"; + src = ./.; + libraryHaskellDepends = [ base transformers ]; + homepage = "http://github.com/ekmett/mtl"; + description = "Monad classes, using functional dependencies"; + license = lib.licenses.bsd3; +} +``` + +This expression should be called with `haskellPackages.callPackage`, which will +supply [`haskellPackages.mkDerivation`](#haskell-mkderivation) and the Haskell +dependencies as arguments. + +`callCabal2nix name src args` +: Create a package named `name` from the source derivation `src` using + `cabal2nix`. + + `args` are extra arguments provided to `haskellPackages.callPackage`. + +`callCabal2nixWithOptions name src opts args` +: Create a package named `name` from the source derivation `src` using + `cabal2nix`. + + `opts` are extra options for calling `cabal2nix`. If `opts` is a string, it + will be used as extra command line arguments for `cabal2nix`, e.g. `--subpath + path/to/dir/containing/cabal-file`. Otherwise, `opts` should be an AttrSet + which can contain the following attributes: + + `extraCabal2nixOptions` + : Extra command line arguments for `cabal2nix`. + + `srcModifier` + : A function which is used to modify the given `src` instead of the default + filter. + + The default source filter will remove all files from `src` except for + `.cabal` files and `package.yaml` files. + <!-- -TODO(@NixOS/haskell): finish these planned sections -### Overriding the entire package set +`callHackage` +: TODO +`callHackageDirect` +: TODO -## Import-from-Derivation helpers +`developPackage` +: TODO -* `callCabal2nix` -* `callHackage`, `callHackageDirect` -* `developPackage` +--> + +<!-- + +TODO(@NixOS/haskell): finish these planned sections +### Overriding the entire package set ## Contributing {#haskell-contributing} @@ -1309,3 +1413,4 @@ relevant. [profiling]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html [search.nixos.org]: https://search.nixos.org [turtle]: https://hackage.haskell.org/package/turtle +[import-from-derivation]: https://nixos.org/manual/nix/stable/language/import-from-derivation |