Best practices for public Cabal sublibraries

Learn
#1

Hi, I wonder what the best practices are when using “subsidiary libraries.” (At least, that seems to be what they are called: https://discourse.haskell.org/t/cabal-terminology-sublibraries/7940.)

In particular, how to deal with version bounds. When I have N public sublibraries and N executables, it seems like I have to repeat many of the bounds to make cabal check happy.

Otherwise, it is a great feature, and I am happy not to compile pandoc if the given library/executable does not need it. :grinning_face_with_smiling_eyes:

1 Like
#2

Hello Ondřej.

If you are importing a sublibrary into your main — or other — library, bounds specifications should be inherited. Example: specifying bounds on megaparsec in swarm-lang will make warnings go away from swarm-lang, but also from swarm-tournament, etc.

Otherwise, common stanzas could be useful.

1 Like
#3

The version bounds issue is exactly what inspired [RFC] `default-package-bounds` · Issue #9569 · haskell/cabal · GitHub. There is an implementation, but it seems to have got a bit stuck.

#4

What do you mean by this?

Edit: ah, it appears swarm-doc depends on pandoc, but no other component: swarm/swarm.cabal at 90d3aa953580ffd05414617cc17473abb1de551d · swarm-game/swarm · GitHub

#5

I would probably use common stanzas. (It would be nice to have some kind of VSCode lens for displaying the “expanded” form of a library, with the common stanzas resolved.)

It’s interesting that all the libraries provided by swarm are public sub-libraries and, as such, no Haddocks are generated for them. Is there some Haddock issue for multiple sub-library support? I couldn’t find it.

#6

You can already generate haddocks for a sublibrary with cabal haddock lib:sublib. Presumably the --(use|gen)-(contents|index) options can be used to merge these haddocks and the results manually uploaded to hackage, though it’s a shame this isn’t automated.

2 Likes
#7

Thanks for the tips. :+1: I tried the common stanzas and will look into those haddocks.

#8

They do get generated, they’re just hard to find:

https://hackage.haskell.org/package/swarm-0.6.0.0/docs/Swarm-Language-Syntax.html

Here’s how I found that:

3 Likes
#9

We need a contributor or volunteer to work on the hackage codebase so it can parse out, display and generate links for multiple sublibraries.

There was some work here, but there were open design questions and the PR never landed: UI for multiple public libraries · Issue #1218 · haskell/hackage-server · GitHub

In the meantime, you can just append /docs to a url to get a directory listing of the generated docs for the sublibraries, like so: swarm: 2D resource gathering game with programmable robots

4 Likes