From d29e487b285d053cd11cbeb3fcc8c6127359971a Mon Sep 17 00:00:00 2001 From: Francesco Ariis Date: Wed, 25 Oct 2023 21:32:53 +0200 Subject: [PATCH 1/2] =?UTF-8?q?Make=20=E2=80=9Csublibrary=E2=80=9D=20stand?= =?UTF-8?q?ard=20terminology=20in=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Substitute “internal library” occourrences with “sublibrary”. --- doc/cabal-package.rst | 24 ++++++++++++------------ doc/file-format-changelog.rst | 6 +++--- doc/setup-commands.rst | 6 +++--- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/doc/cabal-package.rst b/doc/cabal-package.rst index 9b0e970dbd7..75ec9ff40ed 100644 --- a/doc/cabal-package.rst +++ b/doc/cabal-package.rst @@ -184,7 +184,7 @@ Example: A package containing a library and executable programs executable program2 -- A different main.hs because of hs-source-dirs. main-is: main.hs - -- No bound on internal libraries. + -- No bound on a library provided by the same package. build-depends: TestPackage hs-source-dirs: prog2 other-modules: Utils @@ -806,7 +806,7 @@ Library Starting with Cabal 2.0, sub-library components can be defined by setting the ``name`` field to a name different from the current package's name; see - section on :ref:`Internal Libraries ` for more information. By + section on :ref:`Sublibraries ` for more information. By default, these sub-libraries are private and internal. Since Cabal 3.0, these sub-libraries can also be exposed and used by other packages. See the :pkg-field:`library:visibility` field and :ref:`Multiple Public Libraries @@ -852,7 +852,7 @@ The library section should contain the following fields: :since: 3.0 :default: - ``private`` for internal libraries. Cannot be set for main + ``private`` for sublibraries. Cannot be set for main (unnamed) library, which is always public. Can be ``public`` or ``private``. @@ -861,7 +861,7 @@ The library section should contain the following fields: allowed. If set to ``private``, depending on this library is allowed only from the same package. - See section on :ref:`Internal Libraries ` for examples and more + See section on :ref:`Sublibraries ` for examples and more information. .. pkg-field:: reexported-modules: exportlist @@ -903,13 +903,13 @@ section on `build information`_). .. _sublibs: -**Internal Libraries** +**Sublibraries** -Cabal 2.0 and later support "internal libraries", which are extra named +Cabal 2.0 and later support "sublibraries", which are extra named libraries (as opposed to the usual unnamed library section). For example, suppose that your test suite needs access to some internal modules in your library, which you do not otherwise want to export. You -could put these modules in an internal library, which the main library +could put these modules in a sublibrary, which the main library and the test suite :pkg-field:`build-depends` upon. Then your Cabal file might look something like this: @@ -942,11 +942,11 @@ look something like this: build-depends: foo-internal, base default-language: Haskell2010 -Internal libraries are also useful for packages that define multiple +Sublibraries are also useful for packages that define multiple executables, but do not define a publicly accessible library. Internal libraries are only visible internally in the package (so they can only be added to the :pkg-field:`build-depends` of same-package libraries, -executables, test suites, etc.) Internal libraries locally shadow any +executables, test suites, etc.) Sublibraries locally shadow any packages which have the same name; consequently, don't name an internal library with the same name as an external dependency if you need to be able to refer to the external dependency in a @@ -1003,7 +1003,7 @@ a real-world use case: .. note:: For packages using ``cabal-version: 3.4`` or higher, the syntax to - specify an internal library in a ``build-depends:`` section is + specify a sublibrary in a ``build-depends:`` section is ``package-name:internal-library-name``. .. _publicsublibs: @@ -3370,7 +3370,7 @@ just depending on both ``str-impl`` and ``parametrized``: Note that due to technical limitations, you cannot directly define ``Str`` in the ``combined`` library; it must be placed in its own -library (you can use :ref:`Internal Libraries ` to conveniently +library (you can use :ref:`Sublibraries ` to conveniently define a sub-library). However, a more common situation is that your names don't match up @@ -3402,7 +3402,7 @@ the requirements and provided modules renamed to be distinct. parametrized (MyModule as MyModule.BS) requires (Str as Data.ByteString) Intensive use of Backpack sometimes involves creating lots of small -parametrized libraries; :ref:`Internal Libraries ` can be used +parametrized libraries; :ref:`Sublibraries ` can be used to define all of these libraries in a single package without having to create many separate Cabal packages. You may also find it useful to use :pkg-field:`library:reexported-modules` to reexport instantiated diff --git a/doc/file-format-changelog.rst b/doc/file-format-changelog.rst index 4aba3ce6dcd..c3d9aa2dfc8 100644 --- a/doc/file-format-changelog.rst +++ b/doc/file-format-changelog.rst @@ -72,8 +72,8 @@ relative to the respective preceding *published* version. * Dependencies to sublibraries must be specified explicitly, even for current package. - For example: ``build-depends: mypackage:internal-lib`` - This way you can have an internal library with the same + For example: ``build-depends: mypackage:my-sublib`` + This way you can have a sublibrary with the same name as some external dependency. * Remove ``-any`` and ``-none`` syntax for version ranges @@ -218,7 +218,7 @@ relative to the respective preceding *published* version. * Add support for new :pkg-section:`foreign-library` stanza. -* Add support for :ref:`internal library stanzas `. +* Add support for :ref:`sublibrary stanzas `. * New CPP Macro ``CURRENT_PACKAGE_VERSION``. diff --git a/doc/setup-commands.rst b/doc/setup-commands.rst index 0d326e73830..2762b8dcb18 100644 --- a/doc/setup-commands.rst +++ b/doc/setup-commands.rst @@ -144,7 +144,7 @@ This has the following effects: the set of databases via :option:`--package-db` (and related flags): these dependencies are assumed to be up-to-date. A dependency can be explicitly specified using :option:`--dependency` simply by giving the name - of the internal library; e.g., the dependency for an internal library + of the sublibrary; e.g., the dependency for a sublibrary named ``foo`` is given as ``--dependency=pkg-internal=pkg-1.0-internal-abcd``. @@ -612,8 +612,8 @@ Miscellaneous options built; this identifier is passed on to GHC and serves as the basis for linker symbols and the ``id`` field in a ``ghc-pkg`` registration. When a package has multiple components, the actual - component identifiers are derived off of this identifier. E.g., an - internal library ``foo`` from package ``p-0.1-abcd`` will get the + component identifiers are derived off of this identifier. E.g., a + sublibrary ``foo`` from package ``p-0.1-abcd`` will get the identifier ``p-0.1-abcd-foo``. .. option:: --cid=CID From af0d57a2b984e3ded54a5c8c69ae7cb786d85fbe Mon Sep 17 00:00:00 2001 From: Francesco Ariis Date: Thu, 26 Oct 2023 15:48:41 +0200 Subject: [PATCH 2/2] Fix Setup.hs `--dependency` example --- doc/setup-commands.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/setup-commands.rst b/doc/setup-commands.rst index 2762b8dcb18..28cd9e988be 100644 --- a/doc/setup-commands.rst +++ b/doc/setup-commands.rst @@ -146,7 +146,7 @@ This has the following effects: explicitly specified using :option:`--dependency` simply by giving the name of the sublibrary; e.g., the dependency for a sublibrary named ``foo`` is given as - ``--dependency=pkg-internal=pkg-1.0-internal-abcd``. + ``--dependency=Lib:foo=foo-0.1-abc``. - Only the dependencies needed for the requested component are required. Similarly, when :option:`--exact-configuration` is specified,