cabal check requires absolute cabal-version numbers

[ndmitchell]

Cabal HEAD recently started warning on cabal check for cabal-version: >= 1.18. Why? It seems requiring people to break the version checking code on old Cabal versions is a bad idea...

[ndmitchell]

Concretely:

neil: Cabal check gave bad warnings:
"* Packages relying on Cabal 1.12 or later should specify a version range of"
"the form 'cabal-version: x.y'. Use 'cabal-version: 1.18'."

[phadej]

Cabal libs starting from 1.12 (shipped with GHC-7.2) understand cabal-version: version syntax (i.e. not version-range).

Note: that tool compiled against e.g. Cabal-1.12 shouldn't try to build cabal-version: 1.18 package. Starting with Cabal-2.0 it's enforced in the lib itself. See #4899

ping @hvr

[ndmitchell]

But if my user has Cabal version 1.10, and I write cabal-version: 1.18, won't that have nasty consequences? Isn't using >= 1.18 forevermore preferable? It seems odd to demand breaking old users for the sake of omitting 2 characters, when those two characters arguably make the intent clearer.

[phadej]

@ndmitchell the warning is only when cabal-version: 1.12 or up. You have to write `cabal-version: >= 1.10:

$ cabal check
The following warnings are likely to affect your build negatively:
* With Cabal 1.10 or earlier, the 'cabal-version' field must use range syntax
rather than a simple version number. Use 'cabal-version: >= 1.10'.

Hackage would reject this package.

---

To my understanding, no, >= 1.18 isn't preferable, as it's misleading. It is interpreted as 1.18, the field value is not a range. This is why I added a check.

Also note: that that for cabal-versions before 2.0 the check is not fatal:

$ cabal check
These warnings may cause trouble when distributing the package:
* Packages relying on Cabal 1.12 or later should specify a version range of
the form 'cabal-version: x.y'. Use 'cabal-version: 1.12'.

$ echo $?    
0

Only with 2.0 cabal check will fail:

$ cabal check
These warnings may cause trouble when distributing the package:
* Packages relying on Cabal 1.12 or later should specify a version range of
the form 'cabal-version: x.y'. Use 'cabal-version: 2.0'.

$ echo $?
1

and with 2.2 already the parser rejects the file:

$ cabal check
Warning: base64-bytestring-type.cabal:15:23:
unexpected cabal-version higher than 2.2 cannot be specified as a range. See
https://github.com/haskell/cabal/issues/4899
expecting ".", "-", white space, "&&" or "||"

>= 2.2
cabal: Failed parsing "./base64-bytestring-type.cabal".

---

We should document 1) cabal-spec evolution better 2) document cabal checks and 2+ refer from check messages to the documentation, but these are different issues.

[ndmitchell]

So users using older versions of Cabal are going to get a poor experience? Why not allow >= 1.18 indefinitely? Why not fix the 2.2 parser?

"the field value is not a range" - it really really is! If I say cabal-version: 1.18 that doesn't tie me to cabal-version 1.18, it allows me to use all versions higher. If I say base-0.4.5 that doesn't implicitly mean base >= 0.4.5... I understand it's not allowed to be a range other than an open ended range, but it is definitely describing a range.

[phadej]

>= 1.18 is and will be allowed indefinitely. It's however discouraged for new uploads.

---

Cabal-name-ambiguity hits again. In cabal-version it's cabal the spec, not cabal the lib or cabal the tool.
,
Cabal the lib version support older cabal-the-specs (in fact as much as only possible).

We do write default-language: Haskell2010, -std=c++11, or %YAML 1.2

So it's not a range. It's a single version of the Cabal spec, "Cabal the declarative build specification language", if you will. Cabal-the-libs can interpret many different specs

---

http://cabal.readthedocs.io/en/latest/developing-packages.html#pkg-field-cabal-version says

cabal-version The version of the Cabal specification that this package description uses. The Cabal specification does slowly evolve, introducing new features and occasionally changing the meaning of existing features. By specifying which version of the spec you are using it enables programs which process the package description to know what syntax to expect and what each part means.

[sol]

Something I just stumbled upon, http://cabal.readthedocs.io/en/latest/developing-packages.html#pkg-field-cabal-version still says

cabal-version: >= x.y

at the top.

[lspitzner]

@phadej Am I correct in assuming that the wording of the warning message should similarly not name it a version range? ("Packages relying on Cabal 1.12 or later should specify a version range of the form 'cabal-version: x.y'." -> "Packages relying on Cabal 1.12 or later should specify a specific Cabal-spec version of the form 'cabal-version: x.y'.")

[hvr]

@lspitzner yes, you're correct :-)

[moodmosaic]

I've just run into this as well. Definitely the warning message can be improved to be more clear. Happy to send over a pull request.

[hvr]

@moodmosaic please do! if you start a PR we can get the rewording process in motion and it'll certainly accelerate things

While at it, you might also want to review the wording in the user's guide, e.g. at

• https://cabal.readthedocs.io/en/latest/file-format-changelog.html and
• https://cabal.readthedocs.io/en/latest/developing-packages.html#pkg-field-cabal-version

[moodmosaic]

@hvr, thank you. I'll send a PR over the next few days.

[moodmosaic]

@hvr, it looks like it's already fixed by @lspitzner in https://github.com/haskell/cabal/commit/6f778e58d566ddfca8a96e873b9f5544017eff5e, which is great.