From 41ff30ff05f190954b9cbae775162aa853668a57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Domen=20Ko=C5=BEar?= Date: Mon, 3 Sep 2018 18:00:29 +0100 Subject: [PATCH 1/4] [ci skip] Clarify build-tool-depends a bit more --- Cabal/doc/developing-packages.rst | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/Cabal/doc/developing-packages.rst b/Cabal/doc/developing-packages.rst index 0c0e0c3116d..9c9cdf7efa3 100644 --- a/Cabal/doc/developing-packages.rst +++ b/Cabal/doc/developing-packages.rst @@ -2063,16 +2063,22 @@ system-dependent values for these fields. .. pkg-field:: build-tool-depends: package:executable list :since: 2.0 - A list of Haskell programs needed to build this component. + A list of Haskell executabes needed to build this component. + Each is specified by the package containing the executable and the name of the executable itself, separated by a colon, and optionally followed by a version bound. - It is fine for the package to be the current one, in which case this is termed an *internal*, rather than *external* executable dependency. - External dependencies can (and should) contain a version bound like conventional :pkg-field:`build-depends` dependencies. - Internal deps should not contain a version bound, as they will be always resolved within the same configuration of the package in the build plan. - Specifically, version bounds that include the package's version will be warned for being extraneous, and version bounds that exclude the package's version will raise an error for being impossible to follow. + All executables defined in the given Cabal file are termed as *internal* dependency as opposed to the rest which are *external* dependency. + Each of the two is handled differently: + + 1. External dependencies can (and should) contain a version bound like conventional :pkg-field:`build-depends` dependencies. + 2. Internal depenedencies should not contain a version bound, as they will be always resolved within the same configuration of the package in the build plan. + Specifically, version bounds that include the package's version will be warned for being extraneous, and version bounds that exclude the package's version will raise an error for being impossible to follow. - Cabal can make sure that specified programs are built and on the ``PATH`` before building the component in question. - It will always do so for internal dependencies, and also do so for external dependencies when using Nix-style local builds. + Cabal makes sure that specified programs are built and provided on the ``PATH`` before building the component in question under following conditions: + + a) For Nix-style local builds, both internal and external dependencies. + b) For old-style builds, only for internal dependencies [#old-style-build-tool-depends]_. + It's up to the user to specify needed executables in this case. :pkg-field:`build-tool-depends` was added in Cabal 2.0, and it will be ignored (with a warning) with old versions of Cabal. See @@ -3478,3 +3484,13 @@ a few options: .. include:: references.inc + +.. rubric:: Footnotes + +.. [#old-style-build-tool-depends] Some packages (ab)use :pkg-field:`build-depends` on old-style builds, but this has a few major drawbacks: + + - using new-build it's considered an error if you depend on a exe-only package via build-depends: the solver will refuse it + + - it may or may not place the executable on $PATH + + - it does not ensure correct version of the package is installed, you might end up overwriting versions with each other From ca91884e9ac7c7dfa2100893616855c3241202cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Domen=20Ko=C5=BEar?= Date: Mon, 3 Sep 2018 19:41:26 +0100 Subject: [PATCH 2/4] [ci skip] review feedback --- Cabal/doc/developing-packages.rst | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/Cabal/doc/developing-packages.rst b/Cabal/doc/developing-packages.rst index 9c9cdf7efa3..7c9a5dbb9f9 100644 --- a/Cabal/doc/developing-packages.rst +++ b/Cabal/doc/developing-packages.rst @@ -2063,7 +2063,8 @@ system-dependent values for these fields. .. pkg-field:: build-tool-depends: package:executable list :since: 2.0 - A list of Haskell executabes needed to build this component. + A list of Haskell executables needed to build this component. Executables are provided during the whole duration of the build, + so this field can be used for executables needed during :pkg-section:`test-suite` as well. Each is specified by the package containing the executable and the name of the executable itself, separated by a colon, and optionally followed by a version bound. @@ -2078,12 +2079,15 @@ system-dependent values for these fields. a) For Nix-style local builds, both internal and external dependencies. b) For old-style builds, only for internal dependencies [#old-style-build-tool-depends]_. - It's up to the user to specify needed executables in this case. + It's up to the user to provide needed executables in this case under `$PATH.` - :pkg-field:`build-tool-depends` was added in Cabal 2.0, and it will - be ignored (with a warning) with old versions of Cabal. See - :pkg-field:`build-tools` for more information about backwards - compatibility. + + .. note:: + + :pkg-field:`build-tool-depends` was added in Cabal 2.0, and it will + be ignored (with a warning) with old versions of Cabal. See + :pkg-field:`build-tools` for more information about backwards + compatibility. .. pkg-field:: build-tools: program list :deprecated: @@ -3489,7 +3493,7 @@ a few options: .. [#old-style-build-tool-depends] Some packages (ab)use :pkg-field:`build-depends` on old-style builds, but this has a few major drawbacks: - - using new-build it's considered an error if you depend on a exe-only package via build-depends: the solver will refuse it + - using Nix-style builds it's considered an error if you depend on a exe-only package via build-depends: the solver will refuse it - it may or may not place the executable on $PATH From 127831b16a89e0d92d95d9d6a5a71ea403e8e538 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Domen=20Ko=C5=BEar?= Date: Sat, 8 Sep 2018 23:06:07 +0100 Subject: [PATCH 3/4] feedback --- Cabal/doc/developing-packages.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Cabal/doc/developing-packages.rst b/Cabal/doc/developing-packages.rst index 7c9a5dbb9f9..04a5ce48c16 100644 --- a/Cabal/doc/developing-packages.rst +++ b/Cabal/doc/developing-packages.rst @@ -2068,14 +2068,14 @@ system-dependent values for these fields. Each is specified by the package containing the executable and the name of the executable itself, separated by a colon, and optionally followed by a version bound. - All executables defined in the given Cabal file are termed as *internal* dependency as opposed to the rest which are *external* dependency. + All executables defined in the given Cabal file are termed as *internal* dependencies as opposed to the rest which are *external* dependencies. Each of the two is handled differently: 1. External dependencies can (and should) contain a version bound like conventional :pkg-field:`build-depends` dependencies. 2. Internal depenedencies should not contain a version bound, as they will be always resolved within the same configuration of the package in the build plan. Specifically, version bounds that include the package's version will be warned for being extraneous, and version bounds that exclude the package's version will raise an error for being impossible to follow. - Cabal makes sure that specified programs are built and provided on the ``PATH`` before building the component in question under following conditions: + Cabal tries to make sure that all specified programs are built and provided on the ``PATH`` before building the component in question, but can only do so for Nix-style builds. Specifically: a) For Nix-style local builds, both internal and external dependencies. b) For old-style builds, only for internal dependencies [#old-style-build-tool-depends]_. @@ -3491,10 +3491,10 @@ a few options: .. rubric:: Footnotes -.. [#old-style-build-tool-depends] Some packages (ab)use :pkg-field:`build-depends` on old-style builds, but this has a few major drawbacks: +.. [#old-style-build-tool-depends] - - using Nix-style builds it's considered an error if you depend on a exe-only package via build-depends: the solver will refuse it + Some packages (ab)use :pkg-field:`build-depends` on old-style builds, but this has a few major drawbacks: - - it may or may not place the executable on $PATH - - - it does not ensure correct version of the package is installed, you might end up overwriting versions with each other + - using Nix-style builds it's considered an error if you depend on a exe-only package via build-depends: the solver will refuse it. + - it may or may not place the executable on $PATH. + - it does not ensure the correct version of the package is installed, so you might end up overwriting versions with each other. From 96d59bed00e679bf99fdc9251dc6c65c947068c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Domen=20Ko=C5=BEar?= Date: Fri, 28 Sep 2018 11:47:36 +0100 Subject: [PATCH 4/4] review feedback --- Cabal/doc/developing-packages.rst | 39 ++++++++++++++++++++++++------- 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/Cabal/doc/developing-packages.rst b/Cabal/doc/developing-packages.rst index 04a5ce48c16..bc81e5f4ba7 100644 --- a/Cabal/doc/developing-packages.rst +++ b/Cabal/doc/developing-packages.rst @@ -2063,19 +2063,42 @@ system-dependent values for these fields. .. pkg-field:: build-tool-depends: package:executable list :since: 2.0 - A list of Haskell executables needed to build this component. Executables are provided during the whole duration of the build, - so this field can be used for executables needed during :pkg-section:`test-suite` as well. + A list of Haskell executables needed to build this component. Executables are provided + during the whole duration of the component, so this field can be used for executables + needed during :pkg-section:`test-suite` as well. - Each is specified by the package containing the executable and the name of the executable itself, separated by a colon, and optionally followed by a version bound. + Each is specified by the package containing the executable and the name of the + executable itself, separated by a colon, and optionally followed by a version bound. + + All executables defined in the given Cabal file are termed as *internal* dependencies + as opposed to the rest which are *external* dependencies. - All executables defined in the given Cabal file are termed as *internal* dependencies as opposed to the rest which are *external* dependencies. Each of the two is handled differently: - 1. External dependencies can (and should) contain a version bound like conventional :pkg-field:`build-depends` dependencies. - 2. Internal depenedencies should not contain a version bound, as they will be always resolved within the same configuration of the package in the build plan. - Specifically, version bounds that include the package's version will be warned for being extraneous, and version bounds that exclude the package's version will raise an error for being impossible to follow. + 1. External dependencies can (and should) contain a version bound like conventional + :pkg-field:`build-depends` dependencies. + 2. Internal depenedencies should not contain a version bound, as they will be always + resolved within the same configuration of the package in the build plan. + Specifically, version bounds that include the package's version will be warned for + being extraneous, and version bounds that exclude the package's version will raise + an error for being impossible to follow. + + For example (1) using a test-suite to make sure README.md Haskell snippets are tested using + `markdown-unlit `__: + + :: + + build-tool-depends: markdown-unlit:markdown-unlit >=0.5.0 + + For example (2) using a test-suite to test executable behaviour in the same package: + + :: + + build-tool-depends: mypackage:executable - Cabal tries to make sure that all specified programs are built and provided on the ``PATH`` before building the component in question, but can only do so for Nix-style builds. Specifically: + Cabal tries to make sure that all specified programs are atomically built and prepended + on the ``$PATH`` shell variable before building the component in question, but can only do + so for Nix-style builds. Specifically: a) For Nix-style local builds, both internal and external dependencies. b) For old-style builds, only for internal dependencies [#old-style-build-tool-depends]_.