Re #729 Warning about --haddock-executables for Cabal < 3.8.1.0

Author: mpilgrem

.stan.toml

@@ -190,25 +190,25 @@
 
 # Anti-pattern: unsafe functions
 [[ignore]]
-  id = "OBS-STAN-0212-FNS1cF-56:17"
+  id = "OBS-STAN-0212-FNS1cF-57:17"
 # ✦ Description:   Usage of unsafe functions breaks referential transparency
 # ✦ Category:      #Unsafe #AntiPattern
 # ✦ File:          src\Stack\BuildOpts.hs
 #
-#   55 ┃
-#   56 ┃   buildMonoid = undefined :: BuildOptsMonoid
-#   57 ┃                 ^^^^^^^^^
+#   56 ┃
+#   57 ┃   buildMonoid = undefined :: BuildOptsMonoid
+#   58 ┃                 ^^^^^^^^^
 
 # Anti-pattern: unsafe functions
 [[ignore]]
-  id = "OBS-STAN-0212-FNS1cF-68:14"
+  id = "OBS-STAN-0212-FNS1cF-69:14"
 # ✦ Description:   Usage of unsafe functions breaks referential transparency
 # ✦ Category:      #Unsafe #AntiPattern
 # ✦ File:          src\Stack\BuildOpts.hs
 #
-#    67 ┃
-#    68 ┃   toMonoid = undefined :: TestOptsMonoid
-#    69 ┃              ^^^^^^^^^
+#    68 ┃
+#    69 ┃   toMonoid = undefined :: TestOptsMonoid
+#    70 ┃              ^^^^^^^^^
 
 # Anti-pattern: Pattern matching on '_'
 # Pattern matching on '_' for sum types can create maintainability issues

ChangeLog.md

@@ -33,8 +33,8 @@ Other enhancements:
   command, as if it had been specified at the command line.
 * Add flag `--haddock-executables` to Stack's `build` command (including the
   `haddock` synonym for `build --haddock`) to enable also building Haddock
-  documentation for executables. Will fail for GHC versions before 9.4 due to a
-  bug in Cabal (the library).
+  documentation for executables. Due to a bug in Cabal (the library), Stack will
+  ignore the flag with a warning for GHC versions before 9.4.
 
 Bug fixes:
 

src/Stack/Build.hs

@@ -50,7 +50,7 @@ import           Stack.Types.BuildOptsMonoid
                    , buildOptsMonoidInstallExesL, buildOptsMonoidTestsL
                    )
 import           Stack.Types.Compiler ( getGhcVersion )
-import           Stack.Types.CompilerPaths ( cabalVersionL )
+import           Stack.Types.CompilerPaths ( HasCompiler, cabalVersionL )
 import           Stack.Types.Config
                    ( Config (..), HasConfig (..), buildOptsL
                    )
@@ -194,24 +194,32 @@ build msetLocalFiles = do
       localsIdents -> throwM $ LocalPackagesPresent localsIdents
 
     checkCabalVersion
+    haddockExecutablesSupported <- warnAboutHaddockExecutables bopts
+    let disableHaddockExecutables =
+          local $ over buildOptsL $ \bo -> bo { haddockExecutables = False }
+        withHaddockExecutablesGuarded = if haddockExecutablesSupported
+          then id
+          else disableHaddockExecutables
     warnAboutSplitObjs bopts
     warnIfExecutablesWithSameNameCouldBeOverwritten locals plan
 
     when bopts.preFetch $
         preFetch plan
 
     if boptsCli.dryrun
-      then printPlan plan
-      else executePlan
-             boptsCli
-             baseConfigOpts
-             locals
-             globalDumpPkgs
-             snapshotDumpPkgs
-             localDumpPkgs
-             installedMap
-             sourceMap.targets.targets
-             plan
+      then
+        printPlan plan
+      else
+        withHaddockExecutablesGuarded $ executePlan
+          boptsCli
+          baseConfigOpts
+          locals
+          globalDumpPkgs
+          snapshotDumpPkgs
+          localDumpPkgs
+          installedMap
+          sourceMap.targets.targets
+          plan
 
 buildLocalTargets ::
      HasEnvConfig env
@@ -317,6 +325,33 @@ warnIfExecutablesWithSameNameCouldBeOverwritten locals plan = do
   collect :: Ord k => [(k, v)] -> Map k (NonEmpty v)
   collect = Map.mapMaybe nonEmpty . Map.fromDistinctAscList . groupSort
 
+warnAboutHaddockExecutables ::
+     (HasCompiler env, HasTerm env)
+  => BuildOpts
+  -> RIO env Bool
+warnAboutHaddockExecutables bopts = do
+  cabalVer <- view cabalVersionL
+  if cabalVer < mkVersion [3, 8, 1]
+    then do
+      prettyWarnL
+        [ flow "Stack builds Haddock documentation with the version of the \
+               \Cabal package that comes with the specified version of GHC. \
+               \Version"
+        , fromString $ versionString cabalVer
+        , flow "was found, which does not support the building of \
+               \documentation for executables. The option to build such \
+               \documentation will be ignored. To use the option, use a \
+               \snapshot that specifies a version of GHC that is 9.4 or later. \
+               \Stackage LTS Haskell 21.0"
+        , parens (style Shell "lts-21.0")
+        , flow "or later or Nightly 2022-11-19"
+        , parens (style Shell "nightly-2022-11-19")
+        , flow "or later specify such GHC versions."
+        ]
+      pure False
+    else
+      pure bopts.haddockExecutables
+
 warnAboutSplitObjs :: HasTerm env => BuildOpts -> RIO env ()
 warnAboutSplitObjs bopts |  bopts.splitObjs =
   prettyWarnL

src/Stack/Build/Haddock.hs

@@ -258,18 +258,18 @@ generateHaddockIndex descr bco dumpPackages docRelFP destDir = do
   toInterfaceOpt ::
        DumpPackage
     -> IO (Maybe ([String], UTCTime, Path Abs File, Path Abs File))
-  toInterfaceOpt DumpPackage {haddockInterfaces, packageIdent, haddockHtml} =
-    case haddockInterfaces of
+  toInterfaceOpt dp =
+    case dp.haddockInterfaces of
       [] -> pure Nothing
       srcInterfaceFP:_ -> do
         srcInterfaceAbsFile <- parseCollapsedAbsFile srcInterfaceFP
-        let (PackageIdentifier name _) = packageIdent
+        let (PackageIdentifier name _) = dp.packageIdent
             destInterfaceRelFP =
               docRelFP FP.</>
-              packageIdentifierString packageIdent FP.</>
+              packageIdentifierString dp.packageIdent FP.</>
               (packageNameString name FP.<.> "haddock")
             docPathRelFP =
-              fmap ((docRelFP FP.</>) . FP.takeFileName) haddockHtml
+              fmap ((docRelFP FP.</>) . FP.takeFileName) dp.haddockHtml
             interfaces = intercalate "," $ mcons docPathRelFP [srcInterfaceFP]
 
         destInterfaceAbsFile <-