Windows: GHC >= 9.0 boot libraries `*.conf` files: problem with the `haddock-html` paths
- Dominant language
- Haskell
- Stars
- 1.7k
- Forks
- 750
- Avg merge
- 4d 3h
- Merged PRs (30d)
- 28
Description
This is **not** a bug in Cabal (the library) but a bug in GHC >= 9.0 (up to, at least, GHC 9.6.2) that Cabal may wish to accommodate with a work-around. See GHC issue: https://gitlab.haskell.org/ghc/ghc/-/issues/23476 and (because it affects Hoogle too) my Hoogle pull request that suggests that Hoogle accommodate the GHC error: https://github.com/ndmitchell/hoogle/pull/405.
Stack is built on top of Cabal (the library) and I was receiving output like this below with `stack build --haddock` (on Windows) (extracts only) :
~~~text
foo> haddock
Warning: The documentation for the following packages are not installed. No
links will be generated to these packages: base-4.16.4.0, ghc-bignum-1.2,
ghc-prim-0.8.0
Running Haddock on library for foo-0.1.0.0..
50% ( 1 / 2) in 'Lib'
Missing documentation for:
Module header
Warning: Lib: could not find link destinations for:
- GHC.Types.IO
~~~
Note that the 'Warning: ...' (which is via Cabal) is complaining that no documentation is installed for GHC boot libraries, including `base-4.16.4.0`. It turns out that is because the `base-4.16.4.0.conf` file shipped with GHC 9.2.7 contains an error - the `haddock-html` field is not pointing to the correct location where the Haddock HTML is to be found, but to a directory that does not exist.
Proof of this is that if you manually edit the `*.conf` file to point to the correct location, the Cabal warning goes away (eg just for `base`):
~~~text
foo> haddock
Warning: The documentation for the following packages are not installed. No
links will be generated to these packages: ghc-bignum-1.2, ghc-prim-0.8.0
Running Haddock on library for foo-0.1.0.0..
50% ( 1 / 2) in 'Lib'
Missing documentation for:
Module header
~~~
One might argue that the proper approach is for users of GHC >= 9.0 on Windows to patch the `*.conf` files. However, having the tools that rely on the output of `ghc-pkg dump` catch this may be the path of least resistence.
Contributor guide
Research direction
Start by reproducing the Windows case with GHC >= 9.0 and inspect the ghc-pkg dump output and the affected *.conf files. Read the linked GHC issue and Hoogle pull request for the proposed accommodation. Done means Cabal handles the incorrect haddock-html paths so Haddock no longer reports missing boot-library documentation or link destinations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- haskell
- Domain
- build-system, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100