Are many public libraries allowed or not?

[lsmor]

What is wrong with the docs?
In section library is very clearly claimed:

Currently, there can only be one publicly exposed library in a package, and its name is the same as package name set by global name field.

Whereas in the visibility section, a contradiction arises:

Can be public or private. Makes it possible to have multiple public libraries in a single package

Additional context
In my personal project I am trying to build two libraries within the same package. The main regular library (libA) and then a library with orphan quickcheck instances (libB). Test suite depends on both. So the cabal file is

cabal-version:      3.8
name: french-deck -- or libA if prefered
...

library  -- the regular main library
  ...

library french-deck-quickcheck -- or libB with Orphan instances
  ...
  build-depends:
      base >=4.16.4.0 && < 5,
      french-deck  -- depends on libA
  visibility: public -- public because I want to import these instances in other package
  
test-suite my-tests
    build-depends:
        base >=4.16.4.0 && < 5,
        french-deck,
        french-deck-quickcheck

I got the error below.

Resolving dependencies...
Error: cabal: Could not resolve dependencies:
[__0] trying: french-deck-0.1.0.0 (user goal)
[__1] trying: french-deck:*test
[__2] unknown package: french-deck-quickcheck (dependency of french-deck
*test)
[__2] fail (backjumping, conflict set: french-deck, french-deck-quickcheck,
french-deck:test)
After searching the rest of the dependency tree exhaustively, these were the
goals I've had most trouble fulfilling: french-deck, french-deck:test,
french-deck-quickcheck

I am using cabal-install-3.8.1.0. At this point I don't know if multiple libraries are allowed or not and I have to define my instances in libA (which I wouldn't like)

[philderbeast]

We can have multiple public libraries, plugins-with-blobs.cabal is an example.

[geekosaur]

There's an overhaul of that part of the documentation in git, fixing the inconsistency among other things. I suspect your problem stems from how you have to refer to such libraries, although I don't recall how you do it correctly off the top of my head.

[philderbeast]

Here's a snippet of referencing public libraries as package-name:library-name from the same example.

  build-depends:
      base >=4.9.1.0 && <5
    , plugins-for-blobs:thoralf-encode
    , plugins-for-blobs:thoralf-plugin
    , plugins-for-blobs:thoralf-plugin-uom
    , plugins-for-blobs:thoralf-theory
    , plugins-for-blobs:uom-quantity
    , plugins-for-blobs:uom-th
    , template-haskell >=2.9

The thoralf-uom.cabal package does the same thing but with dependencies from other packages:

  build-depends:
      base >=4.9.1.0 && <5
    , template-haskell >=2.9
    , thoralf-uom:thoralf-plugin-uom
    , thoralf:thoralf-encode
    , thoralf:thoralf-plugin
    , thoralf:thoralf-theory
    , uom:uom-quantity
    , uom:uom-th

[ulysses4ever]

OP refers to the stable version of the docs. Can someone confirm with the latest version? (There's a switch between the versions on the website)

Examples may be worth adding to the manual.

[lsmor]

I can confirm the problem was syntax. The way to depend on it is libA:libB. Also It is worth mention that, as far as I can test, two libraries must not share hs-source-dirs (trhows parse error on the export list of libA... weird)

cabal-version:      3.8
name: french-deck -- or libA if prefered
...

library  -- the regular main library
  hs-source-dirs: src
  exposed-modules: X, Y

library french-deck-quickcheck -- or libB with Orphan instances
  ...
  build-depends:
      base >=4.16.4.0 && < 5,
      french-deck  -- depends on libA
  visibility: public 
  hs-source-dirs: src/quickcheck  -- This must not!! be just src. It throws an parse error (why?) when building french-deck
  exposed-modules: Z

test-suite my-tests
    build-depends:
        base >=4.16.4.0 && < 5,
        french-deck,
        french-deck:french-deck-quickcheck
  hs-source-dirs: test

[Mikolaj]

@lsmor thank you for the report. Is there anything actionable here after the discussion? Improving the docs? Investigating whether the hs-source-dirs and, if not, opening a ticket about documenting it? Anything else? @lsmor, it's your ticket, you are driving it. :)

[lsmor]

In my opinion:

• the part of the docs which is wrong should be re-written.
• There is a very small note at the end of the library section which actually points out to the package-name:internal-library syntax. That note should be more visible.
• If two libraries share the same hs-source-dirs cabal fails to compile if and only if you import a module from one library to another. Should this be considered a bug or is it expected behaviour? I guess a bug...

I can create a PR with the small modifications in the docs about it but I can't find where the docs are in the repo.

[Mikolaj]

A good plan! Are the docs you have in mind at https://github.com/haskell/cabal/tree/master/doc perchance?

[lsmor]

I see @chreekat and @ffaf1 have already commited (#9371 and #8982) many changes with this regards, but those aren't part of the docs yet. Is there any time-bounded release cycle for docs?

I see the section Multiple public libraries is still very short, and it points to a blog. Also, examples in internal libraries section uses cabal-version: 2.0 / 3.0 which are outdated as cabal-version: 3.4 has a breaking change in the syntax. A good improvement could be

• Update examples of sublibraries
• Extend multiple sublibraries section with an example.

One question: the term sublibrary seems to be the official one now. Is it reseve only for private libraries or public libraries are also named "sub"?

[Mikolaj]

FYI, the newest docs, from the not yet released version of cabal, are at https://cabal.readthedocs.io/en/latest/

[Mikolaj]

There was a long discussion in a ticket or at discord and I remember all libraries but the main one are "sub" now, both private and public.