Re #638 Add docs on deps on named libs in same package, post-Cabal 3.2

[mpilgrem]

See:

• cabal-version >= 3.4 makes internal-libraries fail #638

[sol]

Hmm, this is not really in line with how Hpack currently works. A user of Hpack shouldn't usually be concerned about cabal-version.

Consider this:

• a user has a package that uses internal libraries
• at a later point the user adds extra-files to the package and as a result the package won't compile anymore

That's not obvious and feels wrong. Not sure how we should address this.

---

Idk, cabal feels like an over-engineered Frankenstein, and nobody is closing the flood gates.

[mpilgrem]

@sol, two possible dimensions to #638 are:

• 'documentation' of the current state of affairs (what this pull request seeks to address, only); and
• 'Hpack functionality'.

The underlying problem seems to me to be that when named libraries were introduced in Cabal 2.0, insufficient thought was given to possible future ramifications, and that was only sorted out in Cabal 3.4. It has also taken a while for Cabal's own documentation to catch up with its functionality.

I am conscious that the Hpack reference documentation seeks to not duplicate Cabal's own documentation. However, as a Hpack user had been caught by this, and it could be fixed with one sentence, it seemed to me that the additional of a sentence was tolerable.

I did think about 'Hpack functionality' but concluded that, given the Cabal 2.0 to 3.2 interlude, there was no way (or, at least, no pleasant way) for Hpack to know if a user really wanted to specify a dependency on a named library of the same package or the main library of another package. However, now that Cabal 3.4 is, itself, 'history' (as we now have Cabal 3.16), one approach might be:

"If a Hpack user specifies internal-libraries, then force cabal-version >= 3.4 and document that package name:library name is required for dependencies on named libraries."

In that case, there would no longer be any ambiguity from a Hpack perspective - but it would be a break from the past. Users expecting the Cabal 2.0 to 3.2 behaviour would encounter messages like:

> stack build
testNamedLibs> configure (lib + sub-lib + exe)
Configuring testNamedLibs-0.1.0.0...
Error: [Cabal-8010]
Encountered missing or private dependencies:
    my-named-library