Commit 70e5f8fa authored by John Ericson's avatar John Ericson
Browse files

Improve documentation of `build-tools`

Forget case of arbitrary program on PATH
parent b2193187
......@@ -1705,16 +1705,12 @@ system-dependent values for these fields.
.. pkg-field:: build-tool-depends: package:executable list
A list of Haskell programs 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. 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` dependenices. 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
A list of Haskell programs 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 and error for
being impossible to follow.
......@@ -1729,13 +1725,25 @@ system-dependent values for these fields.
Deprecated in favor of :pkg-field:`build-tool-depends`.
Confusingly, programs in the list either refer to other executables in the
same package, or one of a hard-coded set of build tools. In the case of the
former, the entry can be sugared into a :pkg-field:`build-tool-depends`
entry by prefixing with ``$pkg:``. In the case of the latter, It is
desugared by looking up the package and executable name in a hard-coded
table. Refer to the documentation for :pkg-field:`build-tool-depends` to
understand the desugared fields meaning.
A list of Haskell programs needed to build this component.
Each may be followed by an optional version bound.
Confusingly, each program in the list either refer to one of three things:
1. Another executables in the same package
2. One of a hard-coded set of packages containing common build tools
3. A pre-built executable that should already be on the ``PATH``
These cases are listed in order of priority:
an executable in the package will override any of the hard-coded packages with the same name,
and a hard-coded package will override any executable on the ``PATH``.
In the first two cases, the list entry is desguared into a :pkg-field:`build-tool-depends` entry.
In the first case, the entry is desugared into a :pkg-field:`build-tool-depends` entry by prefixing with ``$pkg:``.
In the second case, it is desugared by looking up the package and executable name in a hard-coded table.
In either case, the optional version bound is passed through unchanged.
Refer to the documentation for :pkg-field:`build-tool-depends` to understand the desugared field's meaning, along with restrictions on version bounds.
.. pkg-field:: buildable: boolean
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment