Commit 8e58442e authored by Edward Z. Yang's avatar Edward Z. Yang
Browse files

Extra commentary on build-tools BC.

Signed-off-by: default avatarEdward Z. Yang <>
parent 9db9e696
......@@ -1716,10 +1716,15 @@ system-dependent values for these fields.
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-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
.. pkg-field:: build-tools: program list
Deprecated in favor of :pkg-field:`build-tool-depends`.
Deprecated in favor of :pkg-field:`build-tool-depends`, but `see below for backwards compatibility information. <buildtoolsbc>`_
A list of Haskell programs needed to build this component.
Each may be followed by an optional version bound.
......@@ -1728,19 +1733,27 @@ system-dependent values for these fields.
1. Another executables in the same package
2. One of a hard-coded set of packages containing common build tools
(possibly extended by a ``Custom`` setup script)
3. A pre-built executable that should already be on the ``PATH``
(Supported only by Cabal 2.0 and later.)
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 two cases, the list entry is desugared 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.
.. _buildtoolsbc:
Although this field is deprecated in favor of :pkg-field:`build-tool-depends`, there are some situations where you may prefer to use :pkg-field:`build-tool` in cases (1) and (2), as it is supported by more versions of Cabal.
In case (3), :pkg-field:`build-tool-depends` is better for backwards-compatibility, as it will be ignored by old versions of Cabal; if you add the executable to :pkg-field:`build-tools`, a setup script built against old Cabal will choke.
If an old version of Cabal is used, an end-user will have to manually arrange for the requested executable to be in your ``PATH``.
.. pkg-field:: buildable: boolean
:default: ``True``
Supports Markdown
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