SetupWrapper: allow being explicit about the Cabal spec version

A new option in SetupScriptOptions to specify exactly what version of
the Cabal spec we believe we're using when we're talking to the
Setup.hs.

Currently the version of cabal to use is guessed by the SetupWrapper
code based on the useCabalVersion version range and what versions are
installed in the ambient package environment, and cached state of
whatever an existing compiled Setup used.

When an explicit useCabalSpecVersion is given, all of these heuristics
are short cut and we use exactly the version we're told to use. In this
case it's the responsibility of the caller to useDependencies with a
suitable Cabal lib version, or otherwise know that we'll be using the
self or internal setup methods.

This approach goes along with the idea of deciding up front (and in a
deterministic way) what setup deps to use (using defaults if needed),
rather than deciding based on what's currently in the user environment.

In the current code paths, useCabalSpecVersion is Nothing, so no change
in behaviour yet.

Author: dcoutts

cabal-install/Distribution/Client/Configure.hs

@@ -182,6 +182,7 @@ configureSetupScript packageDBs
                      mpkg
   = SetupScriptOptions {
       useCabalVersion   = cabalVersion
+    , useCabalSpecVersion = Nothing
     , useCompiler       = Just comp
     , usePlatform       = Just platform
     , usePackageDB      = packageDBs'

cabal-install/Distribution/Client/SetupWrapper.hs

@@ -122,6 +122,11 @@ import qualified System.Win32 as Win32
 
 data SetupScriptOptions = SetupScriptOptions {
     useCabalVersion          :: VersionRange,
+
+    -- | This is the version of the Cabal specification that we believe that
+    -- this package uses. This affects the semantics and in particular the
+    -- Setup command line interface.
+    useCabalSpecVersion      :: Maybe Version,
     useCompiler              :: Maybe Compiler,
     usePlatform              :: Maybe Platform,
     usePackageDB             :: PackageDBStack,
@@ -180,6 +185,7 @@ data SetupScriptOptions = SetupScriptOptions {
 defaultSetupScriptOptions :: SetupScriptOptions
 defaultSetupScriptOptions = SetupScriptOptions {
     useCabalVersion          = anyVersion,
+    useCabalSpecVersion      = Nothing,
     useCompiler              = Nothing,
     usePlatform              = Nothing,
     usePackageDB             = [GlobalPackageDB, UserPackageDB],
@@ -242,7 +248,9 @@ determineSetupMethod options buildType'
     -- between the self and internal setup methods, which are
     -- consistent with each other.
   | buildType' == Custom             = externalSetupMethod
-  | not (cabalVersion `withinRange`
+  | maybe False (cabalVersion /=)
+        (useCabalSpecVersion options)
+ || not (cabalVersion `withinRange`
          useCabalVersion options)    = externalSetupMethod
   | isJust (useLoggingHandle options)
     -- Forcing is done to use an external process e.g. due to parallel
@@ -345,18 +353,24 @@ externalSetupMethod verbosity options pkg bt mkargs = do
 
   cabalLibVersionToUse :: IO (Version, (Maybe UnitId)
                              ,SetupScriptOptions)
-  cabalLibVersionToUse = do
-    savedVer <- savedVersion
-    case savedVer of
-      Just version | version `withinRange` useCabalVersion options
-        -> do updateSetupScript version bt
-              -- Does the previously compiled setup executable still exist and
-              -- is it up-to date?
-              useExisting <- canUseExistingSetup version
-              if useExisting
-                then return (version, Nothing, options)
-                else installedVersion
-      _ -> installedVersion
+  cabalLibVersionToUse =
+    case useCabalSpecVersion options of
+      Just version -> do
+        updateSetupScript version bt
+        writeFile setupVersionFile (show version ++ "\n")
+        return (version, Nothing, options)
+      Nothing  -> do
+        savedVer <- savedVersion
+        case savedVer of
+          Just version | version `withinRange` useCabalVersion options
+            -> do updateSetupScript version bt
+                  -- Does the previously compiled setup executable still exist
+                  -- and is it up-to date?
+                  useExisting <- canUseExistingSetup version
+                  if useExisting
+                    then return (version, Nothing, options)
+                    else installedVersion
+          _ -> installedVersion
     where
       -- This check duplicates the checks in 'getCachedSetupExecutable' /
       -- 'compileSetupExecutable'. Unfortunately, we have to perform it twice