Cabal terminology: sublibraries

Learn
#1

I would like to check that I am using the ‘correct’, current Cabal terminology around ‘sublibraries’ - as I want to be up-to-date and consistent in the naming of certain identifiers used in the Stack project. Is the following ‘accurate’?

A Cabal package can include an optional ‘main’ library and zero or more named ‘sublibraries’. A sublibrary has a ‘visibility’ that is either ‘public’ or ‘private’. (The ‘main’ library is always public.) Before Cabal 3.0, all sublibraries were private and were referred to as ‘internal’ libraries. Before Cabal 2.0, a Cabal package could not include sublibraries.

EDIT (26 Oct 2023): Given the discussion below, I would now recast my text above as follows:

A Cabal package can include zero or more library components, being an optional ‘main’ unnamed library and/or zero or more named ‘subsidiary’ or ‘ancillary’ libraries (abbreviated as ‘sublibraries’). A sublibrary has a ‘visibility’ that is either ‘public’ or ‘private’. (The ‘main’ unnamed library is always public.) Before Cabal 3.0, all sublibraries were private and were, consequently, referred to as ‘internal’ libraries. Before Cabal 2.0, a Cabal package could not include sublibraries.

8 Likes
#2

Thank you for asking. Let’s improve/clarify the terminology together.

I think “sublibrary” is rarely used nowadays and IMHO “component” is better. Libraries, exes, tests and benchmarks are components. One of the library components is the main library, which makes it only a bit special IIRC. The terminology gets more complex once you start talking about backpack mixins as well, but I don’t remember the details.

4 Likes
#3

@Mikolaj, thanks - understood on ‘components’.

For my specific purpose, I am seeking to be clear on the preferred terminology for a library component that is not a ‘main’ library. I think that is ‘sublibrary’ rather than ‘internal library’ (the principal term used in the current Cabal User Guide).

(As an aside, I think the current Cabal User Guide needs a little attention in this area (see 6. Package Description — Cabal 3.10.1.0 User's Guide) - I may propose a pull request.

3 Likes
#4

Yes, “internal library” is at this point much worse for the non-main library than “sublibrary”. If the former got retained in the Cabal User Guide, a correction (and any number of other improvements) would be very much appreciated.

Perhaps I’m biased against “sublibrary” due to an automatic association with terms such as “subset” or “subobject” — there’s no such relation between a “sublibrary” and the main library, nor between their APIs nor anything else. The main library is not a sum of the library components, but just one of them. Am I missing something?

Perhaps “non-main libraries”? "Named libraries’ (IIRC, one can’t explicitly name the main library, even with the name of the package, though that’s effectively that its name is)? “Additional libraries”?

1 Like
#5

what about extra-libraries? AFAIK, the purpose of them is to provide extra utilities which aren’t meant to be the main usage, for example quickcheck instances

2 Likes
#6

In this instance, I think ‘sub’ is being used as an abbreviation of ‘subsidiary’ (in the sense of “supplementary to the ‘main’ unnamed library”), unlike the words that derive from the Latin sub. So, perhaps it should be ‘sub-library’ rather than ‘sublibrary’.

The ‘main’ unnamed library of a package does have a name, in this sense: you can refer to it expressly in a build-depends: by the name of the package that provides it (eg my-package:my-package refers to the ‘main’ unnamed library in package my-package). Given that, I assume that a named sub-library can’t be given the name of its package.

4 Likes
#7

How about “ancillary”.

1 Like
#8

‘subsidiary’

Oh, that suddenly makes sense. I’m fine with “sublibrary” given this etymology. It’s used in a couple of places in the cabal code and docs (in a sane way, too). so perhaps we can stick to it (and eradicate the others, I see @f-a already embarked on this purification quest here: Make “sublibrary” standard terminology in docs by ffaf1 · Pull Request #9371 · haskell/cabal · GitHub). We can have “extra” and “ancillary” as a backup to resolve ambiguities, to give an intuition for the “sublibrary” term, etc.

1 Like
#9

On Matrix there is a proposal which is getting some traction: “named”/“unnamed”. Opinions?

I have my preferences, but the only important things are:
a) we avoid the objectively wrong “internal library”;
b) we take care of this swiftly.

I see contributors with seniority from both Cabal and Stack are partecipating in this discussion, whatever they agree is gospel.

3 Likes