[Haskell-cafe] build failure on Hackage

[Roman Cheplyaka]

* Brian Lewis <brian at lorf.org> [2013-07-13 14:30:01-0500]
> I maintain a library that, on Linux, needs libXxf86vm to build. The
> server where Hackage runs doesn't have that library, so the build fails.
> I think this is reasonable -- that box can't possibly have all the
> libraries various packages might need. But the build failure seems to
> cause the Haddock docs to not be generated. Why?

This is a consequence of how haddock works. It uses GHC API, which has
to "compile" modules before haddock can process them.

> My understanding is, if someone specifies my library as a build
> dependency, my library's build failure will also cause the docs for
> their package not to be built. I think my library will kill the Hackage
> Haddock docs for any other package that depends on it, due to a build
> error that's not even meaningful.
> 
> What can I do?

1. Why exactly does haddock fail? IINM, the absence of library itself
   (i.e. an .a or .so file) shouldn't be a problem, as haddock doesn't
   do linking. If the problem is due to an absent include file, perhaps
   you can bundle it with your package for the sake of generating
   documentation?

   To generate documentation without linking, do

     cabal configure && cabal haddock

   instead of
    
     cabal install

2. You can use standalone-haddock to generate the documentation on a
   system where the library is installed and then upload it to your own
   web host. Unfortunately, this won't solve the problem with reverse
   deps (but they could do the same).

3. If we ever switch to Hackage 2, this problem should be solved by
   user-uploadable docs.

Roman