From a0d29f47d16c5e504e39de3849c0616f1f42b791 Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Tue, 12 Dec 2023 12:36:25 -0500 Subject: [PATCH 1/2] Warn about project conditional blocks Fixes #8945 --- doc/cabal-package-description-file.rst | 2 ++ doc/cabal-project-description-file.rst | 29 +++++++++++++++++++------- 2 files changed, 24 insertions(+), 7 deletions(-) diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst index ae07f3ff3bc..ceceb36d2ef 100644 --- a/doc/cabal-package-description-file.rst +++ b/doc/cabal-package-description-file.rst @@ -2426,6 +2426,8 @@ Configuration Flags negated value. However, if the flag is manual, then the default value (which can be overridden by commandline flags) will be used. +.. _conditional-blocks: + Conditional Blocks ^^^^^^^^^^^^^^^^^^ diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst index 1bf238063c7..19eb3d0ca56 100644 --- a/doc/cabal-project-description-file.rst +++ b/doc/cabal-project-description-file.rst @@ -40,13 +40,28 @@ directories when there is none in the current directory. Conditionals and imports ------------------------ -As of ``cabal-install`` version 3.8, cabal supports conditional logic -and imports in ``cabal.project`` files. :ref:`conditions` in cabal -may case on operating system, architecture, and -compiler (i.e. there is no support for a notion of custom flags in -project files). Imports may specify local filepaths or remote urls, -and may reference either cabal.project files or v1-style cabal.config -freeze files. As a usage example: +As of ``cabal-install`` version 3.8, cabal supports conditional logic and +imports in ``cabal.project`` files. + + .. warning:: + + While :ref:`conditional blocks` can appear anywhere + within component or common sections of a package, their placement within a + project is restricted. Conditions may only be introduced at the top level + of a project. + + Projects have fewer :ref:`condition tests` as only packages + can have tests for flags. The remaining tests are available to projects, + operating system, architecture, compiler and boolean constants. + + - :samp:`os({name})` + - :samp:`arch({name})` + - :samp:`impl({compiler})` + - ``true`` + - ``false`` + +Imports may specify local filepaths or remote urls, and may reference either +cabal.project files or v1-style cabal.config freeze files. As a usage example: :: From c96747e633fc01c2cee72bc28854b91346c58cd0 Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Tue, 12 Dec 2023 13:15:05 -0500 Subject: [PATCH 2/2] Respond to review comment --- doc/cabal-project-description-file.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst index 19eb3d0ca56..a787a221f58 100644 --- a/doc/cabal-project-description-file.rst +++ b/doc/cabal-project-description-file.rst @@ -50,9 +50,9 @@ imports in ``cabal.project`` files. project is restricted. Conditions may only be introduced at the top level of a project. - Projects have fewer :ref:`condition tests` as only packages - can have tests for flags. The remaining tests are available to projects, - operating system, architecture, compiler and boolean constants. + Of the :ref:`condition tests`, only packages can test for + flags. Projects can test for operating system, architecture, compiler and + the boolean constants. - :samp:`os({name})` - :samp:`arch({name})`