Nix Haskell Overrides: Advanced Packaging, Development, and Trivial Helpers

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} ''; }) ``` `enableSeparateBinOutput drv` : Install executables produced by `drv` to a separate `bin` output. This has a similar effect as `justStaticExecutables`, but preserves the libraries and documentation in the `out` output alongside the `bin` output with a much smaller closure size. `markBroken drv` : Sets the `broken` flag to `true` for `drv`. `markUnbroken drv`, `unmarkBroken drv` : Set the `broken` flag to `false` for `drv`. `doDistribute drv` : Updates `hydraPlatforms` so that Hydra will build `drv`. This is sometimes necessary when working with versioned packages in `haskellPackages` which are not built by default. `dontDistribute drv` : Sets `hydraPlatforms` to `[]`, causing Hydra to skip this package altogether. Useful if it fails to evaluate cleanly and is causing noise in the evaluation errors tab on Hydra. ##### Development Helpers {#haskell-development-helpers} `sdistTarball drv` : Create a source distribution tarball like those found on Hackage instead of building the package `drv`. `documentationTarball drv` : Create a documentation tarball suitable for uploading to Hackage instead of building the package `drv`. `buildFromSdist drv` : Uses `sdistTarball drv` as the source to compile `drv`. This helps to catch packaging bugs when building from a local directory, e.g. when required files are missing from `extra-source-files`. `failOnAllWarnings drv` : Enables all warnings GHC supports and makes it fail the build if any of them are emitted.  `enableDWARFDebugging drv` : Compiles the package with additional debug symbols enabled, useful for debugging with e.g. `gdb`. `doStrip drv` : Sets `doStrip` to `true` for `drv`. `dontStrip drv` : Sets `doStrip` to `false` for `drv`.  ##### Trivial Helpers {#haskell-trivial-helpers} `doJailbreak drv` : Sets the `jailbreak` argument to `true` for `drv`. `dontJailbreak drv` : Sets the `jailbreak` argument to `false` for `drv`. `doHaddock drv` : Sets `doHaddock` to `true` for `drv`. `dontHaddock drv` : Sets `doHaddock` to `false` for `drv`. Useful if the build of a package is failing because of e.g. a syntax error in the Haddock documentation. `doHyperlinkSource drv` : Sets `hyperlinkSource` to `true` for `drv`.

This chunk continues the discussion on `justStaticExecutables`, detailing how to troubleshoot issues where `Paths_*` modules create unwanted GHC references. The solution involves temporarily disabling GHC reference checks, using `strings` to identify problematic libraries, and then employing `remove-references-to` in `postInstall` to clean the output. It then introduces `enableSeparateBinOutput` as an alternative for building executables with a smaller closure while preserving libraries. The document also categorizes and describes various other helper functions: Packaging Helpers like `markBroken` and `doDistribute` for controlling Hydra builds; Development Helpers such as `sdistTarball`, `buildFromSdist`, `failOnAllWarnings`, and `enableDWARFDebugging`; and Trivial Helpers including `doJailbreak` and `doHaddock` for directly setting common derivation arguments.