[Git][ghc/ghc][master] Allow users to override non-essential haddock options in a Flavour

[Marge Bot (@marge-bot)]

Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC


Commits:
e4350b41 by Matthew Pickering at 2023-07-21T23:24:25-04:00
Allow users to override non-essential haddock options in a Flavour

We now supply the non-essential options to haddock using the `extraArgs`
field, which can be specified in a Flavour so that if an advanced user
wants to change how documentation is generated then they can use
something other than the `defaultHaddockExtraArgs`.

This does have the potential to regress some packaging if a user has
overridden `extraArgs` themselves, because now they also need to add
the haddock options to extraArgs. This can easily be done by appending
`defaultHaddockExtraArgs` to their extraArgs invocation but someone
might not notice this behaviour has changed.

In any case, I think passing the non-essential options in this manner is
the right thing to do and matches what we do for the "ghc" builder,
which by default doesn't pass any optmisation levels, and would likewise
be very bad if someone didn't pass suitable `-O` levels for builds.

Fixes #23625

- - - - -


7 changed files:

- hadrian/src/Settings/Builders/Haddock.hs
- hadrian/src/Settings/Default.hs
- hadrian/src/Settings/Default.hs-boot
- hadrian/src/Settings/Flavours/Benchmark.hs
- hadrian/src/Settings/Flavours/Development.hs
- hadrian/src/Settings/Flavours/Performance.hs
- hadrian/src/Settings/Flavours/Validate.hs


Changes:

=====================================
hadrian/src/Settings/Builders/Haddock.hs
=====================================
@@ -50,6 +50,10 @@ haddockBuilderArgs = mconcat
         baseUrlTemplate <- expr (docsBaseUrl <$> userSetting defaultDocArgs)
         let baseUrl p = substituteTemplate baseUrlTemplate p
         ghcOpts  <- haddockGhcArgs
+        -- These are the options which are necessary to perform the build. Additional
+        -- options such as `--hyperlinked-source`, `--hoogle`, `--quickjump` are
+        -- added by the `extraArgs` field in the flavour. The defaults are provided
+        -- by `defaultHaddockExtraArgs`.
         mconcat
             [ arg "--verbosity=0"
             , arg $ "-B" ++ root -/- stageString Stage1 -/- "lib"
@@ -57,9 +61,6 @@ haddockBuilderArgs = mconcat
             , arg $ "--odir=" ++ takeDirectory output
             , arg $ "--dump-interface=" ++ output
             , arg "--html"
-            , arg "--hyperlinked-source"
-            , arg "--hoogle"
-            , arg "--quickjump"
             , arg $ "--title=" ++ pkgName pkg ++ "-" ++ version
                     ++ ": " ++ synopsis
             , arg $ "--prologue=" ++ takeDirectory output -/- "haddock-prologue.txt"


=====================================
hadrian/src/Settings/Default.hs
=====================================
@@ -7,7 +7,7 @@ module Settings.Default (
 
     -- * Default command line arguments for various builders
     SourceArgs (..), sourceArgs, defaultBuilderArgs, defaultPackageArgs,
-    defaultExtraArgs,
+    defaultExtraArgs, defaultHaddockExtraArgs,
 
     -- * Default build flavour and BigNum backend
     defaultFlavour, defaultBignumBackend
@@ -219,7 +219,13 @@ sourceArgs SourceArgs {..} = builder Ghc ? mconcat
 
 -- | All default command line arguments.
 defaultExtraArgs :: Args
-defaultExtraArgs = sourceArgs defaultSourceArgs
+defaultExtraArgs =
+  mconcat [ sourceArgs defaultSourceArgs, defaultHaddockExtraArgs ]
+
+defaultHaddockExtraArgs :: Args
+defaultHaddockExtraArgs = builder (Haddock BuildPackage) ?
+  mconcat [ arg "--hyperlinked-source", arg "--hoogle", arg "--quickjump" ]
+
 
 -- | Default source arguments, e.g. optimisation settings.
 defaultSourceArgs :: SourceArgs


=====================================
hadrian/src/Settings/Default.hs-boot
=====================================
@@ -1,6 +1,6 @@
 module Settings.Default (
     SourceArgs (..), sourceArgs, defaultBuilderArgs, defaultPackageArgs,
-    defaultExtraArgs, defaultLibraryWays, defaultRtsWays,
+    defaultExtraArgs, defaultHaddockExtraArgs, defaultLibraryWays, defaultRtsWays,
     defaultFlavour, defaultBignumBackend
     ) where
 
@@ -15,7 +15,7 @@ data SourceArgs = SourceArgs
 
 sourceArgs :: SourceArgs -> Args
 
-defaultBuilderArgs, defaultPackageArgs, defaultExtraArgs :: Args
+defaultBuilderArgs, defaultPackageArgs, defaultExtraArgs, defaultHaddockExtraArgs :: Args
 defaultLibraryWays, defaultRtsWays :: Ways
 defaultFlavour :: Flavour
 defaultBignumBackend :: String


=====================================
hadrian/src/Settings/Flavours/Benchmark.hs
=====================================
@@ -10,7 +10,7 @@ import {-# SOURCE #-} Settings.Default
 benchmarkFlavour :: Flavour
 benchmarkFlavour = defaultFlavour
     { name = "bench"
-    , extraArgs = benchmarkArgs
+    , extraArgs = benchmarkArgs <> defaultHaddockExtraArgs
     , libraryWays = pure $ Set.fromList [vanilla]
     , rtsWays = Set.fromList <$> mconcat [pure [vanilla], targetSupportsThreadedRts ? pure [threaded]] }
 


=====================================
hadrian/src/Settings/Flavours/Development.hs
=====================================
@@ -12,7 +12,7 @@ import {-# SOURCE #-} Settings.Default
 developmentFlavour :: Stage -> Flavour
 developmentFlavour ghcStage = defaultFlavour
     { name = "devel" ++ stageString ghcStage
-    , extraArgs = developmentArgs ghcStage
+    , extraArgs = developmentArgs ghcStage <> defaultHaddockExtraArgs
     , libraryWays = pure $ Set.fromList [vanilla]
     , rtsWays = Set.fromList <$> mconcat [pure [vanilla, debug], targetSupportsThreadedRts ? pure [threaded, threadedDebug]]
     , dynamicGhcPrograms = return False


=====================================
hadrian/src/Settings/Flavours/Performance.hs
=====================================
@@ -8,7 +8,7 @@ import {-# SOURCE #-} Settings.Default
 performanceFlavour :: Flavour
 performanceFlavour = splitSections $ defaultFlavour
     { name = "perf"
-    , extraArgs = performanceArgs }
+    , extraArgs = performanceArgs <> defaultHaddockExtraArgs }
 
 performanceArgs :: Args
 performanceArgs = sourceArgs SourceArgs


=====================================
hadrian/src/Settings/Flavours/Validate.hs
=====================================
@@ -12,7 +12,7 @@ import {-# SOURCE #-} Settings.Default
 validateFlavour :: Flavour
 validateFlavour = enableLinting $ werror $ defaultFlavour
     { name = "validate"
-    , extraArgs = validateArgs
+    , extraArgs = validateArgs <> defaultHaddockExtraArgs
     , libraryWays = Set.fromList <$>
                     mconcat [ pure [vanilla]
                             , notStage0 ? platformSupportsSharedLibs ? pure [dynamic]



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/e4350b41b54c604e222fe3b0c4edb80beee2c0b3

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/e4350b41b54c604e222fe3b0c4edb80beee2c0b3
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20230721/56cf1863/attachment-0001.html>