Improve documentation for cabal-version field

[hvr]

There seems to be some confusion regarding the cabal-version field, causing some authors to set e.g. cabal-version: >= 1.14 for no good reason due to lack of understanding what that field actually means.

Also it would be useful to include a condensed cabal-version changelog of features added in each cabal-version to the manual.

C.f.

cabal/Cabal/Distribution/PackageDescription/Check.hs

Lines 911 to 1091 in 641e854

	checkCabalVersion :: PackageDescription -> [PackageCheck]
	checkCabalVersion pkg =
	catMaybes [
	-- check syntax of cabal-version field
	check (specVersion pkg >= Version [1,10] []
	&& not simpleSpecVersionRangeSyntax) $
	PackageBuildWarning $
	"Packages relying on Cabal 1.10 or later must only specify a "
	++ "version range of the form 'cabal-version: >= x.y'. Use "
	++ "'cabal-version: >= " ++ display (specVersion pkg) ++ "'."
	-- check syntax of cabal-version field
	, check (specVersion pkg < Version [1,9] []
	&& not simpleSpecVersionRangeSyntax) $
	PackageDistSuspicious $
	"It is recommended that the 'cabal-version' field only specify a "
	++ "version range of the form '>= x.y'. Use "
	++ "'cabal-version: >= " ++ display (specVersion pkg) ++ "'. "
	++ "Tools based on Cabal 1.10 and later will ignore upper bounds."
	-- check syntax of cabal-version field
	, checkVersion [1,12] simpleSpecVersionSyntax $
	PackageBuildWarning $
	"With Cabal 1.10 or earlier, the 'cabal-version' field must use "
	++ "range syntax rather than a simple version number. Use "
	++ "'cabal-version: >= " ++ display (specVersion pkg) ++ "'."
	-- check use of test suite sections
	, checkVersion [1,8] (not (null $ testSuites pkg)) $
	PackageDistInexcusable $
	"The 'test-suite' section is new in Cabal 1.10. "
	++ "Unfortunately it messes up the parser in older Cabal versions "
	++ "so you must specify at least 'cabal-version: >= 1.8', but note "
	++ "that only Cabal 1.10 and later can actually run such test suites."
	-- check use of default-language field
	-- note that we do not need to do an equivalent check for the
	-- other-language field since that one does not change behaviour
	, checkVersion [1,10] (any isJust (buildInfoField defaultLanguage)) $
	PackageBuildWarning $
	"To use the 'default-language' field the package needs to specify "
	++ "at least 'cabal-version: >= 1.10'."
	, check (specVersion pkg >= Version [1,10] []
	&& (any isNothing (buildInfoField defaultLanguage))) $
	PackageBuildWarning $
	"Packages using 'cabal-version: >= 1.10' must specify the "
	++ "'default-language' field for each component (e.g. Haskell98 or "
	++ "Haskell2010). If a component uses different languages in "
	++ "different modules then list the other ones in the "
	++ "'other-languages' field."
	-- check use of reexported-modules sections
	, checkVersion [1,21]
	(maybe False (not.null.reexportedModules) (library pkg)) $
	PackageDistInexcusable $
	"To use the 'reexported-module' field the package needs to specify "
	++ "at least 'cabal-version: >= 1.21'."
	-- check use of thinning and renaming
	, checkVersion [1,21] (not (null depsUsingThinningRenamingSyntax)) $
	PackageDistInexcusable $
	"The package uses "
	++ "thinning and renaming in the 'build-depends' field: "
	++ commaSep (map display depsUsingThinningRenamingSyntax)
	++ ". To use this new syntax, the package needs to specify at least"
	++ "'cabal-version: >= 1.21'."
	-- check use of default-extensions field
	-- don't need to do the equivalent check for other-extensions
	, checkVersion [1,10] (any (not . null) (buildInfoField defaultExtensions)) $
	PackageBuildWarning $
	"To use the 'default-extensions' field the package needs to specify "
	++ "at least 'cabal-version: >= 1.10'."
	-- check use of extensions field
	, check (specVersion pkg >= Version [1,10] []
	&& (any (not . null) (buildInfoField oldExtensions))) $
	PackageBuildWarning $
	"For packages using 'cabal-version: >= 1.10' the 'extensions' "
	++ "field is deprecated. The new 'default-extensions' field lists "
	++ "extensions that are used in all modules in the component, while "
	++ "the 'other-extensions' field lists extensions that are used in "
	++ "some modules, e.g. via the {-# LANGUAGE #-} pragma."
	-- check use of "foo (>= 1.0 && < 1.4) || >=1.8 " version-range syntax
	, checkVersion [1,8] (not (null versionRangeExpressions)) $
	PackageDistInexcusable $
	"The package uses full version-range expressions "
	++ "in a 'build-depends' field: "
	++ commaSep (map displayRawDependency versionRangeExpressions)
	++ ". To use this new syntax the package needs to specify at least "
	++ "'cabal-version: >= 1.8'. Alternatively, if broader compatibility "
	++ "is important, then convert to conjunctive normal form, and use "
	++ "multiple 'build-depends:' lines, one conjunct per line."
	-- check use of "build-depends: foo == 1.*" syntax
	, checkVersion [1,6] (not (null depsUsingWildcardSyntax)) $
	PackageDistInexcusable $
	"The package uses wildcard syntax in the 'build-depends' field: "
	++ commaSep (map display depsUsingWildcardSyntax)
	++ ". To use this new syntax the package need to specify at least "
	++ "'cabal-version: >= 1.6'. Alternatively, if broader compatibility "
	++ "is important then use: " ++ commaSep
	[ display (Dependency name (eliminateWildcardSyntax versionRange))
	| Dependency name versionRange <- depsUsingWildcardSyntax ]
	-- check use of "tested-with: GHC (>= 1.0 && < 1.4) || >=1.8 " syntax
	, checkVersion [1,8] (not (null testedWithVersionRangeExpressions)) $
	PackageDistInexcusable $
	"The package uses full version-range expressions "
	++ "in a 'tested-with' field: "
	++ commaSep (map displayRawDependency testedWithVersionRangeExpressions)
	++ ". To use this new syntax the package needs to specify at least "
	++ "'cabal-version: >= 1.8'."
	-- check use of "tested-with: GHC == 6.12.*" syntax
	, checkVersion [1,6] (not (null testedWithUsingWildcardSyntax)) $
	PackageDistInexcusable $
	"The package uses wildcard syntax in the 'tested-with' field: "
	++ commaSep (map display testedWithUsingWildcardSyntax)
	++ ". To use this new syntax the package need to specify at least "
	++ "'cabal-version: >= 1.6'. Alternatively, if broader compatibility "
	++ "is important then use: " ++ commaSep
	[ display (Dependency name (eliminateWildcardSyntax versionRange))
	| Dependency name versionRange <- testedWithUsingWildcardSyntax ]
	-- check use of "data-files: data/*.txt" syntax
	, checkVersion [1,6] (not (null dataFilesUsingGlobSyntax)) $
	PackageDistInexcusable $
	"Using wildcards like "
	++ commaSep (map quote $ take 3 dataFilesUsingGlobSyntax)
	++ " in the 'data-files' field requires 'cabal-version: >= 1.6'. "
	++ "Alternatively if you require compatibility with earlier Cabal "
	++ "versions then list all the files explicitly."
	-- check use of "extra-source-files: mk/*.in" syntax
	, checkVersion [1,6] (not (null extraSrcFilesUsingGlobSyntax)) $
	PackageDistInexcusable $
	"Using wildcards like "
	++ commaSep (map quote $ take 3 extraSrcFilesUsingGlobSyntax)
	++ " in the 'extra-source-files' field requires "
	++ "'cabal-version: >= 1.6'. Alternatively if you require "
	++ "compatibility with earlier Cabal versions then list all the files "
	++ "explicitly."
	-- check use of "source-repository" section
	, checkVersion [1,6] (not (null (sourceRepos pkg))) $
	PackageDistInexcusable $
	"The 'source-repository' section is new in Cabal 1.6. "
	++ "Unfortunately it messes up the parser in earlier Cabal versions "
	++ "so you need to specify 'cabal-version: >= 1.6'."
	-- check for new licenses
	, checkVersion [1,4] (license pkg `notElem` compatLicenses) $
	PackageDistInexcusable $
	"Unfortunately the license " ++ quote (display (license pkg))
	++ " messes up the parser in earlier Cabal versions so you need to "
	++ "specify 'cabal-version: >= 1.4'. Alternatively if you require "
	++ "compatibility with earlier Cabal versions then use 'OtherLicense'."
	-- check for new language extensions
	, checkVersion [1,2,3] (not (null mentionedExtensionsThatNeedCabal12)) $
	PackageDistInexcusable $
	"Unfortunately the language extensions "
	++ commaSep (map (quote . display) mentionedExtensionsThatNeedCabal12)
	++ " break the parser in earlier Cabal versions so you need to "
	++ "specify 'cabal-version: >= 1.2.3'. Alternatively if you require "
	++ "compatibility with earlier Cabal versions then you may be able to "
	++ "use an equivalent compiler-specific flag."
	, checkVersion [1,4] (not (null mentionedExtensionsThatNeedCabal14)) $
	PackageDistInexcusable $
	"Unfortunately the language extensions "
	++ commaSep (map (quote . display) mentionedExtensionsThatNeedCabal14)
	++ " break the parser in earlier Cabal versions so you need to "
	++ "specify 'cabal-version: >= 1.4'. Alternatively if you require "
	++ "compatibility with earlier Cabal versions then you may be able to "
	++ "use an equivalent compiler-specific flag."
	]

)

[bergmark]

I've also seen libraries using this with a custom Setup.hs that requires a newer Cabal. Unfortunately this isn't part of dependency resolution so builds often fail when picking an earlier version would work.

[phadej]

@hvr, would be it enough to write down specific breakpoints, i.e. 1.21, 1.10 and previous?

And maybe mention that cabal check will say if it's too low for the features you use?