7

If I do a cabal build on my library, then change a file, the next time I run cabal build, I only have to recompile files affected by the changes. I'm not getting the same behavior with the cabal haddock command: when I run it after changing a file, cabal/haddock ends up throwing out all of the previous work and starting from scratch. This is rather time consuming; is there a way to get differential updates to documentation?

Here's a dump of the command cabal issues to generate the documentation.

crockeea
  • 21,651
  • 10
  • 48
  • 101
  • I don't remember: does haddock fail to build if you link to something that doesn't exists? Like using `'MyModule'` and you have no `MyModule` available. Because if it simply gives a warning and continue to run then the behaviour is required: any change to existing files or addition of files could modify the output of the other modules' documentation. – Bakuriu Sep 21 '15 at 18:18
  • I believe a lot of time is spent rebuilding the global index pages. A lot of time could be saved if those pages were not built. Use the -v flag with cabal to see what haddock commands are being executed. – ErikR Sep 21 '15 at 18:25
  • @Bakuriu If I add a random `import ModuleDoesNotExist` to the top of a file, haddock short circuits and does not output any documentation. If I force any other sort of compile error (e.g. a syntax error), haddock outputs documentation up to the module with the error, but then short circuits and does not output documentation for the rest of the modules. – crockeea Sep 21 '15 at 18:26
  • @user5402 Added link in question. – crockeea Sep 21 '15 at 19:17
  • How much time is it taking? As an experiment I built the docs for parsec with `cabal haddock` and it only took a few seconds. However, if I run `cabal install` it will take a lot longer because the global index files have to be regenerated. So how big is your code? Exactly what commands are you running and how long are these commands taking? – ErikR Sep 22 '15 at 00:34
  • @user5402 I'm not running `cabal install` at all. `cabal clean; configure; haddock` takes 41 seconds, as does `cabal clean; configure; build; haddock`. The library is quite large. – crockeea Sep 22 '15 at 01:14
  • how long is the `cabal haddock` command taking? – ErikR Sep 22 '15 at 02:45
  • @user5402 The 41 seconds was just for the `cabal haddock` part, in both cases. Building takes a long time on its own, but I didn't include that time above. – crockeea Sep 22 '15 at 02:59

1 Answers1

1

processModules documentation says:

Create Interfaces and a link environment by typechecking the list of modules using the GHC API and processing the resulting syntax trees.

And that is the core function of haddock. So ATM the answer your question is No.

cabal build doesn't help cabal haddock at all, as haddock type-checks modules with different parameters (e.g. __HADDOCK__ CPP variable enabled)

Making reliable incremental haddock generation is hard, as the code later in the dependency graph can alter the modules documentation previous to that point: particularly the instances listings. Probably one could dump module interfaces.

Looking at the code of processModules the first step is something that could be possible to do incrementally, rest is using global information.

Try turn verbosity to the max i.e. --haddock-options=--verbosity=2 and check how much time is spent between Creating interfaces... and Attaching instances....

phadej
  • 11,947
  • 41
  • 78
  • `cabal haddock --haddock-options=--verbosity=2` doesn't print anything about "creating interfaces" or "attaching instances". – crockeea Sep 29 '15 at 13:52
  • @Erik, it seems you have to give `-v3` to `cabal` to get `haddock` verbose output. OTOH it seems that most time is spend in between `Creating interfaces...` and `Attacing instances`. Maybe there is an optimisation opportunity. – phadej Sep 29 '15 at 14:09
  • "Attaching instances" and "Creating interfaces" are both basically instantaneous, but the "Checking module" step takes a noticeable amount of time for each module. – crockeea Sep 29 '15 at 14:22
  • Ok. There is an intermediate type [`TypecheckedModule`](https://github.com/haskell/haddock/blob/master/haddock-api/src/Haddock/Interface.hs#L168) which looks like it could be possible to serialise to disk and back, but I don't know enough about GHC internals if something is happening in `Ghc` monad, that need to be preserved as well. It's better to turn to `ghc-dev` or `haddock` issue tracker from here. – phadej Sep 29 '15 at 14:31