Documentation of field `tested-with`

[andreasabel]

The documentation http://cabal.readthedocs.io/en/latest/developing-packages.html?highlight=tested-with#pkg-field-tested-with currently just says

tested-with: compiler list

    A list of compilers and versions against which the package has been tested (or at least built).

The format of the compiler list needs to be explained by a representative example at least.

Cabal does have specific expectations here, as witnessed by this error:

cabal: <loc>: Parse of field 'tested-with' failed.

[hvr]

Good catch! I'll try to improve the documentation (unless you want to take a stab at it).

For historical context, afaik, the tested-with field was considered a bit of an historical artifact at some point, and got more or less deprecated (e.g. Hackage doesn't show it anymore).

However, it turned out to be convenient to use in the travis-script generator in https://github.com/hvr/multi-ghc-travis, and that's (to my knowledge) the only tooling that still makes use of the tested-with field.

[asr]

The current documentation shows some representative examples, so this issue can be closed.

[andreasabel]

Yes, that's probably good enough.
Though, I usually prefer the syntax without the , which is not show-cased.

tested-with:
  GHC == 9.0.1
  GHC == 8.10.4

[phadej]

Comma is optional by historical mistake. My plan was to abolish optional commas from the format all together. Either the field doesn't have commas (e.g. other-extensions, ghc-options - single token elements) or it does (build-depends, tested-with - not so simple elements).

Commas really improve error messages when you screw up. There is leading or trailing commas if you want diff friendly lists:

tested-with:
  , GHC == 9.0.1
  , GHC == 8.10.1

EDIT: main motivation is indeed other-extensions field, where commas are optional at the moment. There are files on Hackage where comma usage was inconsistent, e.g. something like:

other-extensions: DeriveFunctor, DeriveFoldable DeriveTraversable

which worked. That doesn't work with cabal-version: 3.0 which requires punctuation to be consistent (either commas between every element, or no commas). Removing the choice would make format simpler.

[andreasabel]

@phadej wrote:

tested-with:
  , GHC == 9.0.1
  , GHC == 8.10.1

This is a syntax I can live with very well! It has the convenience of bullet lists where the first entry does not have a special syntax, so I can conveniently cut and rearrange lines.

However, I never dared to start a list with an empty entry, I would have written:

tested-with:
  GHC == 9.0.1
  , GHC == 8.10.1

Trying your syntax, I get a parse error.

$ cabal configure
Errors encountered when parsing cabal file ./hello.cabal:

hello.cabal:8:3: error:
unexpected ','
expecting white space or end of input

    7 | tested-with:
    8 |   , GHC == 9.0.1
      |   ^

This error does not give me a hint towards its solution. I will likely believe that I cannot start a list with a comma.

However, believing you, after a year of diving into v2-cabal I smell the problem. Bisecting through the cabal-versions, I find that starting with 3.0 it does parse. (However, then other changes to my .cabal file are demanded, like default-langage.)

TL;DR A diff-friendly example for tested-with should also be included in the docs, with sufficient hints to avoid the pitfalls I just described.