haskell / haskell/cabal

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

Open
#4,538 1 comment 5 reactions 0 assignees View on GitHub
Cabal: stanza/custom-setup documentation
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.