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 --- 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 652746b216a..c1566fe4e25 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``