haskell / haskell/cabal

Come up with a way to build documentation for a package without rebuilding a lot

Open
#10,111 1 comment 2 reactions 0 assignees View on GitHub
re: enable-documentation type: enhancement
Dominant language
Haskell
Stars
1.7k
Forks
750
Avg merge
4d 3h
Merged PRs (30d)
28

Description

**Describe the feature request**
At the moment, when cabal builds a package, it decides first whether or not it will build it with documentation, and then it builds the entire package (possibly including documentation) and puts it into a single location in the cabal store. (So: the choice of whether or not to build documentation affects the store hash)

This means that deciding to build a package with documentation when it was not built before means:
1. Rebuilding that package
2. Rebuilding every downstream package (including local ones that depend on it), since we now consider it to be a different package

This is especially painful in the post-hi-haddock world, where we really _don't_ need to rebuild a package in order to build the HTML documentation for it (see discussion [here](https://github.com/haskell/cabal/pull/9177#issuecomment-2166112125)).

There are a few possible solutions:
1. Allow storing the haddock in a separate place in the store from the interface/object files. This would decouple the two, so building the haddock would just build some new things and not affect the existing things (thus preventing cabal from thinking it needs to rebuild dependent packages). See [here](https://github.com/haskell/cabal/issues/8725#issuecomment-1523244372).
2. Always build haddock for non-local packages. Now that a lot of the work is done during GHC's compilation pipeline, I think it's probably fairly cheap to do the final step of generating the docs. In an ideal world we could also do it in parallel with starting to build the next downstream package. I'm not sure how we would configure this, and maybe it's surprising.

Contributor guide

Open the contributing guide

Research direction

Start by reading the discussion linked from cabal issue 10111, including issue 8725 and Cabal PR 9177, to understand the proposed store and Haddock behavior. Define and implement a selected approach so documentation can be built without rebuilding the package or its downstream dependents, then verify that both package artifacts and documentation remain usable.

Written by the indexing model from the issue text.

Assessment

Tech stack
haskell
Domain
build-system
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.