Clarify build-tool-depends a bit more #5561

domenkozar · 2018-09-03T17:02:17Z

Please include the following checklist in your PR:

Patches conform to the coding conventions.
Any changes that could be relevant to users have been recorded in the changelog.
The documentation has been updated, if necessary.
If the change is docs-only, [ci skip] is used to avoid triggering the build bots.

Please also shortly describe how you tested your change. Bonus points for added tests!

hvr · 2018-09-03T17:21:02Z

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.


typo at "executabes"

hvr · 2018-09-03T17:22:25Z

Cabal/doc/developing-packages.rst


-    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:


Maybe we could while at it also address #5418 (comment)

hvr · 2018-09-03T17:24:27Z

Cabal/doc/developing-packages.rst

+
+    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.


not "specify" but rather "provide" (in the sense of installing them and making them available via $PATH)

domenkozar · 2018-09-03T18:41:55Z

@hvr I hope I have addressed all of your comments.

gilligan

While I guess all relevant information is per se available there is not a single example.

Any objections to including at least one example with, and one example without version bounds?

Edit: of course only of valid build-tool-depends strings and nothing more.

domenkozar · 2018-09-04T10:23:04Z

Examples! Yes, I'll add those.

hvr · 2018-09-04T16:35:55Z

of course only of valid build-tool-depends strings and nothing more.

well, I think it'd be more illustrative to show a minimal example which involves an executable and a test-suite, where the test-suite uses build-tool-depends to get access to the intra-package executable (without version bounds obviously), and you can combine that with having the executable refer to some external build-tools such as markdown-unlit (with version bounds)

Ericson2314

Yeah I like this better. Especially that new bit at the end. Thanks Domen!

Ericson2314 · 2018-09-05T14:30:34Z

Cabal/doc/developing-packages.rst

@@ -2063,21 +2063,31 @@ 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 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.


Err what do you mean? The tests can invoke the executables when run? I suppose they do work for that, though I hope to make a different sort of dependency for that httpsaskell/cabal/issues/5411 . Either way, I hope the vast majority of use-cases like hspec-discover really are just used when building the tests.

Yes :) Anything to clarify here?

@Ericson2314 btw, assuming we get run-tool-depends at some point; we'd still need to emulate the current build-tools-depends which conflatedly implies the future run-tool-depends w/ cabal-version:2.* packages; so at that point, @domenkozar wording will still be valid for packages using the respective cabal-version:-values which still had these semantics.

Btw, that sentence implies that running the test-suite is considered part of the build-phase; I think it's worth spelling this out as otherwise it might not be obvious that the respective $PATH-augmentation will also be in effect during the invocation of the test-suite (via e.g. cabal new-test)

Huh. So cabal new-run test:blah and cabal new-test test:blah will behave differently wrt the availability of things listed in build-tool-depends?

Edit: Experimentally verified that yes, they do behave differently. That's worrying if we're recommending new-run as the way to pass arguments to tests.

@quasicomputational you picked up on my subtle hint... ;-)

I consider this a bit of a bug, and I seem to recall we already talked about this in another issue; i.e. ideally

cabal new-run test:x behaves close to cabal new-test x

cabal new-run bench:x behaves close to cabal new-bench x

as I'd consider it merely a different interface to invoking the test-suites; but the $PATH setup ought to be compatible.

Right insofar that there's a bug, I consider the new-run behavior correct :D.

Ericson2314 · 2018-09-05T16:52:15Z

Cabal/doc/developing-packages.rst

-    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.


dependencies

Ericson2314 · 2018-09-06T01:45:28Z

Cabal/doc/developing-packages.rst

+
+.. [#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 Nix-style builds it's considered an error if you depend on a exe-only package via build-depends: the solver will refuse it


This is full sentence, so I'd punctate it as such like the others

Ericson2314 · 2018-09-06T01:46:01Z

Cabal/doc/developing-packages.rst

+
+                                   - 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


the correct version

, so you might

Ericson2314 · 2018-09-06T01:48:23Z

Cabal/doc/developing-packages.rst

+    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 try to makes 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:

I found something like that easier to read

hvr · 2018-09-09T11:54:27Z

Cabal/doc/developing-packages.rst


-    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 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:


One thing worth mentioning explicitly is that those tools' are prepended to the search $PATH; that's important as otherwise a globally same-called executable could interfere (concrete example: if you happen to have a system-wide installed alex executable version 3.1.3 in /usr/bin, but your build-tools-depends: alex:alex ^>= 3.2.4 you'd certainly want to use the one provisioned by new-build satisfying the version constraint to take precedence.

"are built" ... does this mean cabal will do the building automatically or that the user is expected to do the building independently?

@fommil would "are atomically built" clarify the intent?

I think this is important addition. I would like to see in the documentation how to specify constraints for build-tool-depends.

domenkozar · 2018-09-27T08:55:34Z

Hey all, I haven't given up on this, thanks for all the feedback. Going to revisit this today.

domenkozar · 2018-09-28T10:48:55Z

@hvr @Ericson2314 @gilligan @fommil @chshersh addressed comments, I'm not entirely sure about the examples, they should probably be full-blown otherwise they provide little insight.

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-7.10.3" }

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-8.0.2" }

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-7.6.3" }

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-7.8.4" }

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-8.2.2" }

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-8.4.3" }

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-8.4.3-fdebug-expensive-assertions" }

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"osx-7.8.4" }

hvr · 2018-09-29T08:09:27Z

@domenkozar Thank you! I've merged the current state so we can get an incremental improvement in earlier rather than later (so we can start pointing to the official docs); for the examples let's do a new PR if you're up to it! :-)

[ci skip] Clarify build-tool-depends a bit more

41ff30f

This was referenced Sep 3, 2018

Cabal build-tool-depends doesn't work #5560

Closed

Migrating the ecosystem to use build-tool-depends #5412

Open

hvr reviewed Sep 3, 2018

View reviewed changes

domenkozar mentioned this pull request Sep 3, 2018

A nice way to run an executable as part of a test suite? #5418

Closed

[ci skip] review feedback

ca91884

domenkozar force-pushed the docs-build-tool-depends branch from 9f1bde6 to ca91884 Compare September 3, 2018 18:43

gilligan reviewed Sep 4, 2018

View reviewed changes

Ericson2314 reviewed Sep 6, 2018

View reviewed changes

feedback

127831b

hvr reviewed Sep 9, 2018

View reviewed changes

23Skidoo mentioned this pull request Sep 27, 2018

You're awesome! We're giving you commit bits. #3567

Closed

review feedback

96d59be

haskell-pushbot pushed a commit to haskell-pushbot/cabal-binaries that referenced this pull request Sep 28, 2018

{"origin":"haskell/cabal/pull/5561",

6048ab2

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-7.10.3" }

haskell-pushbot pushed a commit to haskell-pushbot/cabal-binaries that referenced this pull request Sep 28, 2018

{"origin":"haskell/cabal/pull/5561",

efd024e

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-8.0.2" }

haskell-pushbot pushed a commit to haskell-pushbot/cabal-binaries that referenced this pull request Sep 28, 2018

{"origin":"haskell/cabal/pull/5561",

3a8e49e

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-7.6.3" }

haskell-pushbot pushed a commit to haskell-pushbot/cabal-binaries that referenced this pull request Sep 28, 2018

{"origin":"haskell/cabal/pull/5561",

dadaaa2

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-7.8.4" }

haskell-pushbot pushed a commit to haskell-pushbot/cabal-binaries that referenced this pull request Sep 28, 2018

{"origin":"haskell/cabal/pull/5561",

1d1466c

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-8.2.2" }

haskell-pushbot pushed a commit to haskell-pushbot/cabal-binaries that referenced this pull request Sep 28, 2018

{"origin":"haskell/cabal/pull/5561",

0f40ca3

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"linux-8.4.3" }

haskell-pushbot pushed a commit to haskell-pushbot/cabal-binaries that referenced this pull request Sep 28, 2018

{"origin":"haskell/cabal/pull/5561",

b504d57

"url":"pull/5561", "account":"haskell", "repo":"cabal", "commit": "96d59bed00e679bf99fdc9251dc6c65c947068c3", "tag":"osx-7.8.4" }

hvr merged commit c070d6a into haskell:master Sep 29, 2018

fgaz mentioned this pull request Aug 26, 2021

Access the executable build by cabal build (with a custom Setup.hs) from cabal test #7577

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarify build-tool-depends a bit more #5561

Clarify build-tool-depends a bit more #5561

domenkozar commented Sep 3, 2018

hvr Sep 3, 2018

hvr Sep 3, 2018

hvr Sep 3, 2018

domenkozar commented Sep 3, 2018

gilligan left a comment •

edited

Loading

domenkozar commented Sep 4, 2018

hvr commented Sep 4, 2018

Ericson2314 left a comment

Ericson2314 Sep 5, 2018

domenkozar Sep 9, 2018

hvr Sep 9, 2018

hvr Sep 9, 2018

quasicomputational Sep 9, 2018 •

edited

Loading

hvr Sep 10, 2018

Ericson2314 Sep 10, 2018

Ericson2314 Sep 5, 2018

Ericson2314 Sep 6, 2018

Ericson2314 Sep 6, 2018

Ericson2314 Sep 6, 2018

Ericson2314 Sep 6, 2018

Ericson2314 Sep 6, 2018

hvr Sep 9, 2018

fommil Sep 24, 2018

hvr Sep 24, 2018

fommil Sep 24, 2018

chshersh Sep 27, 2018

domenkozar commented Sep 27, 2018

domenkozar commented Sep 28, 2018

hvr commented Sep 29, 2018


		.. [#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 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 correct version of the package is installed, you might end up overwriting versions with each other

Clarify build-tool-depends a bit more #5561

Clarify build-tool-depends a bit more #5561

Conversation

domenkozar commented Sep 3, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

domenkozar commented Sep 3, 2018

gilligan left a comment • edited Loading

Choose a reason for hiding this comment

domenkozar commented Sep 4, 2018

hvr commented Sep 4, 2018

Ericson2314 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

quasicomputational Sep 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

domenkozar commented Sep 27, 2018

domenkozar commented Sep 28, 2018

hvr commented Sep 29, 2018

gilligan left a comment •

edited

Loading

quasicomputational Sep 9, 2018 •

edited

Loading