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? 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?
* Brian Lewis
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
On 2013.07.13, at 23:15, Roman Cheplyaka wrote:
1. Why exactly does haddock fail?
I think it never actually tries to build the Haddock docs for the actual package of interest because its dependencies failed to build. Here's the GLFW-b build log: http://hackage.haskell.org/packages/archive/GLFW-b/1.0.0/logs/failure/ghc-7.... ... Running Haddock for bindings-DSL-1.0.16... ... Running Haddock for th-lift-0.5.5... ... * Missing C library: Xxf86vm These messages are from the build of bindings-GLFW, a dependency of GLFW-b. Due to the missing library, bindings-GLFW's build fails. So GLFW-b's does too. I guess I think the build failure should be noted, but that Hackage should go on and build the docs anyway.
* Brian Lewis
On 2013.07.13, at 23:15, Roman Cheplyaka wrote:
1. Why exactly does haddock fail?
I think it never actually tries to build the Haddock docs for the actual package of interest because its dependencies failed to build.
Here's the GLFW-b build log: http://hackage.haskell.org/packages/archive/GLFW-b/1.0.0/logs/failure/ghc-7....
... Running Haddock for bindings-DSL-1.0.16... ... Running Haddock for th-lift-0.5.5... ... * Missing C library: Xxf86vm
These messages are from the build of bindings-GLFW, a dependency of GLFW-b. Due to the missing library, bindings-GLFW's build fails. So GLFW-b's does too.
I guess I think the build failure should be noted, but that Hackage should go on and build the docs anyway.
Ah, yes. This may be a bit more complicated than it seems, due to the way Cabal works. Let's say you've built the docs for this library. Now you have to install it, so that its reverse dependencies can reference it. Installation involves registering the package, so that Cabal can later see which packages are installed. Here's the catch: package databases are maintained by compilers, not by Cabal. In the common case this means GHC. (Unfortunately, haddock is not a separate compiler, which would be a more proper solution.) So we must register the package with GHC. But then we cannot distinguish between real and docs-only packages. Cabal and GHC would expect package to be installed, and would happily attempt to build other packages against it, and fail miserably. Roman
participants (2)
-
Brian Lewis -
Roman Cheplyaka