Re #729 Add --haddock-executables flag

Note: This is not yet guarded for Cabal >= 3.8.1.0.

Author: mpilgrem

ChangeLog.md

@@ -31,6 +31,10 @@ Other enhancements:
 * In YAML configuration files, the `default-init-snapshot` key is introduced to
   allow a default snapshot to be specified for use with the `stack init`
   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).
 
 Bug fixes:
 

src/Stack/Build/ExecutePackage.hs

@@ -609,6 +609,7 @@ realConfigAndBuild
                       , [ "--haddock-option=--hyperlinked-source"
                         | ee.buildOpts.haddockHyperlinkSource
                         ]
+                      , [ "--executables" | ee.buildOpts.haddockExecutables ]
                       , [ "--internal" | ee.buildOpts.haddockInternal  ]
                       , quickjump
                       ]

src/Stack/BuildOpts.hs

@@ -31,6 +31,7 @@ defaultBuildOpts = BuildOpts
   , haddockOpts = defaultHaddockOpts
   , openHaddocks = defaultFirstFalse buildMonoid.openHaddocks
   , haddockDeps = Nothing
+  , haddockExecutables = defaultFirstFalse buildMonoid.haddockExecutables
   , haddockInternal = defaultFirstFalse buildMonoid.haddockInternal
   , haddockHyperlinkSource = defaultFirstTrue buildMonoid.haddockHyperlinkSource
   , haddockForHackage = defaultFirstFalse buildMonoid.haddockForHackage

src/Stack/Config/Build.hs

@@ -54,6 +54,9 @@ buildOptsFromMonoid buildMonoid = BuildOpts
   , haddockDeps = if isHaddockFromHackage
       then Nothing
       else getFirst buildMonoid.haddockDeps
+  , haddockExecutables =
+         not isHaddockFromHackage
+      && fromFirstFalse buildMonoid.haddockExecutables
   , haddockInternal =
          not isHaddockFromHackage
       && fromFirstFalse buildMonoid.haddockInternal

src/Stack/Options/BuildMonoidParser.hs

@@ -41,6 +41,7 @@ buildOptsMonoidParser hide0 = BuildOptsMonoid
   <*> haddockOptsParser hideBool
   <*> openHaddocks
   <*> haddockDeps
+  <*> haddockExecutables
   <*> haddockInternal
   <*> haddockHyperlinkSource
   <*> haddockForHackage
@@ -133,6 +134,11 @@ buildOptsMonoidParser hide0 = BuildOptsMonoid
     "building Haddock documentation for dependencies. (default: if building \
     \Haddock documentation, true; otherwise, false)"
     hide
+  haddockExecutables = firstBoolFlagsFalse
+    "haddock-executables"
+    "also building Haddock documentation for all executables (like \
+    \'cabal haddock --executables')."
+    hide
   haddockInternal = firstBoolFlagsFalse
     "haddock-internal"
     "building Haddock documentation for internal modules (like \

src/Stack/Types/BuildOpts.hs

@@ -32,6 +32,9 @@ data BuildOpts = BuildOpts
     -- ^ Open haddocks in the browser?
   , haddockDeps :: !(Maybe Bool)
     -- ^ Build haddocks for dependencies?
+  , haddockExecutables :: !Bool
+    -- ^ Also build Haddock documentation for all executable components, like
+    -- @runghc Setup.hs haddock --executables@.
   , haddockInternal :: !Bool
     -- ^ Build haddocks for all symbols and packages, like
     -- @cabal haddock --internal@

src/Stack/Types/BuildOptsMonoid.hs

@@ -45,6 +45,7 @@ data BuildOptsMonoid = BuildOptsMonoid
   , haddockOpts :: !HaddockOptsMonoid
   , openHaddocks :: !FirstFalse
   , haddockDeps :: !(First Bool)
+  , haddockExecutables :: !FirstFalse
   , haddockInternal :: !FirstFalse
   , haddockHyperlinkSource :: !FirstTrue
   , haddockForHackage :: !FirstFalse
@@ -81,6 +82,7 @@ instance FromJSON (WithJSONWarnings BuildOptsMonoid) where
     haddockOpts <- jsonSubWarnings (o ..:? haddockOptsArgName ..!= mempty)
     openHaddocks <- FirstFalse <$> o ..:? openHaddocksArgName
     haddockDeps <- First <$> o ..:? haddockDepsArgName
+    haddockExecutables <- FirstFalse <$> o ..:? haddockExecutablesArgName
     haddockInternal <- FirstFalse <$> o ..:? haddockInternalArgName
     haddockHyperlinkSource <- FirstTrue <$> o ..:? haddockHyperlinkSourceArgName
     haddockForHackage <-  FirstFalse <$> o ..:? haddockForHackageArgName
@@ -115,6 +117,7 @@ instance FromJSON (WithJSONWarnings BuildOptsMonoid) where
       , haddockOpts
       , openHaddocks
       , haddockDeps
+      , haddockExecutables
       , haddockInternal
       , haddockHyperlinkSource
       , haddockForHackage
@@ -161,6 +164,9 @@ openHaddocksArgName = "open-haddocks"
 haddockDepsArgName :: Text
 haddockDepsArgName = "haddock-deps"
 
+haddockExecutablesArgName :: Text
+haddockExecutablesArgName = "haddock-executables"
+
 haddockInternalArgName :: Text
 haddockInternalArgName = "haddock-internal"
 

tests/unit/Stack/ConfigSpec.hs

@@ -71,6 +71,7 @@ buildOptsConfig =
   "    - \"--css=/home/user/my-css\"\n" ++
   "  open-haddocks: true\n" ++
   "  haddock-deps: true\n" ++
+  "  haddock-executables: true\n" ++
   "  haddock-internal: true\n" ++
   "  haddock-hyperlink-source: false\n" ++
   "  haddock-for-hackage: false\n" ++
@@ -107,6 +108,7 @@ buildOptsHaddockForHackageConfig =
   "  haddock: true\n" ++
   "  open-haddocks: true\n" ++
   "  haddock-deps: true\n" ++
+  "  haddock-executables: true\n" ++
   "  haddock-internal: true\n" ++
   "  haddock-hyperlink-source: false\n" ++
   "  haddock-for-hackage: true\n" ++
@@ -232,6 +234,7 @@ spec = beforeAll setup $ do
           }
         bopts.openHaddocks `shouldBe` True
         bopts.haddockDeps `shouldBe` Just True
+        bopts.haddockExecutables `shouldBe` True
         bopts.haddockInternal `shouldBe` True
         bopts.haddockHyperlinkSource `shouldBe` False
         bopts.haddockForHackage `shouldBe` False