How to build Haddock documentation quickly?
Norman Ramsey
nr at cs.tufts.edu
Fri Nov 19 18:34:14 UTC 2021
> Hi Norman,
>
> Could you see if the command-line described here is of any help?
> https://gitlab.haskell.org/ghc/ghc/-/issues/17929#building-the-docs
>
> Particularly the "--freeze1 --flavour=Quick" bit.
It was reasonably fast, but it doesn't build the documentation I'm
interested in. The file I wish to rebuild is
_build/docs/html/libraries/ghc/GHC-Tc-Gen-Foreign.html
and the command recommended there is
hadrian/build -j --freeze1 --flavour=Quick _build/docs/html/libraries/base/base.haddock
Just adding `--freeze= --flavour=Quick` to my original command may
have helped a little; after editing GHC/Tc/Gen/Foreign.hs, my build
time was reduced to 3 minutes 11 seconds.
I also took a flyer on these two commands:
hadrian/build -j --freeze1 --flavour=Quick _build/docs/html/libraries/ghc/GHC-Tc-Gen-Foreign.html
hadrian/build -j _build/docs/html/libraries/ghc/GHC-Tc-Gen-Foreign.html
But neither of these commands rebuilt the file.
I also tried
hadrian/build -j --freeze1 --flavour=Quick --docs=no-sphinx docs
which succeeded but took 3 minutes 18 seconds.
I'm more than willing to dive into Hadrian and figure out how it works.
I could even add a new target to build just what I'm interested in.
But I would need help. I've spent some time poking around the `doc`
directory, and I've read the Shake papers (and some of Andrei's work)
but I've never used these tools myself. I got as far as
$GHC/hadrian/src/Rules/Documentation.hs, which led me to try the
`docs-haddock` target, and I got a slightly better result:
the document is rebuilt in 2 minutes 30 seconds.
There has to be a better way. I suppose I could try to come up with a
set of options to `haddock` and to run it directly. But maybe someone
can suggest another idea?
Is there a command-line option to Hadrian that will get it to show
every external command ("builder"?) as it is executed?
Norman
> Le 18/11/2021 à 21:06, Norman Ramsey a écrit :
> > In service of #20528, I'm trying to clean up some Haddock
> > documentation in the GHC sources. The only command I know is
> >
> > ./hadrian/build -j _build/docs/html/index.html
> >
> > It turns out that if I change Haddock comments in one file
> > (GHC/Tc/Gen/Foreign.hs), rebuilding the HTML takes a minute
> > and a quarter. That's a little long. (And I had one build
> > take over four minutes, which is even longer.)
> >
> > What tricks can I use to speed up this process? Might there be a way
> > to run Haddock directly until things are to my liking?
More information about the ghc-devs
mailing list