Commit a6cee38d authored by John Ericson's avatar John Ericson
Browse files

Document `build-tool-depends` in the manual, and rewrite that for `build-tools`

`build-tools` is described in terms of `build-tool-depends`, just as it is
implemented in terms of it.
parent 9db90bf5
......@@ -1703,14 +1703,39 @@ system-dependent values for these fields.
Deprecated in favor of :pkg-field:`default-extensions`.
.. 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
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.
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.
.. pkg-field:: build-tools: program list
A list of programs, possibly annotated with versions, needed to
build this package, e.g. ``c2hs >= 0.15, cpphs``. If no version
constraint is specified, any version is assumed to be acceptable.
:pkg-field:`build-tools` can refer to locally defined executables, in which
case Cabal will make sure that executable is built first and add it
to the PATH upon invocations to the compiler.
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.
.. pkg-field:: buildable: boolean
......@@ -495,8 +495,8 @@ This has the following effects:
(As mentioned previously, you *must* specify internal dependencies as
- Internal ``build-tools`` dependencies are expected to be in the
``PATH`` upon subsequent invocations of ``setup``.
- Internal ``build-tool-depends`` and ``build-tools`` dependencies are expected
to be in the ``PATH`` upon subsequent invocations of ``setup``.
Full details can be found in the `Componentized Cabal
proposal <>`__.
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