From 1d17627915977269bc5ac83724d39d5124a4b206 Mon Sep 17 00:00:00 2001
From: Max Amanshauser <max@lambdalifting.org>
Date: Sun, 16 Oct 2022 15:16:18 +0200
Subject: [PATCH] Document extra-packages a bit better and clean up related
entries (closes #5448) (#8535)
---
doc/cabal-project.rst | 6 ++++--
doc/nix-local-build.rst | 13 ++++++-------
2 files changed, 10 insertions(+), 9 deletions(-)
diff --git a/doc/cabal-project.rst b/doc/cabal-project.rst
index 4ba2c26f87..863ad1bf3c 100644
--- a/doc/cabal-project.rst
+++ b/doc/cabal-project.rst
@@ -127,8 +127,10 @@ project are:
.. cfg-field:: extra-packages: package list with version bounds (comma separated)
:synopsis: Adds external packages as local
- :strike:`Specifies a list of external packages from Hackage which
- should be considered local packages.` (Not implemented)
+ Specifies a list of external packages from Hackage, which
+ should be considered local packages. The motivation for
+ :cfg-field:`extra-packages` is making libraries that are not
+ dependencies of any package in the project available for use in ghci.
There is no command line variant of this field.
diff --git a/doc/nix-local-build.rst b/doc/nix-local-build.rst
index 19cca22c9f..3186be8bbf 100644
--- a/doc/nix-local-build.rst
+++ b/doc/nix-local-build.rst
@@ -146,11 +146,10 @@ must be built per-project, versus external packages, which can be cached
across projects. To be more precise:
1. A **local package** is one that is listed explicitly in the
- ``packages``, ``optional-packages`` or ``extra-packages`` field of a
- project. Usually, these refer to packages whose source code lives
- directly in a folder in your project. But you can list an
- arbitrary Hackage package in :cfg-field:`packages`
- to force it to be treated as local.
+ ``packages``, ``optional-packages`` or ``extra-packages`` fields of a
+ project. Packages in the former two fields will usually have their
+ source code stored in a folder in your project, while ``extra-packages`` lists
+ packages residing on Hackage that are treated as being local anyway.
Local packages, as well as the external packages (below) which depend on
them, are built **inplace**, meaning that they are always built
@@ -159,8 +158,8 @@ packages are not cached and not given unique hashes, which makes them
suitable for packages which you want to edit and recompile.
2. An **external package** is any package which is not listed in the
- ``packages`` field. The source code for external packages is usually
- retrieved from Hackage.
+ ``packages``, ``optional-packages`` and ``extra-packages`` fields.
+ The source code for external packages is usually retrieved from Hackage.
When an external package does not depend on an inplace package, it can
be built and installed to a **global** store, which can be shared across
--
GitLab