haskellPackages.shellFor creates invalid NIX_GHC_DOCDIR

[KAction]

Describe the bug

haskellPackages.shellFor function creates environment with NIX_GHC_DOCDIR
variable set to non-existent path.

Steps To Reproduce

$ cat bad.nix
let
  pkgs = import ./. {};
in pkgs.haskellPackages.shellFor {
  packages = p: [ p.lens ];
}
$ nix-shell bad.nix --run 'ls -al $NIX_GHC_DOCDIR'
ls: cannot access '/nix/store/5hjpspgqm47hqwdjrryrqglp0zfz0b0a-ghc-8.10.7-with-packages/share/doc/ghc/html': No such file or directory

Expected behavior

$NIX_GHC_DOCDIR points to directory with html documentation of all
dependencies.

Notify maintainers

@peti
@cdepillabout
@expipiplus1
@maralorn
@sternenseemann
@cstrahan

Metadata

$ git show
commit 290ab1ac45f92825613c5f24cc4896dd6524b748
Merge: d77cd852ab1 e06f742bebd
Author: Maciej Krüger <[email protected]>
Date:   Sun Dec 12 08:56:08 2021 +0100

    Merge pull request #150379 from r-ryantm/auto-update/xviewer

[user@system:~]$ nix-shell -p nix-info --run "nix-info -m"
 - system: `"x86_64-linux"`
 - host os: `Linux 5.15.7`
 - multi-user?: `yes`
 - sandbox: `yes`
 - version: `nix-env (Nix) 2.5pre20211007_844dd90`
 - channels(kaction): `"nixpkgs-21.11pre332093.7fad01d9d5a"`
 - nixpkgs: `/home/kaction/.nix-defexpr/channels/nixpkgs`

[maralorn]

That is a very good observation.

Of course the burning question is: Has this ever worked or what changed?

In the wrapper code we have docDir pointing at $out/share/doc/ghc/html. Which apparently doesn‘t exist.
More concerning the only directory called html that I can find in the wrapper result is at $out/lib/ghc-8.10.7/html and it appears to only contain js/css assets but no actual documentation. There is not a single html file in the wrapper result.

Instead the docs dir is apparently part of the -doc output of the original ghc build. That dir does not seem to be included by the symlinkJoin that we are using for the wrapper.

It’s a typical "how can this ever have worked" situation. Can someone shed a bit of light on this?

@KAction May I ask how you discovered this? Is there a concrete use case which was broken by this?

[KAction]

@maralorn

Well, I started new Haskell project with template from here: https://github.com/utdemir/hs-nix-template, and it happened to generate default.nix which called shellFor. I did nix-env and it provided with cool environment -- hoogle, repl and other nice things. I wanted to read documentation of my dependencies, so I looked around with env|grep -E 'GHC|NIX' and discovered variable in question.

Actually, if you provide withHoogle = true, you will get documentation, but in another directory.

[maralorn]

Yeah, to be honest, I wouldn‘t actually know how to typically access the config without using hoogle as an entry point. And that usecase works. So I am curious for which situation we need the variable.

[KAction]

As the most straightforward solution we may set this variable only if withHoogle is set, and change its value. Not sure that it is safe, since its value is inspected by GHC itself.

[sternenseemann]

NIX_GHC_DOCDIR is relatively inconsequential in the grand scheme of things, because it is only used by ghc-paths, not GHC itself. In principle this would probably point to the current GHC's documentation directory where in a Nix sense only the documentation of base etc. would be located, downstream packages likely expect all documentation there.

We could create such a directory using buildEnv, although I'm a bit worried it could be slow. ghcWithHoogle doesn't have such a directory, instead the hoogle db knows where the different packages' documentation is located (which is much neater).