Improve documentation for `custom-setup` & `setup-depends`

[hvr]

The documentation at http://cabal.readthedocs.io/en/latest/developing-packages.html#custom-setup-scripts is rather terse.

Users are sometimes confused about the semantics in case of a missing custom-setup and whether you can add a custom-setup stanza even w/o saying cabal-version:>=1.24. (See e.g. hvr/multi-ghc-travis#81 for an example).

Consequently, we should flesh out the documentation for custom-setup, and document at least the following aspects:

• Which setup-depends are implied with recent exe:cabal versions for a missing custom-setup
• How do old cabal versions react if you add a custom-setup (which those version didn't support yet),
  • or more generally: How lib:Cabal version and exe:cabal versions relate to each other in the context of (non)existence of custom-setup
• Recommended practice if compatiblity with older Cabal versions is required.
  • and thus the relevance of cabal-version:>=1.24 when using custom-setup

[andreasabel]

Yes, these question are still terribly interesting and their answers very hard to discover. Please, someone who knows the answers, have mercy on us dumb users and extend the docs.

For instance, I read in the docs that build-tools: hspec-discover needs Cabal 2.0. But it is very unclear where to place this requirement in the cabal file. (For reference, here is a failed build: https://github.com/BNFC/bnfc/runs/1594499971?check_suite_focus=true)

• cabal-version: >=2.0 wasn't necessary and also not suggested by the discussion at https://github.com/haskell-CI/haskell-ci/issues/81
• Should I then put Cabal >= 2.0 in the build-depends of the goal that uses build-tools: hspec-discover? (Didn't try that.)
• I put Cabal >= 2.0 in the custom-setup setup-depends section, that fixed the build failure (see https://github.com/BNFC/bnfc/runs/1594774308?check_suite_focus=true).

However, I cannot claim to have understood the logic behind that. (Even more since the build claimed to have run under Cabal/cabal-install 3.2.0.0, which shouldn't have raised the issue in the first place---see versions flab.)