From fc9de616d5eef39521cb789f1d9f54aa08ed7b33 Mon Sep 17 00:00:00 2001
From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com>
Date: Thu, 6 Jun 2024 14:45:48 +0000
Subject: [PATCH] Fix #8141 Don't refer to 'custom-setup' as 'optional'
(#10073)
Also uses 'stanza' consistently in that context.
(cherry picked from commit 2e8d728611466a8dedd867e7353b565b426f5a49)
Co-authored-by: Mike Pilgrem <mpilgrem@users.noreply.github.com>
---
doc/cabal-package-description-file.rst | 13 ++++++++-----
1 file changed, 8 insertions(+), 5 deletions(-)
diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst
index 652746b216..c1566fe4e2 100644
--- a/doc/cabal-package-description-file.rst
+++ b/doc/cabal-package-description-file.rst
@@ -2804,8 +2804,10 @@ Declaring a ``custom-setup`` stanza also enables the generation of
:synopsis: Custom Setup.hs build information.
:since: 1.24
- The optional :pkg-section:`custom-setup` stanza contains information needed
- for the compilation of custom ``Setup.hs`` scripts,
+ A :pkg-section:`custom-setup` stanza is required for
+ :pkg-field:`build-type` ``Custom`` and will be ignored (with a warning) for
+ other build types. The stanza contains information needed for the compilation
+ of custom ``Setup.hs`` scripts. For example:
::
@@ -2838,7 +2840,7 @@ Backward compatibility and ``custom-setup``
Versions prior to Cabal 1.24 don't recognise ``custom-setup`` stanzas,
and will behave agnostic to them (except for warning about an unknown
-section). Consequently, versions prior to Cabal 1.24 can't ensure the
+'section'). Consequently, versions prior to Cabal 1.24 can't ensure the
declared dependencies ``setup-depends`` are in scope, and instead
whatever is registered in the current package database environment
will become eligible (and resolved by the compiler) for the
@@ -2848,8 +2850,9 @@ The availability of the
``MIN_VERSION_package_(A,B,C)`` CPP macros
inside ``Setup.hs`` scripts depends on the condition that either
-- a ``custom-setup`` section has been declared (or ``cabal build`` is being
- used which injects an implicit hard-coded ``custom-setup`` stanza if it's missing), or
+- a ``custom-setup`` stanza has been declared (or ``cabal build`` is being used
+ which injects an implicit hard-coded ``custom-setup`` stanza if it's missing),
+ or
- GHC 8.0 or later is used (which natively injects package version CPP macros)
Consequently, if you need to write backward compatible ``Setup.hs``
--
GitLab