Do not use tmp dirs for Haddock, add --no-haddock-version-cpp, and more

Haddock no longer writes compilation files by default, so we do not need to pass
tmp dirs for `-hidir`, `-stubdir`, and `-odir` via `--optghc`. Indeed, we do not
*want* to do so, since it results in recompilation for every invocation of
Haddock via Cabal. This commit stops this from happening.

This commit also introduces the `--no-haddock-version-cpp` flag and
`no-haddock-version-cpp:` cabal.project field, which prevent the definition of
the `__HADDOCK_VERSION__` macro when invoking GHC through Haddock. This is
essentially required in order for Haddock to be able to use existing
compilation results and avoid recompilation, since the macro definition will
trigger recompilation.

This commit also renames the `--haddock-lib` flag to `--haddock-resources-dir`
(and `haddock-lib:` cabal.project field to `haddock-resources-dir:`), and adds
this flag to the users guide since it was missing an entry. This also allows us
to add this field to `cabal-install:test:integration-tests2`, since it is no
longer ambiguous with the `--lib` flag.

This commit also causes `documentation: true` or `--enable-documentation` to
imply `-haddock` for GHC.

Also, since Haddock >= 2.29 is renaming `--lib` to `--resources-dir`, this
commit switches the flag provided to Haddock using a backwards compatible
condition based on the Haddock version.

Adds a changelog entry.

.gitignore

@@ -83,3 +83,6 @@ bench.html
 
 # Emacs
 .projectile
+
+# direnv
+.envrc

Cabal/src/Distribution/Simple/Haddock.hs

@@ -137,7 +137,7 @@ data HaddockArgs = HaddockArgs
   -- ^ Re-exported modules
   , argTargets :: [FilePath]
   -- ^ Modules to process.
-  , argLib :: Flag String
+  , argResourcesDir :: Flag String
   -- ^ haddock's static \/ auxiliary files.
   }
   deriving (Generic)
@@ -287,6 +287,16 @@ haddock pkg_descr lbi suffixes flags' = do
         [] -> allTargetsInBuildOrder' pkg_descr lbi
         _ -> targets
 
+    version' =
+      if flag haddockNoVersionCPP
+        then Nothing
+        else Just version
+
+    mtmp :: FilePath -> Maybe FilePath
+    mtmp
+      | version >= mkVersion [2, 28, 0] = const Nothing
+      | otherwise = Just
+
   internalPackageDB <-
     createInternalPackageDB verbosity lbi (flag haddockDistPref)
 
@@ -305,18 +315,18 @@ haddock pkg_descr lbi suffixes flags' = do
 
     preprocessComponent pkg_descr component lbi' clbi False verbosity suffixes
     let
-      doExe com = case (compToExe com) of
+      doExe com = case compToExe com of
         Just exe -> do
           withTempDirectoryEx verbosity tmpFileOpts (buildDir lbi') "tmp" $
             \tmp -> do
               exeArgs <-
                 fromExecutable
                   verbosity
-                  tmp
+                  (mtmp tmp)
                   lbi'
                   clbi
                   htmlTemplate
-                  version
+                  version'
                   exe
               let exeArgs' = commonArgs `mappend` exeArgs
               runHaddock
@@ -345,17 +355,17 @@ haddock pkg_descr lbi suffixes flags' = do
           (maybeComponentInstantiatedWith clbi)
     case component of
       CLib lib -> do
-        withTempDirectoryEx verbosity tmpFileOpts (buildDir lbi) "tmp" $
+        withTempDirectoryEx verbosity tmpFileOpts (buildDir lbi') "tmp" $
           \tmp -> do
             smsg
             libArgs <-
               fromLibrary
                 verbosity
-                tmp
+                (mtmp tmp)
                 lbi'
                 clbi
                 htmlTemplate
-                version
+                version'
                 lib
             let libArgs' = commonArgs `mappend` libArgs
             runHaddock verbosity tmpFileOpts comp platform haddockProg True libArgs'
@@ -392,20 +402,20 @@ haddock pkg_descr lbi suffixes flags' = do
         when
           (flag haddockForeignLibs)
           ( do
-              withTempDirectoryEx verbosity tmpFileOpts (buildDir lbi') "tmp" $
-                \tmp -> do
-                  smsg
-                  flibArgs <-
+              smsg
+              flibArgs <-
+                withTempDirectoryEx verbosity tmpFileOpts (buildDir lbi') "tmp" $
+                  \tmp ->
                     fromForeignLib
                       verbosity
-                      tmp
+                      (mtmp tmp)
                       lbi'
                       clbi
                       htmlTemplate
-                      version
+                      version'
                       flib
-                  let libArgs' = commonArgs `mappend` flibArgs
-                  runHaddock verbosity tmpFileOpts comp platform haddockProg True libArgs'
+              let libArgs' = commonArgs `mappend` flibArgs
+              runHaddock verbosity tmpFileOpts comp platform haddockProg True libArgs'
           )
           >> return index
       CExe _ -> when (flag haddockExecutables) (smsg >> doExe component) >> return index
@@ -465,7 +475,7 @@ fromFlags env flags =
           (haddockIndex flags)
     , argGenIndex = Flag False
     , argBaseUrl = haddockBaseUrl flags
-    , argLib = haddockLib flags
+    , argResourcesDir = haddockResourcesDir flags
     , argVerbose =
         maybe mempty (Any . (>= deafening))
           . flagToMaybe
@@ -491,7 +501,7 @@ fromHaddockProjectFlags flags =
     , argPrologueFile = haddockProjectPrologue flags
     , argInterfaces = fromFlagOrDefault [] (haddockProjectInterfaces flags)
     , argLinkedSource = Flag True
-    , argLib = haddockProjectLib flags
+    , argResourcesDir = haddockProjectResourcesDir flags
     }
 
 fromPackageDescription :: HaddockTarget -> PackageDescription -> HaddockArgs
@@ -536,26 +546,34 @@ componentGhcOptions verbosity lbi bi clbi odir =
 
 mkHaddockArgs
   :: Verbosity
-  -> FilePath
+  -> Maybe FilePath
+  -- ^ 'Nothing' to prevent passing temporary directories for -hidir, -odir, and
+  -- -stubdir to GHC through Haddock
   -> LocalBuildInfo
   -> ComponentLocalBuildInfo
   -> Maybe PathTemplate
   -- ^ template for HTML location
-  -> Version
+  -> Maybe Version
+  -- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
+  -- macro
   -> [FilePath]
   -> BuildInfo
   -> IO HaddockArgs
-mkHaddockArgs verbosity tmp lbi clbi htmlTemplate haddockVersion inFiles bi = do
+mkHaddockArgs verbosity mtmp lbi clbi htmlTemplate haddockVersion inFiles bi = do
   ifaceArgs <- getInterfaces verbosity lbi clbi htmlTemplate
-  let vanillaOpts =
-        (componentGhcOptions normal lbi bi clbi (buildDir lbi))
-          { -- Noooooooooo!!!!!111
-            -- haddock stomps on our precious .hi
-            -- and .o files. Workaround by telling
-            -- haddock to write them elsewhere.
-            ghcOptObjDir = toFlag tmp
-          , ghcOptHiDir = toFlag tmp
-          , ghcOptStubDir = toFlag tmp
+  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
+            -- GHC session in a temporary directory. Doing so always causes
+            -- recompilation during documentation generation, which can now be
+            -- avoided thanks to Hi Haddock. See
+            -- https://github.com/haskell/cabal/pull/9177 for discussion.
+            ghcOptObjDir = maybe (ghcOptObjDir vanillaOpts') toFlag mtmp
+          , ghcOptHiDir = maybe (ghcOptHiDir vanillaOpts') toFlag mtmp
+          , ghcOptStubDir = maybe (ghcOptStubDir vanillaOpts') toFlag mtmp
           }
           `mappend` getGhcCppOpts haddockVersion bi
       sharedOpts =
@@ -583,20 +601,24 @@ mkHaddockArgs verbosity tmp lbi clbi htmlTemplate haddockVersion inFiles bi = do
 
 fromLibrary
   :: Verbosity
-  -> FilePath
+  -> Maybe FilePath
+  -- ^ 'Nothing' to prevent passing temporary directories for -hidir, -odir, and
+  -- -stubdir to GHC through Haddock
   -> LocalBuildInfo
   -> ComponentLocalBuildInfo
   -> Maybe PathTemplate
   -- ^ template for HTML location
-  -> Version
+  -> Maybe Version
+  -- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
+  -- macro
   -> Library
   -> IO HaddockArgs
-fromLibrary verbosity tmp lbi clbi htmlTemplate haddockVersion lib = do
+fromLibrary verbosity mtmp lbi clbi htmlTemplate haddockVersion lib = do
   inFiles <- map snd `fmap` getLibSourceFiles verbosity lbi lib clbi
   args <-
     mkHaddockArgs
       verbosity
-      tmp
+      mtmp
       lbi
       clbi
       htmlTemplate
@@ -610,20 +632,24 @@ fromLibrary verbosity tmp lbi clbi htmlTemplate haddockVersion lib = do
 
 fromExecutable
   :: Verbosity
-  -> FilePath
+  -> Maybe FilePath
+  -- ^ 'Nothing' to prevent passing temporary directories for -hidir, -odir, and
+  -- -stubdir to GHC through Haddock
   -> LocalBuildInfo
   -> ComponentLocalBuildInfo
   -> Maybe PathTemplate
   -- ^ template for HTML location
-  -> Version
+  -> Maybe Version
+  -- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
+  -- macro
   -> Executable
   -> IO HaddockArgs
-fromExecutable verbosity tmp lbi clbi htmlTemplate haddockVersion exe = do
+fromExecutable verbosity mtmp lbi clbi htmlTemplate haddockVersion exe = do
   inFiles <- map snd `fmap` getExeSourceFiles verbosity lbi exe clbi
   args <-
     mkHaddockArgs
       verbosity
-      tmp
+      mtmp
       lbi
       clbi
       htmlTemplate
@@ -638,20 +664,24 @@ fromExecutable verbosity tmp lbi clbi htmlTemplate haddockVersion exe = do
 
 fromForeignLib
   :: Verbosity
-  -> FilePath
+  -> Maybe FilePath
+  -- ^ 'Nothing' to prevent passing temporary directories for -hidir, -odir, and
+  -- -stubdir to GHC through Haddock
   -> LocalBuildInfo
   -> ComponentLocalBuildInfo
   -> Maybe PathTemplate
   -- ^ template for HTML location
-  -> Version
+  -> Maybe Version
+  -- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
+  -- macro
   -> ForeignLib
   -> IO HaddockArgs
-fromForeignLib verbosity tmp lbi clbi htmlTemplate haddockVersion flib = do
+fromForeignLib verbosity mtmp lbi clbi htmlTemplate haddockVersion flib = do
   inFiles <- map snd `fmap` getFLibSourceFiles verbosity lbi flib clbi
   args <-
     mkHaddockArgs
       verbosity
-      tmp
+      mtmp
       lbi
       clbi
       htmlTemplate
@@ -707,7 +737,9 @@ getReexports LibComponentLocalBuildInfo{componentExposedModules = mods} =
 getReexports _ = []
 
 getGhcCppOpts
-  :: Version
+  :: Maybe Version
+  -- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
+  -- macro
   -> BuildInfo
   -> GhcOptions
 getGhcCppOpts haddockVersion bi =
@@ -717,16 +749,21 @@ getGhcCppOpts haddockVersion bi =
     }
   where
     needsCpp = EnableExtension CPP `elem` usedExtensions bi
-    defines = [haddockVersionMacro]
-    haddockVersionMacro =
-      "-D__HADDOCK_VERSION__="
-        ++ show (v1 * 1000 + v2 * 10 + v3)
+    defines =
+      [ "-D__HADDOCK_VERSION__=" ++ show vn
+      | Just vn <- [versionInt . versionNumbers <$> haddockVersion]
+      ]
       where
-        (v1, v2, v3) = case versionNumbers haddockVersion of
-          [] -> (0, 0, 0)
-          [x] -> (x, 0, 0)
-          [x, y] -> (x, y, 0)
-          (x : y : z : _) -> (x, y, z)
+        -- 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
@@ -922,7 +959,7 @@ renderPureArgs version comp platform args =
       , isVersion 2 19
       ]
     , argTargets $ args
-    , maybe [] ((: []) . ("--lib=" ++)) . flagToMaybe . argLib $ args
+    , maybe [] ((: []) . (resourcesDirFlag ++)) . flagToMaybe . argResourcesDir $ args
     ]
   where
     renderInterfaces = map renderInterface
@@ -964,6 +1001,9 @@ renderPureArgs version comp platform args =
     verbosityFlag
       | isVersion 2 5 = "--verbosity=1"
       | otherwise = "--verbose"
+    resourcesDirFlag
+      | isVersion 2 29 = "--resources-dir="
+      | otherwise = "--lib="
     haddockSupportsVisibility = version >= mkVersion [2, 26, 1]
     haddockSupportsPackageName = version > mkVersion [2, 16]