haskell / haskell/cabal

Windows: GHC >= 9.0 boot libraries `*.conf` files: problem with the `haddock-html` paths

Open
#9,000 0 comments 0 reactions 0 assignees View on GitHub
resolution: not our bug
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.