Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

cabal haddock fails with internal libraries #4969

Closed
shlevy opened this issue Dec 22, 2017 · 12 comments · Fixed by #5253
Closed

cabal haddock fails with internal libraries #4969

shlevy opened this issue Dec 22, 2017 · 12 comments · Fixed by #5253
Labels
Cabal: cmd/haddock priority: high 🔥 type: bug
Milestone
Obsoleted by nix-...

Comments

@shlevy
Copy link

shlevy commented Dec 22, 2017

When using internal libraries, cabal haddock seems to fail unconditionally:

$ cabal haddock
Preprocessing library 'internal' for internal-library-test-0.1.0.0..
Running Haddock on library 'internal' for internal-library-test-0.1.0.0..
Haddock coverage:
   0% (  0 /  2) in 'Internal'
  Missing documentation for:
    Module header
    foo (internal/Internal.hs:3)
Documentation created: dist/doc/html/internal-library-test/index.html
Preprocessing library for internal-library-test-0.1.0.0..
Running Haddock on library for internal-library-test-0.1.0.0..
cabal: internal error when calculating transitive package dependencies.
Debug info: []
@shlevy shlevy mentioned this issue Dec 22, 2017
Closed
@23Skidoo
Copy link
Member

See also #4215, #1085 and #1919. Would be nice to fix all these in one go...

@hvr
Copy link
Member

hvr commented Dec 22, 2017 •
edited

fwiw, I managed to generate haddocks back then in July for http://hackage.haskell.org/package/haddock-library

EDIT: I just tried again (with cabal HEAD), it still works just fine!

$ cabal get haddock-library-1.4.5 && cd haddock-library-1.4.5

$ cabal new-haddock --haddock-for-hackage

results in https://gist.github.com/3d1c22e67a75c3e7117f64b8a03d7a3b

@23Skidoo
Copy link
Member

Hmm, so broken only with old-build? Interesting.

@shlevy
Copy link
Author

shlevy commented Jan 21, 2018

Is the plan to not fix this and wait for new-haddock?

@ezyang
Copy link
Contributor

ezyang commented Jan 21, 2018

Yeah, I'm pretty OK with just saying "use new-build" for this one.

@shlevy shlevy closed this as completed Jan 21, 2018
@pikajude pikajude mentioned this issue Mar 9, 2018
Closed
@peti
Copy link
Collaborator

peti commented Mar 15, 2018 •
edited 

$ runhaskell Setup.hs new-haddock
unrecognised command: new-haddock (try --help)

Now what?

This bug is quite nasty and it effectively prevents all kinds of distributors like Nix and openSUSE from generating Haddock documentation for any package that uses an internal library. 😞

peti added a commit to NixOS/cabal2nix that referenced this issue Mar 15, 2018
@peti
Disable Haddock phase for packages with internal libraries.
7017487 
haskell/cabal#4969 means that Haddock cannot generate
documentation for packages that use internal libraries.
@shlevy shlevy reopened this Mar 15, 2018
@hvr
Copy link
Member

hvr commented Mar 15, 2018 •
edited

@peti There's not going to be a Setup.hs new-haddock just as there isn't going to be a Setup.hs new-build command, as that's a low-level interface (c.f. "plumbing" in the Git model) which cabal new-haddock (the "porcelaine") builds upon.

TLDR, you need to invoke Setup.hs haddock for each component individually, similiar to how cabal new-haddock does.

@peti
Copy link
Collaborator

peti commented Mar 15, 2018

You need to invoke Setup.hs haddock for each component individually, similiar to how cabal new-haddock does.

It would be super nice if runhaskell Setup.hs haddock would to that for me. I realize that is a decent work-around for an issue the old(er) Cabal code has, but still it feels awkward that I (and all other people who want to distribute Haskell packages to end-users) now have to implement this work-around in our build infrastructure. If we'd just get a fixed version of Cabal, then this issue would be flat-out solved for everyone.

@hvr
Copy link
Member

hvr commented Mar 15, 2018 •
edited

It would be super nice if runhaskell Setup.hs haddock would to that for me.

Well, I'm not saying we wouldn't welcome a patch for that. But please understand the priority for some of us here is getting the overdue cabal new-build feature out of the door to become cabal's default mode of operation; so we somewhat lack the bandwidth to address things (especially when they appear like issues which may become obsolete/moot by cabal new-build anyway) ourselves that don't contribute to that goal and may even cause further delays.

@shlevy
Copy link
Author

shlevy commented Mar 15, 2018

@hvr So if I'm understanding correctly, in the example above we could do Setup haddock internal then Setup haddock and all would be well?

@peti
Copy link
Collaborator

peti commented Mar 16, 2018 •
edited

@hvr,

You need to invoke Setup.hs haddock for each component individually.

I tried to do that, but I couldn't figure out what exactly you mean. The haddock command does not take any argument that indicates which component to process:

$ runhaskell Setup.hs haddock --help    
Generate Haddock HTML documentation.

Usage: Setup.hs haddock [FLAGS]
...

Now, there are flags that I could pass, but none of them seem to do what you suggested we should do. If you have the chance, could you please post a slightly more verbose explanation or maybe even a complete example of how to build the documentation for, say stylish-cabal-0.4.0.0 with the normal Setup haddock command?

peti added a commit to peti/cabal2spec that referenced this issue Mar 21, 2018
@peti
Don't build Haddock documentation for packages that use sub-libraries.
f571b67 
This is necessary to avoid haskell/cabal#4969.
peti added a commit to peti/cabal2spec that referenced this issue Mar 21, 2018
@peti
Don't build Haddock documentation for packages that use sub-libraries.
838c474 
This is necessary to avoid haskell/cabal#4969.
@peti peti mentioned this issue Mar 23, 2018
Closed
@st3ll1s st3ll1s mentioned this issue Mar 24, 2018
Closed
@alexbiehl alexbiehl mentioned this issue Apr 3, 2018
Merged
4 tasks
@ryanreich ryanreich mentioned this issue Apr 27, 2018
Closed
@nrolland
Copy link

nrolland commented Nov 30, 2018 •
edited

Any work-around for haddock-library when using stack ? haddock-library-1.5.0.2 is on LTS-12.20, which is potentially used by many, and it breaks the documentation generation for an entire project AFAICT, unlike nixpkgs which just dontHaddock the culprits

michaelpj added a commit to michaelpj/plutus that referenced this issue Jan 23, 2019
@michaelpj
Make the Plutus Tx plugin an internal library
afe1176 
The documentation for `addCorePlugin` says it has to be in a separate
package to the plugin. However it appears that in GHC's eyes internal
libraries in a Cabal package are separate packages, so we can hide all
of this in a single package, which is much nicer.

We then have to do some shennanigans to get doctest to work. The normal
tests work fine, since Cabal registers the built internal library as a
package, and that's fine. But doctest interprets things, which *doesn't*
work.

Now, I initially tried to just pass the appropriate `-package-db`
arguments to `doctest`, but in doing so I hit what appears to be a [Cabal
bug with internal libraries](haskell/cabal#5857).
However, somehow `cabal repl` and friends seem to get around this, and
fortunately there is now a `cabal doctest` command, which amazingly
also seems to pass the right set of obscure flags. So we use that.

Finally, in an extremely irritating discovery, apparently [Haddock
doesn't work with internal libraries]
(haskell/cabal#4969) (possibly fixed in a
newer Cabal, who knows), so I ended up having to exclude `plutus-tx`
from Haddock generation for now.
michaelpj added a commit to michaelpj/plutus that referenced this issue Jan 23, 2019
@michaelpj
Make the Plutus Tx plugin an internal library
fc73185 
The documentation for `addCorePlugin` says it has to be in a separate
package to the plugin. However it appears that in GHC's eyes internal
libraries in a Cabal package are separate packages, so we can hide all
of this in a single package, which is much nicer. We can then organize
things a bit more neatly inside.

We then have to do some shennanigans to get doctest to work. The normal
tests work fine, since Cabal registers the built internal library as a
package, and that's fine. But doctest interprets things, which *doesn't*
work.

Now, I initially tried to just pass the appropriate `-package-db`
arguments to `doctest`, but in doing so I hit what appears to be a [Cabal
bug with internal libraries](haskell/cabal#5857).
However, somehow `cabal repl` and friends seem to get around this, and
fortunately there is now a `cabal doctest` command, which amazingly
also seems to pass the right set of obscure flags. So we use that.

Finally, in an extremely irritating discovery, apparently [Haddock
doesn't work with internal libraries]
(haskell/cabal#4969) (possibly fixed in a
newer Cabal, who knows), so I ended up having to exclude `plutus-tx`
from Haddock generation for now.
michaelpj added a commit to michaelpj/plutus that referenced this issue Jan 23, 2019
@michaelpj
Make the Plutus Tx plugin an internal library
fd56d51 
The documentation for `addCorePlugin` says it has to be in a separate
package to the plugin. However it appears that in GHC's eyes internal
libraries in a Cabal package are separate packages, so we can hide all
of this in a single package, which is much nicer. We can then organize
things a bit more neatly inside.

We then have to do some shennanigans to get doctest to work. The normal
tests work fine, since Cabal registers the built internal library as a
package, and that's fine. But doctest interprets things, which *doesn't*
work.

Now, I initially tried to just pass the appropriate `-package-db`
arguments to `doctest`, but in doing so I hit what appears to be a [Cabal
bug with internal libraries](haskell/cabal#5857).
However, somehow `cabal repl` and friends seem to get around this, and
fortunately there is now a `cabal doctest` command, which amazingly
also seems to pass the right set of obscure flags. So we use that.

Finally, in an extremely irritating discovery, apparently [Haddock
doesn't work with internal libraries]
(haskell/cabal#4969) (possibly fixed in a
newer Cabal, who knows), so I ended up having to exclude `plutus-tx`
from Haddock generation for now.
michaelpj added a commit to michaelpj/plutus that referenced this issue Jan 23, 2019
@michaelpj
Make the Plutus Tx plugin an internal library
da47636 
The documentation for `addCorePlugin` says it has to be in a separate
package to the plugin. However it appears that in GHC's eyes internal
libraries in a Cabal package are separate packages, so we can hide all
of this in a single package, which is much nicer. We can then organize
things a bit more neatly inside.

We then have to do some shennanigans to get doctest to work. The normal
tests work fine, since Cabal registers the built internal library as a
package, and that's fine. But doctest interprets things, which *doesn't*
work.

Now, I initially tried to just pass the appropriate `-package-db`
arguments to `doctest`, but in doing so I hit what appears to be a [Cabal
bug with internal libraries](haskell/cabal#5857).
However, somehow `cabal repl` and friends seem to get around this, and
fortunately there is now a `cabal doctest` command, which amazingly
also seems to pass the right set of obscure flags. So we use that.

Finally, in an extremely irritating discovery, apparently [Haddock
doesn't work with internal libraries]
(haskell/cabal#4969) (possibly fixed in a
newer Cabal, who knows), so I ended up having to exclude `plutus-tx`
from Haddock generation for now.
@michaelpj michaelpj mentioned this issue Jan 23, 2019
Merged
michaelpj added a commit to michaelpj/plutus that referenced this issue Jan 23, 2019
@michaelpj
Make the Plutus Tx plugin an internal library
953896f 
The documentation for `addCorePlugin` says it has to be in a separate
package to the plugin. However it appears that in GHC's eyes internal
libraries in a Cabal package are separate packages, so we can hide all
of this in a single package, which is much nicer. We can then organize
things a bit more neatly inside.

We then have to do some shennanigans to get doctest to work. The normal
tests work fine, since Cabal registers the built internal library as a
package, and that's fine. But doctest interprets things, which *doesn't*
work.

Now, I initially tried to just pass the appropriate `-package-db`
arguments to `doctest`, but in doing so I hit what appears to be a [Cabal
bug with internal libraries](haskell/cabal#5857).
However, somehow `cabal repl` and friends seem to get around this, and
fortunately there is now a `cabal doctest` command, which amazingly
also seems to pass the right set of obscure flags. So we use that.

Finally, in an extremely irritating discovery, apparently [Haddock
doesn't work with internal libraries]
(haskell/cabal#4969) (possibly fixed in a
newer Cabal, who knows), so I ended up having to exclude `plutus-tx`
from Haddock generation for now.
michaelpj added a commit to michaelpj/plutus that referenced this issue Jan 23, 2019
@michaelpj
Make the Plutus Tx plugin an internal library
3b28494 
The documentation for `addCorePlugin` says it has to be in a separate
package to the plugin. However it appears that in GHC's eyes internal
libraries in a Cabal package are separate packages, so we can hide all
of this in a single package, which is much nicer. We can then organize
things a bit more neatly inside.

We then have to do some shennanigans to get doctest to work. The normal
tests work fine, since Cabal registers the built internal library as a
package, and that's fine. But doctest interprets things, which *doesn't*
work.

Now, I initially tried to just pass the appropriate `-package-db`
arguments to `doctest`, but in doing so I hit what appears to be a [Cabal
bug with internal libraries](haskell/cabal#5857).
However, somehow `cabal repl` and friends seem to get around this, and
fortunately there is now a `cabal doctest` command, which amazingly
also seems to pass the right set of obscure flags. So we use that.

Finally, in an extremely irritating discovery, apparently [Haddock
doesn't work with internal libraries]
(haskell/cabal#4969) (possibly fixed in a
newer Cabal, who knows), so I ended up having to exclude `plutus-tx`
from Haddock generation for now.
MangoIV pushed a commit to MangoIV/plutus-contract that referenced this issue Sep 3, 2022
@michaelpj
Make the Plutus Tx plugin an internal library
4f9e450 
The documentation for `addCorePlugin` says it has to be in a separate
package to the plugin. However it appears that in GHC's eyes internal
libraries in a Cabal package are separate packages, so we can hide all
of this in a single package, which is much nicer. We can then organize
things a bit more neatly inside.

We then have to do some shennanigans to get doctest to work. The normal
tests work fine, since Cabal registers the built internal library as a
package, and that's fine. But doctest interprets things, which *doesn't*
work.

Now, I initially tried to just pass the appropriate `-package-db`
arguments to `doctest`, but in doing so I hit what appears to be a [Cabal
bug with internal libraries](haskell/cabal#5857).
However, somehow `cabal repl` and friends seem to get around this, and
fortunately there is now a `cabal doctest` command, which amazingly
also seems to pass the right set of obscure flags. So we use that.

Finally, in an extremely irritating discovery, apparently [Haddock
doesn't work with internal libraries]
(haskell/cabal#4969) (possibly fixed in a
newer Cabal, who knows), so I ended up having to exclude `plutus-tx`
from Haddock generation for now.
kayvank pushed a commit to input-output-hk/marconi that referenced this issue Mar 11, 2023
@michaelpj
Make the Plutus Tx plugin an internal library
b84950c 
The documentation for `addCorePlugin` says it has to be in a separate
package to the plugin. However it appears that in GHC's eyes internal
libraries in a Cabal package are separate packages, so we can hide all
of this in a single package, which is much nicer. We can then organize
things a bit more neatly inside.

We then have to do some shennanigans to get doctest to work. The normal
tests work fine, since Cabal registers the built internal library as a
package, and that's fine. But doctest interprets things, which *doesn't*
work.

Now, I initially tried to just pass the appropriate `-package-db`
arguments to `doctest`, but in doing so I hit what appears to be a [Cabal
bug with internal libraries](haskell/cabal#5857).
However, somehow `cabal repl` and friends seem to get around this, and
fortunately there is now a `cabal doctest` command, which amazingly
also seems to pass the right set of obscure flags. So we use that.

Finally, in an extremely irritating discovery, apparently [Haddock
doesn't work with internal libraries]
(haskell/cabal#4969) (possibly fixed in a
newer Cabal, who knows), so I ended up having to exclude `plutus-tx`
from Haddock generation for now.
kayvank pushed a commit to input-output-hk/marconi that referenced this issue Mar 22, 2023
@michaelpj
Make the Plutus Tx plugin an internal library
f3de265 
The documentation for `addCorePlugin` says it has to be in a separate
package to the plugin. However it appears that in GHC's eyes internal
libraries in a Cabal package are separate packages, so we can hide all
of this in a single package, which is much nicer. We can then organize
things a bit more neatly inside.

We then have to do some shennanigans to get doctest to work. The normal
tests work fine, since Cabal registers the built internal library as a
package, and that's fine. But doctest interprets things, which *doesn't*
work.

Now, I initially tried to just pass the appropriate `-package-db`
arguments to `doctest`, but in doing so I hit what appears to be a [Cabal
bug with internal libraries](haskell/cabal#5857).
However, somehow `cabal repl` and friends seem to get around this, and
fortunately there is now a `cabal doctest` command, which amazingly
also seems to pass the right set of obscure flags. So we use that.

Finally, in an extremely irritating discovery, apparently [Haddock
doesn't work with internal libraries]
(haskell/cabal#4969) (possibly fixed in a
newer Cabal, who knows), so I ended up having to exclude `plutus-tx`
from Haddock generation for now.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Cabal: cmd/haddock priority: high 🔥 type: bug
Projects
None yet
Milestone
Obsoleted by nix-local-build (3.0)
Development

Successfully merging a pull request may close this issue.

Haddock: add internal libraries to package index alexbiehl/cabal
6 participants
@ezyang @peti @nrolland @23Skidoo @hvr @shlevy