Skip to content

Building of haddock program and generation of ghc haddocks should be independent

So the comment in build.mk.sample seems wrong / misleading:

https://gitlab.haskell.org/ghc/ghc/-/blob/6a01e28f4204ec17c587931311711fa76e0ea08d/mk/build.mk.sample#L106

# Enable pretty hyperlinked sources
#HADDOCK_DOCS = YES

This suggests that this setting controls whether Haddock is run on GHC to generate hyperlinked sources.

However, it appears that this setting also controls whether the haddock program is built at all, and e.g. installed on the system with make install:

https://gitlab.haskell.org/ghc/ghc/-/blob/6a01e28f4204ec17c587931311711fa76e0ea08d/ghc.mk#L690

ifeq "$(HADDOCK_DOCS)" "NO"
BUILD_DIRS := $(filter-out utils/haddock,$(BUILD_DIRS))
BUILD_DIRS := $(filter-out utils/haddock/doc,$(BUILD_DIRS))
endif

This creates a problem when people want to build GHC quickly, skipping haddocks generation for GHC, but still want a full-featured GHC installation that includes the haddock program.

Further, there is the extra rule that says Can not build haddock docs when CrossCompiling:

https://gitlab.haskell.org/ghc/ghc/-/blob/6a01e28f4204ec17c587931311711fa76e0ea08d/ghc.mk#L198-204

Given that HADDOCK_DOCS controls both building the program and generating ghc docs, is unclear to me whether this restriction applies to only generating the docs, or whether also _building the haddock program_ is impossible during cross compilation. It would be great if we could cross-compile the haddock` executable.


I propose that:

  1. The comment # Enable pretty hyperlinked sources be changed to explain that it also controls whether the haddock program is built.
  2. Somebody sheds light on whether the cross-compilation restriction applies only to running haddock on GHC, or also to building the haddock executable.
  3. A setting BUILD_HADDOCK_PROGRAM is added, defaulting to YES, so that HADDOCK_DOCS only controls building hyperlinked GHC sources, and so that the haddock program is built during cross-compilation.

CC @angerman @Ericson2314 @Fuuzetsu @bgamari as I believe they know things about cross-compilation and haddock.

To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information