new-haddock's file monitoring broken

[hvr]

Consider the following simple reproduction instructions:

$ cabal get sort-1.0.0.1 && cd sort-0.0.0.1/
Unpacking to sort-0.0.0.1/

The first invocation of new-haddock works as expected:

$ cabal new-haddock
Resolving dependencies...
In order, the following will be built (use -v for more details):
 - sort-0.0.0.1 (lib) (first run)
Configuring library for sort-0.0.0.1..
Preprocessing library for sort-0.0.0.1..
Running Haddock on library for sort-0.0.0.1..
Haddock coverage:
  67% (  2 /  3) in 'Data.Sort'
  Missing documentation for:
    Module header
Documentation created:
/tmp/sort-0.0.0.1/dist-newstyle/build/x86_64-linux/ghc-8.0.2/sort-0.0.0.1/doc/html/sort/index.html

However, the 2nd invocation of new-haddock rebuilds the documentation (NB: the install-plan wasn't resolved, and the action plan says "(first run)"):

$ cabal new-haddock
In order, the following will be built (use -v for more details):
 - sort-0.0.0.1 (lib) (first run)
Preprocessing library for sort-0.0.0.1..
Running Haddock on library for sort-0.0.0.1..
Haddock coverage:
  67% (  2 /  3) in 'Data.Sort'
  Missing documentation for:
    Module header
Documentation created:
/tmp/sort-0.0.0.1/dist-newstyle/build/x86_64-linux/ghc-8.0.2/sort-0.0.0.1/doc/html/sort/index.html

What's really bad though: if we remove dist-newstyle again, and start with cabal new-build, then new-haddock doesn't generate any documentation at all:

$ rm -rf dist-newstyle/
$ cabal new-build
Resolving dependencies...
In order, the following will be built (use -v for more details):
 - sort-0.0.0.1 (lib) (first run)
Configuring library for sort-0.0.0.1..
Preprocessing library for sort-0.0.0.1..
Building library for sort-0.0.0.1..
[1 of 1] Compiling Data.Sort        ( src/Data/Sort.hs, /tmp/sort-0.0.0.1/dist-newstyle/build/x86_64-linux/ghc-8.0.2/sort-0.0.0.1/build/Data/Sort.o )

$ cabal new-haddock
Up to date

[chris-martin]

I can't seem to get new-haddock to do anything unless I have modified a source file after running cabal new-configure. (cabal version 2.0.0.0)

[int-index]

I studied the implementation of new-haddock and I could not locate the code that would track whether the documentation was generated. It appears that new-haddock tries to reuse the same mechanism for avoiding rebuilds as new-build — naturally, when new-build marks a package as built, new-haddock concludes that there is nothing to do.

Does this analysis sound correct? @hvr @ezyang
Any ideas what would be the proper way to add tracking documentation rebuilds? (I will attempt to implement a fix based on the suggestions).

[ezyang]

@int-index Yes, that sounds accurate to me.

One approach which makes conceptual sense to me is to treat documentation as another "target". There are a few ways to do this:

• Treat "build with docs" as another mode, much like "build with profiling" is a distinct mode unto itself. The good thing is I think this is pretty simple. The downside of doing it this way is that when you ask for docs, you're going to build all of your deps (again)
• Treat "build with docs" as a separate "component", much like how executables and libraries are components. With per-component dependency tracking you can correctly state that documentation build of x depends on documentation build of y. But this is a much more substantial change.

[hvr]

@ezyang fwiw, @alexbiehl and I had vague plans to have haddocks lazily built on a by-need basis, which would probably benefit from considering haddocks a separate component.

PS: related #3535

[int-index]

@hvr This was fixed by #5226, correct? Can we close this?

[gbaz]

optimistically closing