Skip to content

Commit

Permalink
Cabal: Don't pass -D__HADDOCK_VERSION__ to haddock
Browse files Browse the repository at this point in the history
We no longer define the `__HADDOCK_VERSION__` macro when invoking GHC
through Haddock, since doing so essentially guarantees recompilation
during documentation generation.

We audited all uses of `__HADDOCK_VERSION__` in hackage, ensuring there
was a reasonable path forward to migrate away from using
`__HADDOCK_VERSION__` for each, while generating the same documentation
as it did before.

If you are a user of `__HADDOCK_VERSION__`, please take a look at the
discussion in haskell#9177 and reach out
to us if your use case is not covered.

Reverts the version-cpp flag introduced in the previous commit to avoid
a workaround. Instead, we get rid of the problem (`__HADDOCK_VERSION__`) at its root.

See the discussion in haskell#9177
  • Loading branch information
alt-romes authored and mmhat committed Jun 24, 2024
1 parent 5580d00 commit 3a55d7e
Show file tree
Hide file tree
Showing 19 changed files with 30 additions and 116 deletions.
65 changes: 4 additions & 61 deletions Cabal/src/Distribution/Simple/Haddock.hs
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,6 @@ import Distribution.Types.ComponentLocalBuildInfo
import Distribution.Types.ExposedModule
import Distribution.Types.LocalBuildInfo
import Distribution.Types.TargetInfo
import Distribution.Utils.NubList
import Distribution.Utils.Path hiding
( Dir
)
Expand All @@ -92,8 +91,6 @@ import qualified Distribution.Utils.ShortText as ShortText
import Distribution.Verbosity
import Distribution.Version

import Language.Haskell.Extension

import Control.Monad
import Data.Either (rights)
import System.Directory (doesDirectoryExist, doesFileExist)
Expand Down Expand Up @@ -329,11 +326,6 @@ haddock_setupHooks
[] -> allTargetsInBuildOrder' pkg_descr lbi
_ -> targets

version' =
if flag haddockVersionCPP
then Just version
else Nothing

mtmp
| version >= mkVersion [2, 28, 0] = const Nothing
| otherwise = Just
Expand Down Expand Up @@ -380,7 +372,6 @@ haddock_setupHooks
lbi'
clbi
htmlTemplate
version'
exe
let exeArgs' = commonArgs `mappend` exeArgs
runHaddock
Expand Down Expand Up @@ -420,7 +411,6 @@ haddock_setupHooks
lbi'
clbi
htmlTemplate
version'
lib
let libArgs' = commonArgs `mappend` libArgs
runHaddock verbosity mbWorkDir tmpFileOpts comp platform haddockProg True libArgs'
Expand Down Expand Up @@ -467,7 +457,6 @@ haddock_setupHooks
lbi'
clbi
htmlTemplate
version'
flib
let libArgs' = commonArgs `mappend` flibArgs
runHaddock verbosity mbWorkDir tmpFileOpts comp platform haddockProg True libArgs'
Expand Down Expand Up @@ -613,17 +602,13 @@ mkHaddockArgs
-> ComponentLocalBuildInfo
-> Maybe PathTemplate
-- ^ template for HTML location
-> Maybe Version
-- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
-- macro
-> [SymbolicPath Pkg File]
-> BuildInfo
-> IO HaddockArgs
mkHaddockArgs verbosity mtmp lbi clbi htmlTemplate haddockVersion inFiles bi = do
mkHaddockArgs verbosity mtmp lbi clbi htmlTemplate inFiles bi = do
ifaceArgs <- getInterfaces verbosity lbi clbi htmlTemplate
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
Expand All @@ -635,7 +620,6 @@ mkHaddockArgs verbosity mtmp lbi clbi htmlTemplate haddockVersion inFiles bi = d
, ghcOptHiDir = maybe (ghcOptHiDir vanillaOpts') (toFlag . coerceSymbolicPath) mtmp
, ghcOptStubDir = maybe (ghcOptStubDir vanillaOpts') (toFlag . coerceSymbolicPath) mtmp
}
`mappend` getGhcCppOpts haddockVersion bi
sharedOpts =
vanillaOpts
{ ghcOptDynLinkMode = toFlag GhcDynamicOnly
Expand Down Expand Up @@ -668,12 +652,9 @@ fromLibrary
-> ComponentLocalBuildInfo
-> Maybe PathTemplate
-- ^ template for HTML location
-> Maybe Version
-- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
-- macro
-> Library
-> IO HaddockArgs
fromLibrary verbosity mtmp lbi clbi htmlTemplate haddockVersion lib = do
fromLibrary verbosity mtmp lbi clbi htmlTemplate lib = do
inFiles <- map snd `fmap` getLibSourceFiles verbosity lbi lib clbi
args <-
mkHaddockArgs
Expand All @@ -682,7 +663,6 @@ fromLibrary verbosity mtmp lbi clbi htmlTemplate haddockVersion lib = do
lbi
clbi
htmlTemplate
haddockVersion
inFiles
(libBuildInfo lib)
return
Expand All @@ -699,12 +679,9 @@ fromExecutable
-> ComponentLocalBuildInfo
-> Maybe PathTemplate
-- ^ template for HTML location
-> Maybe Version
-- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
-- macro
-> Executable
-> IO HaddockArgs
fromExecutable verbosity mtmp lbi clbi htmlTemplate haddockVersion exe = do
fromExecutable verbosity mtmp lbi clbi htmlTemplate exe = do
inFiles <- map snd `fmap` getExeSourceFiles verbosity lbi exe clbi
args <-
mkHaddockArgs
Expand All @@ -713,7 +690,6 @@ fromExecutable verbosity mtmp lbi clbi htmlTemplate haddockVersion exe = do
lbi
clbi
htmlTemplate
haddockVersion
inFiles
(buildInfo exe)
return
Expand All @@ -731,12 +707,9 @@ fromForeignLib
-> ComponentLocalBuildInfo
-> Maybe PathTemplate
-- ^ template for HTML location
-> Maybe Version
-- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
-- macro
-> ForeignLib
-> IO HaddockArgs
fromForeignLib verbosity mtmp lbi clbi htmlTemplate haddockVersion flib = do
fromForeignLib verbosity mtmp lbi clbi htmlTemplate flib = do
inFiles <- map snd `fmap` getFLibSourceFiles verbosity lbi flib clbi
args <-
mkHaddockArgs
Expand All @@ -745,7 +718,6 @@ fromForeignLib verbosity mtmp lbi clbi htmlTemplate haddockVersion flib = do
lbi
clbi
htmlTemplate
haddockVersion
inFiles
(foreignLibBuildInfo flib)
return
Expand Down Expand Up @@ -796,35 +768,6 @@ getReexports LibComponentLocalBuildInfo{componentExposedModules = mods} =
mapMaybe exposedReexport mods
getReexports _ = []

getGhcCppOpts
:: Maybe Version
-- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
-- macro
-> BuildInfo
-> GhcOptions
getGhcCppOpts haddockVersion bi =
mempty
{ ghcOptExtensions = toNubListR [EnableExtension CPP | needsCpp]
, ghcOptCppOptions = defines
}
where
needsCpp = EnableExtension CPP `elem` usedExtensions bi
defines =
[ "-D__HADDOCK_VERSION__=" ++ show vn
| Just vn <- [versionInt . versionNumbers <$> haddockVersion]
]
where
-- 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
-> LocalBuildInfo
Expand Down
18 changes: 0 additions & 18 deletions Cabal/src/Distribution/Simple/Setup/Haddock.hs
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,6 @@ data HaddockFlags = HaddockFlags
, haddockBaseUrl :: Flag String
, haddockResourcesDir :: Flag String
, haddockOutputDir :: Flag FilePath
, haddockVersionCPP :: Flag Bool
}
deriving (Show, Generic, Typeable)

Expand Down Expand Up @@ -171,7 +170,6 @@ defaultHaddockFlags =
, haddockBaseUrl = NoFlag
, haddockResourcesDir = NoFlag
, haddockOutputDir = NoFlag
, haddockVersionCPP = Flag False
}

haddockCommand :: CommandUI HaddockFlags
Expand Down Expand Up @@ -380,13 +378,6 @@ haddockOptions showOrParseArgs =
haddockOutputDir
(\v flags -> flags{haddockOutputDir = v})
(reqArgFlag "DIR")
, option
""
["version-cpp"]
"Define the __HADDOCK_VERSION__ macro when invoking GHC through Haddock. This will likely trigger recompilation during documentation generation."
haddockVersionCPP
(\v flags -> flags{haddockVersionCPP = v})
trueArg
]

emptyHaddockFlags :: HaddockFlags
Expand Down Expand Up @@ -451,7 +442,6 @@ data HaddockProjectFlags = HaddockProjectFlags
, -- haddockBaseUrl is not supported, a fixed value is provided
haddockProjectResourcesDir :: Flag String
, haddockProjectOutputDir :: Flag FilePath
, haddockProjectVersionCPP :: Flag Bool
}
deriving (Show, Generic, Typeable)

Expand All @@ -477,7 +467,6 @@ defaultHaddockProjectFlags =
, haddockProjectResourcesDir = NoFlag
, haddockProjectOutputDir = NoFlag
, haddockProjectInterfaces = NoFlag
, haddockProjectVersionCPP = Flag False
}

haddockProjectCommand :: CommandUI HaddockProjectFlags
Expand Down Expand Up @@ -631,13 +620,6 @@ haddockProjectOptions _showOrParseArgs =
haddockProjectOutputDir
(\v flags -> flags{haddockProjectOutputDir = v})
(reqArgFlag "DIR")
, option
""
["version-cpp"]
"Define the __HADDOCK_VERSION__ macro when invoking GHC through Haddock. This will likely trigger recompilation during documentation generation."
haddockProjectVersionCPP
(\v flags -> flags{haddockProjectVersionCPP = v})
trueArg
]

emptyHaddockProjectFlags :: HaddockProjectFlags
Expand Down
1 change: 0 additions & 1 deletion cabal-install/src/Distribution/Client/CmdHaddockProject.hs
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,6 @@ haddockProjectAction flags _extraArgs globalFlags = do
, haddockKeepTempFiles = haddockProjectKeepTempFiles flags
, haddockResourcesDir = haddockProjectResourcesDir flags
, haddockOutputDir = haddockProjectOutputDir flags
, haddockVersionCPP = haddockProjectVersionCPP flags
}
nixFlags =
(commandDefaultFlags CmdHaddock.haddockCommand)
Expand Down
1 change: 0 additions & 1 deletion cabal-install/src/Distribution/Client/Config.hs
Original file line number Diff line number Diff line change
Expand Up @@ -632,7 +632,6 @@ instance Semigroup SavedConfig where
, haddockBaseUrl = combine haddockBaseUrl
, haddockResourcesDir = combine haddockResourcesDir
, haddockOutputDir = combine haddockOutputDir
, haddockVersionCPP = combine haddockVersionCPP
}
where
combine = combine' savedHaddockFlags
Expand Down
2 changes: 0 additions & 2 deletions cabal-install/src/Distribution/Client/PackageHash.hs
Original file line number Diff line number Diff line change
Expand Up @@ -240,7 +240,6 @@ data PackageHashConfigInputs = PackageHashConfigInputs
, pkgHashHaddockBaseUrl :: Maybe String
, pkgHashHaddockResourcesDir :: Maybe String
, pkgHashHaddockOutputDir :: Maybe FilePath
, pkgHashHaddockVersionCPP :: Bool
-- TODO: [required eventually] pkgHashToolsVersions ?
-- TODO: [required eventually] pkgHashToolsExtraOptions ?
}
Expand Down Expand Up @@ -350,7 +349,6 @@ renderPackageHashInputs
, opt "haddock-base-url" Nothing (fromMaybe "") pkgHashHaddockBaseUrl
, opt "haddock-resources-dir" Nothing (fromMaybe "") pkgHashHaddockResourcesDir
, opt "haddock-output-dir" Nothing (fromMaybe "") pkgHashHaddockOutputDir
, opt "haddock-version-cpp" False prettyShow pkgHashHaddockVersionCPP
]
++ Map.foldrWithKey (\prog args acc -> opt (prog ++ "-options") [] unwords args : acc) [] pkgHashProgramArgs
where
Expand Down
3 changes: 0 additions & 3 deletions cabal-install/src/Distribution/Client/ProjectConfig/Legacy.hs
Original file line number Diff line number Diff line change
Expand Up @@ -823,7 +823,6 @@ convertLegacyPerPackageFlags
, haddockBaseUrl = packageConfigHaddockBaseUrl
, haddockResourcesDir = packageConfigHaddockResourcesDir
, haddockOutputDir = packageConfigHaddockOutputDir
, haddockVersionCPP = packageConfigHaddockVersionCPP
} = haddockFlags

TestFlags
Expand Down Expand Up @@ -1221,7 +1220,6 @@ convertToLegacyPerPackageConfig PackageConfig{..} =
, haddockBaseUrl = packageConfigHaddockBaseUrl
, haddockResourcesDir = packageConfigHaddockResourcesDir
, haddockOutputDir = packageConfigHaddockOutputDir
, haddockVersionCPP = packageConfigHaddockVersionCPP
}

testFlags =
Expand Down Expand Up @@ -1623,7 +1621,6 @@ legacyPackageConfigFieldDescrs =
, "base-url"
, "resources-dir"
, "output-dir"
, "version-cpp"
]
. commandOptionsToFields
)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -307,7 +307,6 @@ data PackageConfig = PackageConfig
, packageConfigHaddockBaseUrl :: Flag String -- TODO: [required eventually] use this
, packageConfigHaddockResourcesDir :: Flag String -- TODO: [required eventually] use this
, packageConfigHaddockOutputDir :: Flag FilePath -- TODO: [required eventually] use this
, packageConfigHaddockVersionCPP :: Flag Bool -- TODO: [required eventually] use this
, packageConfigHaddockForHackage :: Flag HaddockTarget
, -- Test options
packageConfigTestHumanLog :: Flag PathTemplate
Expand Down
3 changes: 0 additions & 3 deletions cabal-install/src/Distribution/Client/ProjectPlanning.hs
Original file line number Diff line number Diff line change
Expand Up @@ -2280,7 +2280,6 @@ elaborateInstallPlan
elabHaddockBaseUrl = perPkgOptionMaybe pkgid packageConfigHaddockBaseUrl
elabHaddockResourcesDir = perPkgOptionMaybe pkgid packageConfigHaddockResourcesDir
elabHaddockOutputDir = perPkgOptionMaybe pkgid packageConfigHaddockOutputDir
elabHaddockVersionCPP = perPkgOptionFlag pkgid False packageConfigHaddockVersionCPP

elabTestMachineLog = perPkgOptionMaybe pkgid packageConfigTestMachineLog
elabTestHumanLog = perPkgOptionMaybe pkgid packageConfigTestHumanLog
Expand Down Expand Up @@ -4148,7 +4147,6 @@ setupHsHaddockFlags
, haddockBaseUrl = maybe mempty toFlag elabHaddockBaseUrl
, haddockResourcesDir = maybe mempty toFlag elabHaddockResourcesDir
, haddockOutputDir = maybe mempty toFlag elabHaddockOutputDir
, haddockVersionCPP = maybe mempty toFlag elabHaddockVersionCPP
}

setupHsHaddockArgs :: ElaboratedConfiguredPackage -> [String]
Expand Down Expand Up @@ -4307,7 +4305,6 @@ packageHashConfigInputs shared@ElaboratedSharedConfig{..} pkg =
, pkgHashHaddockBaseUrl = elabHaddockBaseUrl
, pkgHashHaddockResourcesDir = elabHaddockResourcesDir
, pkgHashHaddockOutputDir = elabHaddockOutputDir
, pkgHashHaddockVersionCPP = elabHaddockVersionCPP
}
where
ElaboratedConfiguredPackage{..} = normaliseConfiguredPackage shared pkg
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -302,7 +302,6 @@ data ElaboratedConfiguredPackage = ElaboratedConfiguredPackage
, elabHaddockBaseUrl :: Maybe String
, elabHaddockResourcesDir :: Maybe String
, elabHaddockOutputDir :: Maybe FilePath
, elabHaddockVersionCPP :: Bool
, elabTestMachineLog :: Maybe PathTemplate
, elabTestHumanLog :: Maybe PathTemplate
, elabTestShowDetails :: Maybe TestShowDetails
Expand Down
1 change: 0 additions & 1 deletion cabal-install/src/Distribution/Client/Setup.hs
Original file line number Diff line number Diff line change
Expand Up @@ -2437,7 +2437,6 @@ haddockOptions showOrParseArgs =
, "base-url"
, "resources-dir"
, "output-dir"
, "version-cpp"
]
]

Expand Down
1 change: 0 additions & 1 deletion cabal-install/tests/IntegrationTests2.hs
Original file line number Diff line number Diff line change
Expand Up @@ -2101,7 +2101,6 @@ testConfigOptionComments = do
" -- base-url" @=? findLineWith True "base-url" defaultConfigFile
" -- resources-dir" @=? findLineWith True "resources-dir" defaultConfigFile
" -- output-dir" @=? findLineWith True "output-dir" defaultConfigFile
" -- version-cpp" @=? findLineWith True "version-cpp" defaultConfigFile

" -- interactive" @=? findLineWith True "interactive" defaultConfigFile
" -- quiet" @=? findLineWith True "quiet" defaultConfigFile
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -726,7 +726,6 @@ instance Arbitrary PackageConfig where
<*> arbitrary
<*> arbitrary
<*> arbitrary
<*> arbitrary
<*> arbitraryFlag arbitraryShortToken
<*> arbitrary
<*> shortListOf 5 arbitrary
Expand Down Expand Up @@ -794,7 +793,6 @@ instance Arbitrary PackageConfig where
, packageConfigHaddockBaseUrl = x55
, packageConfigHaddockResourcesDir = x56
, packageConfigHaddockOutputDir = x57
, packageConfigHaddockVersionCPP = x58
, packageConfigTestHumanLog = x44
, packageConfigTestMachineLog = x45
, packageConfigTestShowDetails = x46
Expand Down Expand Up @@ -858,7 +856,6 @@ instance Arbitrary PackageConfig where
, packageConfigHaddockBaseUrl = x55'
, packageConfigHaddockResourcesDir = x56'
, packageConfigHaddockOutputDir = x57'
, packageConfigHaddockVersionCPP = x58'
, packageConfigTestHumanLog = x44'
, packageConfigTestMachineLog = x45'
, packageConfigTestShowDetails = x46'
Expand All @@ -881,7 +878,6 @@ instance Arbitrary PackageConfig where
, (x44', x45', x46', x47', x48', x49', x51', x52', x54', x55')
, x56'
, x57'
, x58'
)
) <-
shrink
Expand All @@ -907,7 +903,6 @@ instance Arbitrary PackageConfig where
, (x44, x45, x46, x47, x48, x49, x51, x52, x54, x55)
, x56
, x57
, x58
)
)
]
Expand Down
Loading

0 comments on commit 3a55d7e

Please sign in to comment.