Cabal: Don't pass -D__HADDOCK_VERSION__ to haddock

We no longer define the `__HADDOCK_VERSION__` macro when invoking GHC
through Haddock, since doing so essentially guarantees recompilation
during documentation generation.

We audited all uses of `__HADDOCK_VERSION__` in hackage, ensuring there
was a reasonable path forward to migrate away from using
`__HADDOCK_VERSION__` for each, while generating the same documentation
as it did before.

If you are a user of `__HADDOCK_VERSION__`, please take a look at the
discussion in #9177 and reach out
to us if your use case is not covered.

Reverts the version-cpp flag introduced in the previous commit to avoid
a workaround. Instead, we get rid of the problem (`__HADDOCK_VERSION__`) at its root.

See the discussion in #9177

Author: alt-romes

Cabal/src/Distribution/Simple/Haddock.hs

@@ -83,7 +83,6 @@ import Distribution.Types.ComponentLocalBuildInfo
 import Distribution.Types.ExposedModule
 import Distribution.Types.LocalBuildInfo
 import Distribution.Types.TargetInfo
-import Distribution.Utils.NubList
 import Distribution.Utils.Path hiding
   ( Dir
   )
@@ -92,8 +91,6 @@ import qualified Distribution.Utils.ShortText as ShortText
 import Distribution.Verbosity
 import Distribution.Version
 
-import Language.Haskell.Extension
-
 import Control.Monad
 import Data.Either (rights)
 import System.Directory (doesDirectoryExist, doesFileExist)
@@ -329,11 +326,6 @@ haddock_setupHooks
           [] -> allTargetsInBuildOrder' pkg_descr lbi
           _ -> targets
 
-      version' =
-        if flag haddockVersionCPP
-          then Just version
-          else Nothing
-
       mtmp
         | version >= mkVersion [2, 28, 0] = const Nothing
         | otherwise = Just
@@ -380,7 +372,6 @@ haddock_setupHooks
                     lbi'
                     clbi
                     htmlTemplate
-                    version'
                     exe
                 let exeArgs' = commonArgs `mappend` exeArgs
                 runHaddock
@@ -420,7 +411,6 @@ haddock_setupHooks
                   lbi'
                   clbi
                   htmlTemplate
-                  version'
                   lib
               let libArgs' = commonArgs `mappend` libArgs
               runHaddock verbosity mbWorkDir tmpFileOpts comp platform haddockProg True libArgs'
@@ -467,7 +457,6 @@ haddock_setupHooks
                         lbi'
                         clbi
                         htmlTemplate
-                        version'
                         flib
                 let libArgs' = commonArgs `mappend` flibArgs
                 runHaddock verbosity mbWorkDir tmpFileOpts comp platform haddockProg True libArgs'
@@ -613,17 +602,13 @@ mkHaddockArgs
   -> ComponentLocalBuildInfo
   -> Maybe PathTemplate
   -- ^ template for HTML location
-  -> Maybe Version
-  -- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
-  -- macro
   -> [SymbolicPath Pkg File]
   -> BuildInfo
   -> IO HaddockArgs
-mkHaddockArgs verbosity mtmp lbi clbi htmlTemplate haddockVersion inFiles bi = do
+mkHaddockArgs verbosity mtmp lbi clbi htmlTemplate inFiles bi = do
   ifaceArgs <- getInterfaces verbosity lbi clbi htmlTemplate
   let vanillaOpts' =
         componentGhcOptions normal lbi bi clbi (buildDir lbi)
-          `mappend` getGhcCppOpts haddockVersion bi
       vanillaOpts =
         vanillaOpts'
           { -- Starting with Haddock 2.28, we no longer want to run Haddock's
@@ -635,7 +620,6 @@ mkHaddockArgs verbosity mtmp lbi clbi htmlTemplate haddockVersion inFiles bi = d
           , ghcOptHiDir = maybe (ghcOptHiDir vanillaOpts') (toFlag . coerceSymbolicPath) mtmp
           , ghcOptStubDir = maybe (ghcOptStubDir vanillaOpts') (toFlag . coerceSymbolicPath) mtmp
           }
-          `mappend` getGhcCppOpts haddockVersion bi
       sharedOpts =
         vanillaOpts
           { ghcOptDynLinkMode = toFlag GhcDynamicOnly
@@ -668,12 +652,9 @@ fromLibrary
   -> ComponentLocalBuildInfo
   -> Maybe PathTemplate
   -- ^ template for HTML location
-  -> Maybe Version
-  -- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
-  -- macro
   -> Library
   -> IO HaddockArgs
-fromLibrary verbosity mtmp lbi clbi htmlTemplate haddockVersion lib = do
+fromLibrary verbosity mtmp lbi clbi htmlTemplate lib = do
   inFiles <- map snd `fmap` getLibSourceFiles verbosity lbi lib clbi
   args <-
     mkHaddockArgs
@@ -682,7 +663,6 @@ fromLibrary verbosity mtmp lbi clbi htmlTemplate haddockVersion lib = do
       lbi
       clbi
       htmlTemplate
-      haddockVersion
       inFiles
       (libBuildInfo lib)
   return
@@ -699,12 +679,9 @@ fromExecutable
   -> ComponentLocalBuildInfo
   -> Maybe PathTemplate
   -- ^ template for HTML location
-  -> Maybe Version
-  -- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
-  -- macro
   -> Executable
   -> IO HaddockArgs
-fromExecutable verbosity mtmp lbi clbi htmlTemplate haddockVersion exe = do
+fromExecutable verbosity mtmp lbi clbi htmlTemplate exe = do
   inFiles <- map snd `fmap` getExeSourceFiles verbosity lbi exe clbi
   args <-
     mkHaddockArgs
@@ -713,7 +690,6 @@ fromExecutable verbosity mtmp lbi clbi htmlTemplate haddockVersion exe = do
       lbi
       clbi
       htmlTemplate
-      haddockVersion
       inFiles
       (buildInfo exe)
   return
@@ -731,12 +707,9 @@ fromForeignLib
   -> ComponentLocalBuildInfo
   -> Maybe PathTemplate
   -- ^ template for HTML location
-  -> Maybe Version
-  -- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
-  -- macro
   -> ForeignLib
   -> IO HaddockArgs
-fromForeignLib verbosity mtmp lbi clbi htmlTemplate haddockVersion flib = do
+fromForeignLib verbosity mtmp lbi clbi htmlTemplate flib = do
   inFiles <- map snd `fmap` getFLibSourceFiles verbosity lbi flib clbi
   args <-
     mkHaddockArgs
@@ -745,7 +718,6 @@ fromForeignLib verbosity mtmp lbi clbi htmlTemplate haddockVersion flib = do
       lbi
       clbi
       htmlTemplate
-      haddockVersion
       inFiles
       (foreignLibBuildInfo flib)
   return
@@ -796,35 +768,6 @@ getReexports LibComponentLocalBuildInfo{componentExposedModules = mods} =
   mapMaybe exposedReexport mods
 getReexports _ = []
 
-getGhcCppOpts
-  :: Maybe Version
-  -- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
-  -- macro
-  -> BuildInfo
-  -> GhcOptions
-getGhcCppOpts haddockVersion bi =
-  mempty
-    { ghcOptExtensions = toNubListR [EnableExtension CPP | needsCpp]
-    , ghcOptCppOptions = defines
-    }
-  where
-    needsCpp = EnableExtension CPP `elem` usedExtensions bi
-    defines =
-      [ "-D__HADDOCK_VERSION__=" ++ show vn
-      | Just vn <- [versionInt . versionNumbers <$> haddockVersion]
-      ]
-      where
-        -- For some list xs = [x, y, z ...], versionInt xs results in
-        -- x * 1000 + y * 10 + z. E.g.:
-        -- >>> versionInt [2, 29, 0]
-        -- 2290
-        -- >>> versionInt [3, 4]
-        -- 3040
-        -- >>> versionInt []
-        -- 0
-        versionInt :: [Int] -> Int
-        versionInt = foldr ((+) . uncurry (*)) 0 . zip [1000, 10, 1]
-
 getGhcLibDir
   :: Verbosity
   -> LocalBuildInfo

Cabal/src/Distribution/Simple/Setup/Haddock.hs

@@ -115,7 +115,6 @@ data HaddockFlags = HaddockFlags
   , haddockBaseUrl :: Flag String
   , haddockResourcesDir :: Flag String
   , haddockOutputDir :: Flag FilePath
-  , haddockVersionCPP :: Flag Bool
   }
   deriving (Show, Generic, Typeable)
 
@@ -171,7 +170,6 @@ defaultHaddockFlags =
     , haddockBaseUrl = NoFlag
     , haddockResourcesDir = NoFlag
     , haddockOutputDir = NoFlag
-    , haddockVersionCPP = Flag False
     }
 
 haddockCommand :: CommandUI HaddockFlags
@@ -380,13 +378,6 @@ haddockOptions showOrParseArgs =
         haddockOutputDir
         (\v flags -> flags{haddockOutputDir = v})
         (reqArgFlag "DIR")
-    , option
-        ""
-        ["version-cpp"]
-        "Define the __HADDOCK_VERSION__ macro when invoking GHC through Haddock. This will likely trigger recompilation during documentation generation."
-        haddockVersionCPP
-        (\v flags -> flags{haddockVersionCPP = v})
-        trueArg
     ]
 
 emptyHaddockFlags :: HaddockFlags
@@ -451,7 +442,6 @@ data HaddockProjectFlags = HaddockProjectFlags
   , -- haddockBaseUrl is not supported, a fixed value is provided
     haddockProjectResourcesDir :: Flag String
   , haddockProjectOutputDir :: Flag FilePath
-  , haddockProjectVersionCPP :: Flag Bool
   }
   deriving (Show, Generic, Typeable)
 
@@ -477,7 +467,6 @@ defaultHaddockProjectFlags =
     , haddockProjectResourcesDir = NoFlag
     , haddockProjectOutputDir = NoFlag
     , haddockProjectInterfaces = NoFlag
-    , haddockProjectVersionCPP = Flag False
     }
 
 haddockProjectCommand :: CommandUI HaddockProjectFlags
@@ -631,13 +620,6 @@ haddockProjectOptions _showOrParseArgs =
       haddockProjectOutputDir
       (\v flags -> flags{haddockProjectOutputDir = v})
       (reqArgFlag "DIR")
-  , option
-      ""
-      ["version-cpp"]
-      "Define the __HADDOCK_VERSION__ macro when invoking GHC through Haddock. This will likely trigger recompilation during documentation generation."
-      haddockProjectVersionCPP
-      (\v flags -> flags{haddockProjectVersionCPP = v})
-      trueArg
   ]
 
 emptyHaddockProjectFlags :: HaddockProjectFlags

cabal-install/src/Distribution/Client/CmdHaddockProject.hs

@@ -150,7 +150,6 @@ haddockProjectAction flags _extraArgs globalFlags = do
           , haddockKeepTempFiles = haddockProjectKeepTempFiles flags
           , haddockResourcesDir = haddockProjectResourcesDir flags
           , haddockOutputDir = haddockProjectOutputDir flags
-          , haddockVersionCPP = haddockProjectVersionCPP flags
           }
       nixFlags =
         (commandDefaultFlags CmdHaddock.haddockCommand)

cabal-install/src/Distribution/Client/Config.hs

@@ -632,7 +632,6 @@ instance Semigroup SavedConfig where
           , haddockBaseUrl = combine haddockBaseUrl
           , haddockResourcesDir = combine haddockResourcesDir
           , haddockOutputDir = combine haddockOutputDir
-          , haddockVersionCPP = combine haddockVersionCPP
           }
         where
           combine = combine' savedHaddockFlags

cabal-install/src/Distribution/Client/PackageHash.hs

@@ -240,7 +240,6 @@ data PackageHashConfigInputs = PackageHashConfigInputs
   , pkgHashHaddockBaseUrl :: Maybe String
   , pkgHashHaddockResourcesDir :: Maybe String
   , pkgHashHaddockOutputDir :: Maybe FilePath
-  , pkgHashHaddockVersionCPP :: Bool
   --     TODO: [required eventually] pkgHashToolsVersions     ?
   --     TODO: [required eventually] pkgHashToolsExtraOptions ?
   }
@@ -350,7 +349,6 @@ renderPackageHashInputs
           , opt "haddock-base-url" Nothing (fromMaybe "") pkgHashHaddockBaseUrl
           , opt "haddock-resources-dir" Nothing (fromMaybe "") pkgHashHaddockResourcesDir
           , opt "haddock-output-dir" Nothing (fromMaybe "") pkgHashHaddockOutputDir
-          , opt "haddock-version-cpp" False prettyShow pkgHashHaddockVersionCPP
           ]
             ++ Map.foldrWithKey (\prog args acc -> opt (prog ++ "-options") [] unwords args : acc) [] pkgHashProgramArgs
     where

cabal-install/src/Distribution/Client/ProjectConfig/Legacy.hs

@@ -823,7 +823,6 @@ convertLegacyPerPackageFlags
         , haddockBaseUrl = packageConfigHaddockBaseUrl
         , haddockResourcesDir = packageConfigHaddockResourcesDir
         , haddockOutputDir = packageConfigHaddockOutputDir
-        , haddockVersionCPP = packageConfigHaddockVersionCPP
         } = haddockFlags
 
       TestFlags
@@ -1221,7 +1220,6 @@ convertToLegacyPerPackageConfig PackageConfig{..} =
         , haddockBaseUrl = packageConfigHaddockBaseUrl
         , haddockResourcesDir = packageConfigHaddockResourcesDir
         , haddockOutputDir = packageConfigHaddockOutputDir
-        , haddockVersionCPP = packageConfigHaddockVersionCPP
         }
 
     testFlags =
@@ -1623,7 +1621,6 @@ legacyPackageConfigFieldDescrs =
             , "base-url"
             , "resources-dir"
             , "output-dir"
-            , "version-cpp"
             ]
           . commandOptionsToFields
        )

cabal-install/src/Distribution/Client/ProjectConfig/Types.hs

@@ -307,7 +307,6 @@ data PackageConfig = PackageConfig
   , packageConfigHaddockBaseUrl :: Flag String -- TODO: [required eventually] use this
   , packageConfigHaddockResourcesDir :: Flag String -- TODO: [required eventually] use this
   , packageConfigHaddockOutputDir :: Flag FilePath -- TODO: [required eventually] use this
-  , packageConfigHaddockVersionCPP :: Flag Bool -- TODO: [required eventually] use this
   , packageConfigHaddockForHackage :: Flag HaddockTarget
   , -- Test options
     packageConfigTestHumanLog :: Flag PathTemplate

cabal-install/src/Distribution/Client/ProjectPlanning.hs

@@ -2280,7 +2280,6 @@ elaborateInstallPlan
             elabHaddockBaseUrl = perPkgOptionMaybe pkgid packageConfigHaddockBaseUrl
             elabHaddockResourcesDir = perPkgOptionMaybe pkgid packageConfigHaddockResourcesDir
             elabHaddockOutputDir = perPkgOptionMaybe pkgid packageConfigHaddockOutputDir
-            elabHaddockVersionCPP = perPkgOptionFlag pkgid False packageConfigHaddockVersionCPP
 
             elabTestMachineLog = perPkgOptionMaybe pkgid packageConfigTestMachineLog
             elabTestHumanLog = perPkgOptionMaybe pkgid packageConfigTestHumanLog
@@ -4148,7 +4147,6 @@ setupHsHaddockFlags
       , haddockBaseUrl = maybe mempty toFlag elabHaddockBaseUrl
       , haddockResourcesDir = maybe mempty toFlag elabHaddockResourcesDir
       , haddockOutputDir = maybe mempty toFlag elabHaddockOutputDir
-      , haddockVersionCPP = maybe mempty toFlag elabHaddockVersionCPP
       }
 
 setupHsHaddockArgs :: ElaboratedConfiguredPackage -> [String]
@@ -4307,7 +4305,6 @@ packageHashConfigInputs shared@ElaboratedSharedConfig{..} pkg =
     , pkgHashHaddockBaseUrl = elabHaddockBaseUrl
     , pkgHashHaddockResourcesDir = elabHaddockResourcesDir
     , pkgHashHaddockOutputDir = elabHaddockOutputDir
-    , pkgHashHaddockVersionCPP = elabHaddockVersionCPP
     }
   where
     ElaboratedConfiguredPackage{..} = normaliseConfiguredPackage shared pkg

cabal-install/src/Distribution/Client/ProjectPlanning/Types.hs

@@ -302,7 +302,6 @@ data ElaboratedConfiguredPackage = ElaboratedConfiguredPackage
   , elabHaddockBaseUrl :: Maybe String
   , elabHaddockResourcesDir :: Maybe String
   , elabHaddockOutputDir :: Maybe FilePath
-  , elabHaddockVersionCPP :: Bool
   , elabTestMachineLog :: Maybe PathTemplate
   , elabTestHumanLog :: Maybe PathTemplate
   , elabTestShowDetails :: Maybe TestShowDetails

cabal-install/src/Distribution/Client/Setup.hs

@@ -2437,7 +2437,6 @@ haddockOptions showOrParseArgs =
              , "base-url"
              , "resources-dir"
              , "output-dir"
-             , "version-cpp"
              ]
   ]