Skip to content

Commit 4dd9273

Browse files
23Skidoo23Skidoo
authored
Merge pull request #3956 from 23Skidoo/backport-3452
Backport #3452 to the 1.24 branch
2 parents 73e09ec + c7a3ef3 commit 4dd9273

File tree

6 files changed

+58
-34
lines changed

6 files changed

+58
-34
lines changed

‎Cabal/Distribution/Simple/BuildPaths.hs

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
module Distribution.Simple.BuildPaths (
1515
defaultDistPref, srcPref,
16-
hscolourPref, haddockPref,
16+
haddockDirName, hscolourPref, haddockPref,
1717
autogenModulesDir,
1818

1919
autogenModuleName,
@@ -48,12 +48,19 @@ import System.FilePath ((</>), (<.>))
4848
srcPref :: FilePath -> FilePath
4949
srcPref distPref = distPref </> "src"
5050

51-
hscolourPref :: FilePath -> PackageDescription -> FilePath
51+
hscolourPref :: HaddockTarget -> FilePath -> PackageDescription -> FilePath
5252
hscolourPref = haddockPref
5353

54-
haddockPref :: FilePath -> PackageDescription -> FilePath
55-
haddockPref distPref pkg_descr
56-
= distPref </> "doc" </> "html" </> display (packageName pkg_descr)
54+
-- | This is the name of the directory in which the generated haddocks
55+
-- should be stored. It does not include the @<dist>/doc/html@ prefix.
56+
haddockDirName :: HaddockTarget -> PackageDescription -> FilePath
57+
haddockDirName ForDevelopment = display . packageName
58+
haddockDirName ForHackage = (++ "-docs") . display . packageId
59+
60+
-- | The directory to which generated haddock documentation should be written.
61+
haddockPref :: HaddockTarget -> FilePath -> PackageDescription -> FilePath
62+
haddockPref haddockTarget distPref pkg_descr
63+
= distPref </> "doc" </> "html" </> haddockDirName haddockTarget pkg_descr
5764

5865
-- |The directory in which we put auto-generated modules
5966
autogenModulesDir :: LocalBuildInfo -> String

‎Cabal/Distribution/Simple/Haddock.hs

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -135,22 +135,24 @@ haddock pkg_descr lbi suffixes flags' = do
135135
comp = compiler lbi
136136
platform = hostPlatform lbi
137137

138-
flags
139-
| fromFlag (haddockForHackage flags') = flags'
138+
flags = case haddockTarget of
139+
ForDevelopment -> flags'
140+
ForHackage -> flags'
140141
{ haddockHoogle = Flag True
141142
, haddockHtml = Flag True
142143
, haddockHtmlLocation = Flag (pkg_url ++ "/docs")
143144
, haddockContents = Flag (toPathTemplate pkg_url)
144145
, haddockHscolour = Flag True
145146
}
146-
| otherwise = flags'
147147
pkg_url = "/package/$pkg-$version"
148148
flag f = fromFlag $ f flags
149149

150150
tmpFileOpts = defaultTempFileOptions
151151
{ optKeepTempFiles = flag haddockKeepTempFiles }
152152
htmlTemplate = fmap toPathTemplate . flagToMaybe . haddockHtmlLocation
153153
$ flags
154+
haddockTarget =
155+
fromFlagOrDefault ForDevelopment (haddockForHackage flags')
154156

155157
setupMessage verbosity "Running Haddock for" (packageId pkg_descr)
156158
(confHaddock, version, _) <-
@@ -180,15 +182,14 @@ haddock pkg_descr lbi suffixes flags' = do
180182
initialBuildSteps (flag haddockDistPref) pkg_descr lbi verbosity
181183

182184
when (flag haddockHscolour) $
183-
hscolour' (warn verbosity) pkg_descr lbi suffixes
185+
hscolour' (warn verbosity) haddockTarget pkg_descr lbi suffixes
184186
(defaultHscolourFlags `mappend` haddockToHscolour flags)
185187

186188
libdirArgs <- getGhcLibDir verbosity lbi
187189
let commonArgs = mconcat
188190
[ libdirArgs
189191
, fromFlags (haddockTemplateEnv lbi (packageId pkg_descr)) flags
190-
, fromPackageDescription forDist pkg_descr ]
191-
forDist = fromFlagOrDefault False (haddockForHackage flags)
192+
, fromPackageDescription haddockTarget pkg_descr ]
192193

193194
let pre c = preprocessComponent pkg_descr c lbi False verbosity suffixes
194195
withAllComponentsInBuildOrder pkg_descr lbi $ \component clbi -> do
@@ -249,21 +250,19 @@ fromFlags env flags =
249250
argOutputDir = maybe mempty Dir . flagToMaybe $ haddockDistPref flags
250251
}
251252

252-
fromPackageDescription :: Bool -> PackageDescription -> HaddockArgs
253-
fromPackageDescription forDist pkg_descr =
253+
fromPackageDescription :: HaddockTarget -> PackageDescription -> HaddockArgs
254+
fromPackageDescription haddockTarget pkg_descr =
254255
mempty { argInterfaceFile = Flag $ haddockName pkg_descr,
255256
argPackageName = Flag $ packageId $ pkg_descr,
256-
argOutputDir = Dir $ "doc" </> "html" </> name,
257+
argOutputDir = Dir $
258+
"doc" </> "html" </> haddockDirName haddockTarget pkg_descr,
257259
argPrologue = Flag $ if null desc then synopsis pkg_descr
258260
else desc,
259261
argTitle = Flag $ showPkg ++ subtitle
260262
}
261263
where
262264
desc = PD.description pkg_descr
263265
showPkg = display (packageId pkg_descr)
264-
name
265-
| forDist = showPkg ++ "-docs"
266-
| otherwise = display (packageName pkg_descr)
267266
subtitle | null (synopsis pkg_descr) = ""
268267
| otherwise = ": " ++ synopsis pkg_descr
269268

@@ -653,18 +652,19 @@ hscolour pkg_descr lbi suffixes flags = do
653652
-- we preprocess even if hscolour won't be found on the machine
654653
-- will this upset someone?
655654
initialBuildSteps distPref pkg_descr lbi verbosity
656-
hscolour' die pkg_descr lbi suffixes flags
655+
hscolour' die ForDevelopment pkg_descr lbi suffixes flags
657656
where
658657
verbosity = fromFlag (hscolourVerbosity flags)
659658
distPref = fromFlag $ hscolourDistPref flags
660659

661660
hscolour' :: (String -> IO ()) -- ^ Called when the 'hscolour' exe is not found.
661+
-> HaddockTarget
662662
-> PackageDescription
663663
-> LocalBuildInfo
664664
-> [PPSuffixHandler]
665665
-> HscolourFlags
666666
-> IO ()
667-
hscolour' onNoHsColour pkg_descr lbi suffixes flags =
667+
hscolour' onNoHsColour haddockTarget pkg_descr lbi suffixes flags =
668668
either onNoHsColour (\(hscolourProg, _, _) -> go hscolourProg) =<<
669669
lookupProgramVersion verbosity hscolourProgram
670670
(orLaterVersion (Version [1,8] [])) (withPrograms lbi)
@@ -673,15 +673,15 @@ hscolour' onNoHsColour pkg_descr lbi suffixes flags =
673673
go hscolourProg = do
674674
setupMessage verbosity "Running hscolour for" (packageId pkg_descr)
675675
createDirectoryIfMissingVerbose verbosity True $
676-
hscolourPref distPref pkg_descr
676+
hscolourPref haddockTarget distPref pkg_descr
677677

678678
let pre c = preprocessComponent pkg_descr c lbi False verbosity suffixes
679679
withAllComponentsInBuildOrder pkg_descr lbi $ \comp _ -> do
680680
pre comp
681681
let
682682
doExe com = case (compToExe com) of
683683
Just exe -> do
684-
let outputDir = hscolourPref distPref pkg_descr
684+
let outputDir = hscolourPref haddockTarget distPref pkg_descr
685685
</> exeName exe </> "src"
686686
runHsColour hscolourProg outputDir =<< getExeSourceFiles lbi exe
687687
Nothing -> do
@@ -690,7 +690,7 @@ hscolour' onNoHsColour pkg_descr lbi suffixes flags =
690690
return ()
691691
case comp of
692692
CLib lib -> do
693-
let outputDir = hscolourPref distPref pkg_descr </> "src"
693+
let outputDir = hscolourPref haddockTarget distPref pkg_descr </> "src"
694694
runHsColour hscolourProg outputDir =<< getLibSourceFiles lbi lib
695695
CExe _ -> when (fromFlag (hscolourExecutables flags)) $ doExe comp
696696
CTest _ -> when (fromFlag (hscolourTestSuites flags)) $ doExe comp

‎Cabal/Distribution/Simple/Install.hs

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,8 @@ import Distribution.Simple.Utils
2626
, die, info, notice, warn, matchDirFileGlob )
2727
import Distribution.Simple.Compiler
2828
( CompilerFlavor(..), compilerFlavor )
29-
import Distribution.Simple.Setup (CopyFlags(..), fromFlag)
29+
import Distribution.Simple.Setup (CopyFlags(..), fromFlag
30+
,HaddockTarget(ForDevelopment))
3031

3132
import qualified Distribution.Simple.GHC as GHC
3233
import qualified Distribution.Simple.GHCJS as GHCJS
@@ -79,22 +80,22 @@ install pkg_descr lbi flags = do
7980

8081
unless (hasLibs pkg_descr || hasExes pkg_descr) $
8182
die "No executables and no library found. Nothing to do."
82-
docExists <- doesDirectoryExist $ haddockPref distPref pkg_descr
83-
info verbosity ("directory " ++ haddockPref distPref pkg_descr ++
83+
docExists <- doesDirectoryExist $ haddockPref ForDevelopment distPref pkg_descr
84+
info verbosity ("directory " ++ haddockPref ForDevelopment distPref pkg_descr ++
8485
" does exist: " ++ show docExists)
8586

8687
installDataFiles verbosity pkg_descr dataPref
8788

8889
when docExists $ do
8990
createDirectoryIfMissingVerbose verbosity True htmlPref
9091
installDirectoryContents verbosity
91-
(haddockPref distPref pkg_descr) htmlPref
92+
(haddockPref ForDevelopment distPref pkg_descr) htmlPref
9293
-- setPermissionsRecursive [Read] htmlPref
9394
-- The haddock interface file actually already got installed
9495
-- in the recursive copy, but now we install it where we actually
9596
-- want it to be (normally the same place). We could remove the
9697
-- copy in htmlPref first.
97-
let haddockInterfaceFileSrc = haddockPref distPref pkg_descr
98+
let haddockInterfaceFileSrc = haddockPref ForDevelopment distPref pkg_descr
9899
</> haddockName pkg_descr
99100
haddockInterfaceFileDest = interfacePref </> haddockName pkg_descr
100101
-- We only generate the haddock interface file for libs, So if the

‎Cabal/Distribution/Simple/Setup.hs

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ module Distribution.Simple.Setup (
3939
configAbsolutePaths, readPackageDbList, showPackageDbList,
4040
CopyFlags(..), emptyCopyFlags, defaultCopyFlags, copyCommand,
4141
InstallFlags(..), emptyInstallFlags, defaultInstallFlags, installCommand,
42+
HaddockTarget(..),
4243
HaddockFlags(..), emptyHaddockFlags, defaultHaddockFlags, haddockCommand,
4344
HscolourFlags(..), emptyHscolourFlags, defaultHscolourFlags, hscolourCommand,
4445
BuildFlags(..), emptyBuildFlags, defaultBuildFlags, buildCommand,
@@ -1209,13 +1210,27 @@ hscolourCommand = CommandUI
12091210
-- * Haddock flags
12101211
-- ------------------------------------------------------------
12111212

1213+
1214+
-- | When we build haddock documentation, there are two cases:
1215+
--
1216+
-- 1. We build haddocks only for the current development version,
1217+
-- intended for local use and not for distribution. In this case,
1218+
-- we store the generated documentation in @<dist>/doc/html/<package name>@.
1219+
--
1220+
-- 2. We build haddocks for intended for uploading them to hackage.
1221+
-- In this case, we need to follow the layout that hackage expects
1222+
-- from documentation tarballs, and we might also want to use different
1223+
-- flags than for development builds, so in this case we store the generated
1224+
-- documentation in @<dist>/doc/html/<package id>-docs@.
1225+
data HaddockTarget = ForHackage | ForDevelopment deriving (Eq, Show, Generic)
1226+
12121227
data HaddockFlags = HaddockFlags {
12131228
haddockProgramPaths :: [(String, FilePath)],
12141229
haddockProgramArgs :: [(String, [String])],
12151230
haddockHoogle :: Flag Bool,
12161231
haddockHtml :: Flag Bool,
12171232
haddockHtmlLocation :: Flag String,
1218-
haddockForHackage :: Flag Bool,
1233+
haddockForHackage :: Flag HaddockTarget,
12191234
haddockExecutables :: Flag Bool,
12201235
haddockTestSuites :: Flag Bool,
12211236
haddockBenchmarks :: Flag Bool,
@@ -1237,7 +1252,7 @@ defaultHaddockFlags = HaddockFlags {
12371252
haddockHoogle = Flag False,
12381253
haddockHtml = Flag False,
12391254
haddockHtmlLocation = NoFlag,
1240-
haddockForHackage = Flag False,
1255+
haddockForHackage = Flag ForDevelopment,
12411256
haddockExecutables = Flag False,
12421257
haddockTestSuites = Flag False,
12431258
haddockBenchmarks = Flag False,
@@ -1306,7 +1321,7 @@ haddockOptions showOrParseArgs =
13061321
,option "" ["for-hackage"]
13071322
"Collection of flags to generate documentation suitable for upload to hackage"
13081323
haddockForHackage (\v flags -> flags { haddockForHackage = v })
1309-
trueArg
1324+
(noArg (Flag ForHackage))
13101325

13111326
,option "" ["executables"]
13121327
"Run haddock for Executables targets"

‎cabal-install/Distribution/Client/Config.hs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1088,7 +1088,7 @@ haddockFlagsFields = [ field
10881088
name = fieldName field
10891089
, name `notElem` exclusions ]
10901090
where
1091-
exclusions = ["verbose", "builddir"]
1091+
exclusions = ["verbose", "builddir", "for-hackage"]
10921092

10931093
-- | Fields for the 'program-locations' section.
10941094
withProgramsFields :: [FieldDescr [(String, FilePath)]]

‎cabal-install/Main.hs

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,8 @@ import Distribution.Client.Setup
4646
, manpageCommand
4747
)
4848
import Distribution.Simple.Setup
49-
( HaddockFlags(..), haddockCommand, defaultHaddockFlags
49+
( HaddockTarget(..)
50+
, HaddockFlags(..), haddockCommand, defaultHaddockFlags
5051
, HscolourFlags(..), hscolourCommand
5152
, ReplFlags(..)
5253
, CopyFlags(..), copyCommand
@@ -904,7 +905,7 @@ haddockAction haddockFlags extraArgs globalFlags = do
904905
setupScriptOptions = defaultSetupScriptOptions { useDistPref = distPref }
905906
setupWrapper verbosity setupScriptOptions Nothing
906907
haddockCommand (const haddockFlags') extraArgs
907-
when (fromFlagOrDefault False $ haddockForHackage haddockFlags) $ do
908+
when (haddockForHackage haddockFlags == Flag ForHackage) $ do
908909
pkg <- fmap LBI.localPkgDescr (getPersistBuildConfig distPref)
909910
let dest = distPref </> name <.> "tar.gz"
910911
name = display (packageId pkg) ++ "-docs"
@@ -1111,7 +1112,7 @@ uploadAction uploadFlags extraArgs globalFlags = do
11111112
++ "If you need to customise Haddock options, "
11121113
++ "run 'haddock --for-hackage' first "
11131114
++ "to generate a documentation tarball."
1114-
haddockAction (defaultHaddockFlags { haddockForHackage = Flag True })
1115+
haddockAction (defaultHaddockFlags { haddockForHackage = Flag ForHackage })
11151116
[] globalFlags
11161117
distPref <- findSavedDistPref config NoFlag
11171118
pkg <- fmap LBI.localPkgDescr (getPersistBuildConfig distPref)

0 commit comments

Comments
 (0)