Add `tool` documentation

[hamishmack]

The tool and tools features (haskell-nix.tool(s), the shellFor.tools argument and shell.tools) are not well covered by the documentation. However there is a comment in the code. We should update the documentation to cover this and also discuss alternatives (using haskell-nix.hackage-package, haskell-nix.hackage-project and haskell-nix.cabalPackage directly).

haskell.nix/overlays/tools.nix

Lines 1 to 39 in 3473e3c

	# This overlay helps accessing common executable components.
	# Typically we want to make these available in a nix-shell
	# created with shellFor. In most cases the package name
	# will be the same as the executable, but we have a
	# `toolPackageName` and `packageToolName` mapping to help
	# when it is not.
	#
	# To get a single tool:
	# haskell-nix.tool "ghc884" "cabal" "3.2.0.0"
	#
	# This does the same thing as:
	# (haskell-nix.hackage-package {
	# compiler-nix-name = "ghc884";
	# name = "cabal-install"
	# version = "3.2.0.0"
	# }).components.exes.cabal
	#
	# To get an attr set containing multiple tools:
	# haskell-nix.tools "ghc884" { cabal = "3.2.0.0"; hlint = "2.2.11"; }
	#
	# To add tools to a shell:
	# shellFor { tools = { cabal = "3.2.0.0"; hlint = "2.2.11"; }; }
	#
	# When used in shellFor the tools will be compiled with the same version
	# of ghc used in the shell (the build ghc in the case of cross compilation).
	#
	# To get tools for use with project `p` without using shellFor:
	# p.tool "cabal" "3.2.0.0"
	# p.tools { cabal = "3.2.0.0"; hlint = "2.2.11"; }
	# (the ghc version used to build it will match the one used in the project)
	#
	# Instead of a version string we can use an attr set containing
	# arguments that will be passed to `cabalProject`.
	#
	# For instance to add haskell.nix modules. Use:
	# haskell-nix.tool "ghc884" "cabal" {
	# version = "3.2.0.0";
	# modules = [ ... ];
	# }

.

[m4dc4p]

How can I use a pre-release version of Cabal? In particular, I'd like to use 3.10.3.0 (which is not on hackage yet).

I am happy to figure out how to download & build from github, but I can't figure out how to tell haskell.nix to use it everywhere.

Thanks for any help!

[hamishmack]

Instead of setting .version for the tool set .src and point it at the cabal source code. If you are using flakes you can get the source by adding a flake input to your flake.nix. Something like:

inputs.cabal-src = { url = "github:haskell/cabal"; flake = false; };
outputs = { ..., cabal-src }:
  ...
  tools = {
    cabal.src = cabal-src;
    ...

[hamishmack]

but I can't figure out how to tell haskell.nix to use it everywhere.

Oh I missed that bit. Do you need it to be used as the solver and for Setup as well? Is it ok if GHC and its dependencies build with the old Cabal?

To replace Cabal used for solving your projects build plan.

The solver is now included in nix-tools. It might be a bit tricky, but I think you could pass in the location of the Cabal library as a source-repository-package in a CabalProjectLocal argument to build a suitable nix-tools to pass to your project.

To replace Cabal used in Setup

I think packages with Custom build type should respect the plan for Cabal. So setting the build type in Custom in the .cabal file might and adding a source-repository-package for Cabal should work.

If you can't use Custom build type, then you may need to change the way the Cabal used to build the default setup. When possible haskell.nix uses final.buildPackages.haskell-nix.cabal-install-unchecked.${compiler-nix-name}.project.hsPkgs.Cabal.components.library;. I think if you add an overlay to replace haskell-nix.cabal-install-unchecked should work. To prevent infinite recursion you will probably need to build the new cabal-install-unchecked with pkgs that does not include the new overlay (just using prev will not be enough because the default-setup overlay uses final).

Something like:

overrideCabal = final: prev: {
  haskell-nix = prev.haskell-nix // {
    cabal-install-unchecked = prev.haskell-nix.cabal-install-unchecked // {
      ghc981 = pkgsWithoutThisOverlay.haskell-nix.tool "ghc981" "cabal" { src = cabal-src; };
    };
  };
};

[m4dc4p]

This is great stuff! I think it's close to what I need. I'm trying to compile my code under 9.8.1, and I'm running into issues with plugins:

<no location info>: error:
    The name Plugin is not in the type environment: are you sure it exists?

The fix at haskell/cabal#9384 was merged into haskell.nix, but it doesn't seem to be working for me. So I'm trying to use a later version of cabal (from their 3.10 branch) to see if I can make progress.

I think if you add an overlay to replace haskell-nix.cabal-install-unchecked should work.

Did you intend I add this overlay when importing nixpkgs (to override haskell-nix there)? So far that doesn't seem to work (e.g., I have tried using invalid paths for the src and no error occurs). Here is my latest (with irrelevant stuff elided):

  pkgsWithoutThisOverlay = import <nixpkgs-2305> ...;

  overrideCabal = final: prev: {
    haskell-nix = prev.haskell-nix // {
      cabal-install-unchecked = prev.haskell-nix.cabal-install-unchecked // {
        ghc981 = pkgsWithoutThisOverlay.haskell-nix.tool "ghc981" "cabal" { src = ../vendorz/cabal; };
        ghc981llvm = pkgsWithoutThisOverlay.haskell-nix.tool "ghc981" "cabal" { src = ../vendorq/cabal; };
      };
    };
  };

  pkgs = import <nixpkgs-2305> (... { overlays = ... ++ [ overrideCabal ]; });

I am using invalid paths for cabal-install-unchecked, but haskell.nix seems to run cabal when building my project, so I don't think these are having any effect.

I do get errors when I try to evaluate cabal-install-unchecked with the REPL (that is, > pkgs.haskell-nix.cabal-install-unchecked.ghc981 will error) , so the overlay is getting applied at some level.

Thank you for your help so far!

[m4dc4p]

I've managed to reproduce the problem I'm running into with plugins at #2155. I haven't tried to fix it yet with the above.