From 5092b8b37825d263ffcdaa1ccdb264ced7d397d6 Mon Sep 17 00:00:00 2001
From: Francesco Gazzetta <fgaz@fgaz.me>
Date: Thu, 11 Aug 2022 16:46:56 +0000
Subject: [PATCH] Document multiple public libraries (#8364)

(cherry picked from commit f4270fc090589b1c997a7cf83dd010261f8cc220)
---
 doc/buildinfo-fields-reference.rst | 11 ++++++++
 doc/cabal-package.rst              | 45 +++++++++++++++++++++---------
 doc/file-format-changelog.rst      |  5 ++++
 3 files changed, 48 insertions(+), 13 deletions(-)

diff --git a/doc/buildinfo-fields-reference.rst b/doc/buildinfo-fields-reference.rst
index 1fdf055f1c7..910bcf6813c 100644
--- a/doc/buildinfo-fields-reference.rst
+++ b/doc/buildinfo-fields-reference.rst
@@ -510,6 +510,17 @@ virtual-modules
         \mathrm{commalist}\left({\left(\mathop{\mathit{upper}}{\left\{ \mathop{\mathit{alpha\text{-}num}}\mid[\mathop{\mathord{``}\mathtt{\text{'}}\mathord{"}}\mathop{\mathord{``}\mathtt{\text{_}}\mathord{"}}] \right\}}^\ast_{}\right)}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}\right)
 
 
+Library fields
+--------------
+
+visibility
+    * Optional field
+    * Documentation of :pkg-field:`library:visibility`
+
+    .. math::
+        \left\{ \mathop{\mathord{``}\mathtt{public}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{private}\mathord{"}} \right\}
+
+
 Package description fields
 --------------------------
 
diff --git a/doc/cabal-package.rst b/doc/cabal-package.rst
index bab41cdc6ef..0aefb2df803 100644
--- a/doc/cabal-package.rst
+++ b/doc/cabal-package.rst
@@ -849,11 +849,18 @@ The library section should contain the following fields:
 
     :since: 3.0
 
-    :default: ``private`` for internal libraries. Cannot be set for public library.
+    :default:
+        ``private`` for internal libraries. Cannot be set for main
+        (unnamed) library, which is always public.
 
-    Cabal recognizes ``public`` and ``private`` here...
+    Can be ``public`` or ``private``.
+    Makes it possible to have multiple public libraries in a single package.
+    If set to ``public``, depending on this library from another package is
+    allowed. If set to ``private``, depending on this library is allowed only
+    from the same package.
 
-    Multiple public libraries...
+    See section on :ref:`Internal Libraries <sublibs>` for examples and more
+    information.
 
 .. pkg-field:: reexported-modules: exportlist
     :since: 1.22
@@ -991,6 +998,18 @@ a real-world use case:
 
       default-language: Haskell2010
 
+**Multiple public libraries**
+
+Cabal 3.0 and later support exposing multiple libraries from a single package
+through the field :pkg-field:`library:visibility`.
+Having multiple public libraries is useful for separating the unit of
+distribution (package) from the unit of buildable code (library).
+For more information about the rationale and some examples, see
+`this blog post <https://fgaz.me/posts/2019-11-14-cabal-multiple-libraries/>`__.
+
+..
+    TODO inline the blog post
+
 
 Opening an interpreter session
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1561,16 +1580,16 @@ system-dependent values for these fields.
     **Library Names**
 
     External libraries are identified by the package's name they're
-    provided by (currently a package can only publicly expose its
-    main library component; in future, packages with multiple exposed
-    public library components will be supported and a syntax for
-    referring to public sub-libraries will be provided).
-
-    In order to specify an intra-package dependency on an internal
-    library component you can use the unqualified name of the
-    library component. Note that locally defined sub-library
-    names shadow external package names of the same name. See section on
-    :ref:`Internal Libraries <sublibs>` for examples and more information.
+    provided by, optionally followed by a colon and the library name
+    (available from ``cabal-version: 3.0``).
+    If the library name is absent, the main (unnamed) library will be used.
+    To refer to the main (unnamed) library explicitly, use the name of the
+    package (``foo:foo``).
+    Multiple libraries from the same package can be specified with the shorthand
+    syntax ``pkg:{lib1,lib2}```.
+
+    See section on :ref:`Internal Libraries <sublibs>` for examples and more
+    information.
 
     **Version Constraints**
 
diff --git a/doc/file-format-changelog.rst b/doc/file-format-changelog.rst
index eee4eed32f7..d2faf6d4a37 100644
--- a/doc/file-format-changelog.rst
+++ b/doc/file-format-changelog.rst
@@ -86,6 +86,11 @@ relative to the respective preceding *published* version.
 ``cabal-version: 3.0``
 ----------------------
 
+* New :pkg-field:`library:visibility` for exposing sublibraries.
+
+* New ``pkg:lib`` and ``pkg:{lib1,lib2}`` syntax in :pkg-field:`build-depends`
+  for depending on public sublibraries from other packages.
+
 * Added the :pkg-field:`extra-dynamic-library-flavours` field to specify non-trivial
   variants of dynamic flavours. It is :pkg-field:`extra-library-flavours` but for
   shared libraries. Mainly useful for GHC's RTS library.