Description
It has come to my attention that the cabal haddock
command could do with some work.
Related issues
- Can't access __HADDOCK_VERSION__ #10818
cabal haddock
rebuilds (all?) the dependencies since cabal-install-3.9.0.0 (or 3.8?) #8707- Come up with a way to build documentation for a package without rebuilding a lot #10111
- Feature request: enable --enable-documentation by default #7462
- Haddock recompilation avoidance #9177
The first thing to do is to clarify the confusion in the codebase about what --enable-documentation
means. At the moment it does two separate things.
- Build HTML documentation for a component
- Build the component with the
-haddock
option.
Requiring (1) implies (2) but not vice versa. A package can be built with -haddock, but documentation not generated yet. It is important to decouple these two concepts inside cabal so that a user can express which combination they want to use.
Further to this, the switch which turns on -haddock
is not implemented correctly, since ./Setup configure
doesn't accept an --enable-documentation
option, to indicate that the component should be built with documentation.
Task 1: Implement --enable-documentation
as a configure time option for ./Setup
.
Task 2: Distinguish between requesting (1) and (2) in cabal-install.
Consider an issue such as #10818, here the user wishes to build documentation with different options to their
normal compilation. In this situation
The configuration step of Cabal should therefore record after the build phase, which artifact will have the suitable information in for generating documentation.
- This will typically be the normal
.hi
files, when no extra haddock options are passed. - If a user wishes to pass different options when compiling in the "haddock" way, a simple "-fno-code" compilation pass can be performed, to produce specific interfaces for generation.
Task 3: Record in the output of ./Setup configure
, which interface file way the
In order to implement task 3, the decision needs to be taken earlier about using -dynamic-too, -haddock etc.
Task 3a: Record in the output of ./Setup configure
the build combinations which ./Setup build
should use to produce the artifacts.
Running cabal haddock
should use the --no-compilation
flag from haddock
when available, and just read information from an interface file. First cabal haddock
runs the build phase, which ensures that the artifact which contains the documentation is available.
The "no-compilation" flag will just read interface files, and mean we can remove much complexity from the command which tries to either guess what build did (now decided by configure), or stop haddock from recompiling modules (provided by --no-compilation).
Task 4: Use --no-compilation
for cabal haddock
when supported.
Then we consider issues such as #8707, there is a tension about whether when running cabal haddock
, you should require documentation for all your dependencies, so that hyperlinks work.
Both uses are valid, but it should be possible to configure this behaviour in the normal global/project/local configuration options.
Task 5: Add a flag to control the transitive behavior of cabal haddock
.
Finally, we should make the build graph more fine-grained so that building documentation for packages does not force you to rebuild everything.
A good first step for this would be to separate the .html and haddock index generation from the building of the package. Then you can build a package with -haddock, and later generate the .html from that if you need it.
This will fix well into Task 4.
Task 6: Separate documentation building from package building in the build graph.
Comments on this plan would be welcome from anyone who has opened any of the other ticket!