Improve documentation for `custom-setup` & `setup-depends`
- Dominant language
- Haskell
- Stars
- 1.7k
- Forks
- 750
- Avg merge
- 4d 3h
- Merged PRs (30d)
- 28
Description
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`
Contributor guide
Assessment
This issue has not been assessed yet.