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,10 +287,18 @@ haddock pkg_descr lbi suffixes flags' = do
         [] -> allTargetsInBuildOrder' pkg_descr lbi
         _ -> targets
 
+    version' =
+      if flag haddockNoVersionCPP then
+        Nothing
+      else
+        Just version
+
+    index = installedPkgs lbi
+
   internalPackageDB <-
     createInternalPackageDB verbosity lbi (flag haddockDistPref)
 
-  (\f -> foldM_ f (installedPkgs lbi) targets') $ \index target -> do
+  forM_ targets' $ \target -> do
     let component = targetComponent target
         clbi = targetCLBI target
 
@@ -305,28 +313,25 @@ 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
-                  lbi'
-                  clbi
-                  htmlTemplate
-                  version
-                  exe
-              let exeArgs' = commonArgs `mappend` exeArgs
-              runHaddock
-                verbosity
-                tmpFileOpts
-                comp
-                platform
-                haddockProg
-                True
-                exeArgs'
+          exeArgs <-
+            fromExecutable
+              verbosity
+              lbi'
+              clbi
+              htmlTemplate
+              version'
+              exe
+          let exeArgs' = commonArgs `mappend` exeArgs
+          runHaddock
+            verbosity
+            tmpFileOpts
+            comp
+            platform
+            haddockProg
+            True
+            exeArgs'
         Nothing -> do
           warn
             (fromFlag $ haddockVerbosity flags)
@@ -345,67 +350,62 @@ haddock pkg_descr lbi suffixes flags' = do
           (maybeComponentInstantiatedWith clbi)
     case component of
       CLib lib -> do
-        withTempDirectoryEx verbosity tmpFileOpts (buildDir lbi) "tmp" $
-          \tmp -> do
-            smsg
-            libArgs <-
-              fromLibrary
-                verbosity
-                tmp
-                lbi'
-                clbi
-                htmlTemplate
-                version
-                lib
-            let libArgs' = commonArgs `mappend` libArgs
-            runHaddock verbosity tmpFileOpts comp platform haddockProg True libArgs'
-
-            pwd <- getCurrentDirectory
-
-            let
-              ipi =
-                inplaceInstalledPackageInfo
-                  pwd
-                  (flag haddockDistPref)
-                  pkg_descr
-                  (mkAbiHash "inplace")
-                  lib
-                  lbi'
-                  clbi
+        smsg
+        libArgs <-
+          fromLibrary
+            verbosity
+            lbi'
+            clbi
+            htmlTemplate
+            version'
+            lib
+        let libArgs' = commonArgs `mappend` libArgs
+        runHaddock verbosity tmpFileOpts comp platform haddockProg True libArgs'
 
-            debug verbosity $
-              "Registering inplace:\n"
-                ++ (InstalledPackageInfo.showInstalledPackageInfo ipi)
+        pwd <- getCurrentDirectory
+
+        let
+          ipi =
+            inplaceInstalledPackageInfo
+              pwd
+              (flag haddockDistPref)
+              pkg_descr
+              (mkAbiHash "inplace")
+              lib
+              lbi'
+              clbi
+
+        debug verbosity $
+          "Registering inplace:\n"
+            ++ (InstalledPackageInfo.showInstalledPackageInfo ipi)
+
+        registerPackage
+          verbosity
+          (compiler lbi')
+          (withPrograms lbi')
+          (withPackageDB lbi')
+          ipi
+          HcPkg.defaultRegisterOptions
+            { HcPkg.registerMultiInstance = True
+            }
+
+        return $ PackageIndex.insert ipi index
 
-            registerPackage
-              verbosity
-              (compiler lbi')
-              (withPrograms lbi')
-              (withPackageDB lbi')
-              ipi
-              HcPkg.defaultRegisterOptions
-                { HcPkg.registerMultiInstance = True
-                }
-
-            return $ PackageIndex.insert ipi index
       CFLib flib ->
         when
           (flag haddockForeignLibs)
           ( do
-              withTempDirectoryEx verbosity tmpFileOpts (buildDir lbi') "tmp" $
-                \tmp -> do
-                  smsg
-                  flibArgs <-
-                    fromForeignLib
-                      verbosity
-                      tmp
-                      lbi'
-                      clbi
-                      htmlTemplate
-                      version
-                      flib
-                  let libArgs' = commonArgs `mappend` flibArgs
-                  runHaddock verbosity tmpFileOpts comp platform haddockProg True libArgs'
+              smsg
+              flibArgs <-
+                fromForeignLib
+                  verbosity
+                  lbi'
+                  clbi
+                  htmlTemplate
+                  version'
+                  flib
+              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 +465,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 +491,7 @@ fromHaddockProjectFlags flags =
     , argPrologueFile = haddockProjectPrologue flags
     , argInterfaces = fromFlagOrDefault [] (haddockProjectInterfaces flags)
     , argLinkedSource = Flag True
-    , argLib = haddockProjectLib flags
+    , argResourcesDir = haddockProjectResourcesDir flags
     }
 
 fromPackageDescription :: HaddockTarget -> PackageDescription -> HaddockArgs
@@ -536,27 +536,20 @@ componentGhcOptions verbosity lbi bi clbi odir =
 
 mkHaddockArgs
   :: Verbosity
-  -> FilePath
   -> 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 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
-          }
+        componentGhcOptions normal lbi bi clbi (buildDir lbi)
           `mappend` getGhcCppOpts haddockVersion bi
       sharedOpts =
         vanillaOpts
@@ -583,20 +576,20 @@ mkHaddockArgs verbosity tmp lbi clbi htmlTemplate haddockVersion inFiles bi = do
 
 fromLibrary
   :: Verbosity
-  -> FilePath
   -> 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 lbi clbi htmlTemplate haddockVersion lib = do
   inFiles <- map snd `fmap` getLibSourceFiles verbosity lbi lib clbi
   args <-
     mkHaddockArgs
       verbosity
-      tmp
       lbi
       clbi
       htmlTemplate
@@ -610,20 +603,20 @@ fromLibrary verbosity tmp lbi clbi htmlTemplate haddockVersion lib = do
 
 fromExecutable
   :: Verbosity
-  -> FilePath
   -> 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 lbi clbi htmlTemplate haddockVersion exe = do
   inFiles <- map snd `fmap` getExeSourceFiles verbosity lbi exe clbi
   args <-
     mkHaddockArgs
       verbosity
-      tmp
       lbi
       clbi
       htmlTemplate
@@ -638,20 +631,20 @@ fromExecutable verbosity tmp lbi clbi htmlTemplate haddockVersion exe = do
 
 fromForeignLib
   :: Verbosity
-  -> FilePath
   -> 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 lbi clbi htmlTemplate haddockVersion flib = do
   inFiles <- map snd `fmap` getFLibSourceFiles verbosity lbi flib clbi
   args <-
     mkHaddockArgs
       verbosity
-      tmp
       lbi
       clbi
       htmlTemplate
@@ -707,7 +700,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 +712,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 +922,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 +964,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]