Skip to content

Commit 80f0a65

Browse files
FinleyMcIlwaineMikolaj
authored andcommitted
Do not use tmp dirs for Haddock, add --haddock-version-cpp, and more
Haddock no longer writes compilation files by default, so we do not need to pass tmp dirs for `-hidir`, `-stubdir`, and `-odir` via `--optghc`. Indeed, we do not *want* to do so, since it results in recompilation for every invocation of Haddock via Cabal. This commit stops this from happening for haddock versions >= 2.28 (when Hi Haddock was introduced). This commit also stops the default definition of the `__HADDOCK_VERSION__` macro when invoking GHC through haddock. Since a very limited set of users may still depend on this macro, we introduce the `--haddock-version-cpp` flag and `haddock-version-cpp:` cabal.project field, which enable the definition of the `__HADDOCK_VERSION__` macro when invoking GHC through Haddock. This will almost guarantee recompilation during documentation generation due to the macro definition. This commit also renames the `--haddock-lib` flag to `--haddock-resources-dir` (and `haddock-lib:` cabal.project field to `haddock-resources-dir:`), and adds this flag to the users guide since it was missing an entry. This also allows us to add this field to `cabal-install:test:integration-tests2`, since it is no longer ambiguous with the `--lib` flag. This commit also causes `documentation: true` or `--enable-documentation` to imply `-haddock` for GHC. Also, since Haddock >= 2.29 is renaming `--lib` to `--resources-dir`, this commit switches the flag provided to Haddock using a backwards compatible condition based on the Haddock version. Adds a changelog entry.
1 parent f323d29 commit 80f0a65

File tree

20 files changed

+235
-94
lines changed

20 files changed

+235
-94
lines changed

.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,9 @@ bench.html
9898
# Emacs
9999
.projectile
100100

101+
# direnv
102+
.envrc
103+
101104
## Release Scripts
102105

103106
# ignore the downloaded binary files

Cabal/src/Distribution/Simple/Haddock.hs

Lines changed: 90 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,7 @@ data HaddockArgs = HaddockArgs
153153
-- ^ Re-exported modules
154154
, argTargets :: [FilePath]
155155
-- ^ Modules to process.
156-
, argLib :: Flag String
156+
, argResourcesDir :: Flag String
157157
-- ^ haddock's static \/ auxiliary files.
158158
}
159159
deriving (Generic)
@@ -329,6 +329,15 @@ haddock_setupHooks
329329
[] -> allTargetsInBuildOrder' pkg_descr lbi
330330
_ -> targets
331331

332+
version' =
333+
if flag haddockVersionCPP
334+
then Just version
335+
else Nothing
336+
337+
mtmp
338+
| version >= mkVersion [2, 28, 0] = const Nothing
339+
| otherwise = Just
340+
332341
internalPackageDB <-
333342
createInternalPackageDB verbosity lbi (flag $ setupDistPref . haddockCommonFlags)
334343

@@ -367,11 +376,11 @@ haddock_setupHooks
367376
exeArgs <-
368377
fromExecutable
369378
verbosity
370-
tmp
379+
(mtmp tmp)
371380
lbi'
372381
clbi
373382
htmlTemplate
374-
version
383+
version'
375384
exe
376385
let exeArgs' = commonArgs `mappend` exeArgs
377386
runHaddock
@@ -401,17 +410,17 @@ haddock_setupHooks
401410
(maybeComponentInstantiatedWith clbi)
402411
ipi <- case component of
403412
CLib lib -> do
404-
withTempDirectoryCwdEx verbosity tmpFileOpts mbWorkDir (buildDir lbi) "tmp" $
413+
withTempDirectoryCwdEx verbosity tmpFileOpts mbWorkDir (buildDir lbi') "tmp" $
405414
\tmp -> do
406415
smsg
407416
libArgs <-
408417
fromLibrary
409418
verbosity
410-
tmp
419+
(mtmp tmp)
411420
lbi'
412421
clbi
413422
htmlTemplate
414-
version
423+
version'
415424
lib
416425
let libArgs' = commonArgs `mappend` libArgs
417426
runHaddock verbosity mbWorkDir tmpFileOpts comp platform haddockProg True libArgs'
@@ -448,20 +457,20 @@ haddock_setupHooks
448457
when
449458
(flag haddockForeignLibs)
450459
( do
451-
withTempDirectoryCwdEx verbosity tmpFileOpts mbWorkDir (buildDir lbi') "tmp" $
452-
\tmp -> do
453-
smsg
454-
flibArgs <-
460+
smsg
461+
flibArgs <-
462+
withTempDirectoryCwdEx verbosity tmpFileOpts mbWorkDir (buildDir lbi') "tmp" $
463+
\tmp -> do
455464
fromForeignLib
456465
verbosity
457-
tmp
466+
(mtmp tmp)
458467
lbi'
459468
clbi
460469
htmlTemplate
461-
version
470+
version'
462471
flib
463-
let libArgs' = commonArgs `mappend` flibArgs
464-
runHaddock verbosity mbWorkDir tmpFileOpts comp platform haddockProg True libArgs'
472+
let libArgs' = commonArgs `mappend` flibArgs
473+
runHaddock verbosity mbWorkDir tmpFileOpts comp platform haddockProg True libArgs'
465474
)
466475
>> return index
467476
CExe _ -> when (flag haddockExecutables) (smsg >> doExe component) >> return index
@@ -525,7 +534,7 @@ fromFlags env flags =
525534
(haddockIndex flags)
526535
, argGenIndex = Flag False
527536
, argBaseUrl = haddockBaseUrl flags
528-
, argLib = haddockLib flags
537+
, argResourcesDir = haddockResourcesDir flags
529538
, argVerbose =
530539
maybe mempty (Any . (>= deafening))
531540
. flagToMaybe
@@ -552,7 +561,7 @@ fromHaddockProjectFlags flags =
552561
, argPrologueFile = haddockProjectPrologue flags
553562
, argInterfaces = fromFlagOrDefault [] (haddockProjectInterfaces flags)
554563
, argLinkedSource = Flag True
555-
, argLib = haddockProjectLib flags
564+
, argResourcesDir = haddockProjectResourcesDir flags
556565
}
557566

558567
fromPackageDescription :: HaddockTarget -> PackageDescription -> HaddockArgs
@@ -597,26 +606,34 @@ componentGhcOptions verbosity lbi bi clbi odir =
597606

598607
mkHaddockArgs
599608
:: Verbosity
600-
-> SymbolicPath Pkg (Path.Dir Tmp)
609+
-> Maybe (SymbolicPath Pkg (Path.Dir Tmp))
610+
-- ^ 'Nothing' to prevent passing temporary directories for -hidir, -odir, and
611+
-- -stubdir to GHC through Haddock
601612
-> LocalBuildInfo
602613
-> ComponentLocalBuildInfo
603614
-> Maybe PathTemplate
604615
-- ^ template for HTML location
605-
-> Version
616+
-> Maybe Version
617+
-- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
618+
-- macro
606619
-> [SymbolicPath Pkg File]
607620
-> BuildInfo
608621
-> IO HaddockArgs
609-
mkHaddockArgs verbosity tmp lbi clbi htmlTemplate haddockVersion inFiles bi = do
622+
mkHaddockArgs verbosity mtmp lbi clbi htmlTemplate haddockVersion inFiles bi = do
610623
ifaceArgs <- getInterfaces verbosity lbi clbi htmlTemplate
611-
let vanillaOpts =
612-
(componentGhcOptions normal lbi bi clbi (buildDir lbi))
613-
{ -- Noooooooooo!!!!!111
614-
-- haddock stomps on our precious .hi
615-
-- and .o files. Workaround by telling
616-
-- haddock to write them elsewhere.
617-
ghcOptObjDir = toFlag $ coerceSymbolicPath tmp
618-
, ghcOptHiDir = toFlag $ coerceSymbolicPath tmp
619-
, ghcOptStubDir = toFlag $ coerceSymbolicPath tmp
624+
let vanillaOpts' =
625+
componentGhcOptions normal lbi bi clbi (buildDir lbi)
626+
`mappend` getGhcCppOpts haddockVersion bi
627+
vanillaOpts =
628+
vanillaOpts'
629+
{ -- Starting with Haddock 2.28, we no longer want to run Haddock's
630+
-- GHC session in a temporary directory. Doing so always causes
631+
-- recompilation during documentation generation, which can now be
632+
-- avoided thanks to Hi Haddock. See
633+
-- https://github.com/haskell/cabal/pull/9177 for discussion.
634+
ghcOptObjDir = maybe (ghcOptObjDir vanillaOpts') (toFlag . coerceSymbolicPath) mtmp
635+
, ghcOptHiDir = maybe (ghcOptHiDir vanillaOpts') (toFlag . coerceSymbolicPath) mtmp
636+
, ghcOptStubDir = maybe (ghcOptStubDir vanillaOpts') (toFlag . coerceSymbolicPath) mtmp
620637
}
621638
`mappend` getGhcCppOpts haddockVersion bi
622639
sharedOpts =
@@ -644,20 +661,24 @@ mkHaddockArgs verbosity tmp lbi clbi htmlTemplate haddockVersion inFiles bi = do
644661

645662
fromLibrary
646663
:: Verbosity
647-
-> SymbolicPath Pkg (Path.Dir Tmp)
664+
-> Maybe (SymbolicPath Pkg (Path.Dir Tmp))
665+
-- ^ 'Nothing' to prevent passing temporary directories for -hidir, -odir, and
666+
-- -stubdir to GHC through Haddock
648667
-> LocalBuildInfo
649668
-> ComponentLocalBuildInfo
650669
-> Maybe PathTemplate
651670
-- ^ template for HTML location
652-
-> Version
671+
-> Maybe Version
672+
-- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
673+
-- macro
653674
-> Library
654675
-> IO HaddockArgs
655-
fromLibrary verbosity tmp lbi clbi htmlTemplate haddockVersion lib = do
676+
fromLibrary verbosity mtmp lbi clbi htmlTemplate haddockVersion lib = do
656677
inFiles <- map snd `fmap` getLibSourceFiles verbosity lbi lib clbi
657678
args <-
658679
mkHaddockArgs
659680
verbosity
660-
tmp
681+
mtmp
661682
lbi
662683
clbi
663684
htmlTemplate
@@ -671,20 +692,24 @@ fromLibrary verbosity tmp lbi clbi htmlTemplate haddockVersion lib = do
671692

672693
fromExecutable
673694
:: Verbosity
674-
-> SymbolicPath Pkg (Path.Dir Tmp)
695+
-> Maybe (SymbolicPath Pkg (Path.Dir Tmp))
696+
-- ^ 'Nothing' to prevent passing temporary directories for -hidir, -odir, and
697+
-- -stubdir to GHC through Haddock
675698
-> LocalBuildInfo
676699
-> ComponentLocalBuildInfo
677700
-> Maybe PathTemplate
678701
-- ^ template for HTML location
679-
-> Version
702+
-> Maybe Version
703+
-- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
704+
-- macro
680705
-> Executable
681706
-> IO HaddockArgs
682-
fromExecutable verbosity tmp lbi clbi htmlTemplate haddockVersion exe = do
707+
fromExecutable verbosity mtmp lbi clbi htmlTemplate haddockVersion exe = do
683708
inFiles <- map snd `fmap` getExeSourceFiles verbosity lbi exe clbi
684709
args <-
685710
mkHaddockArgs
686711
verbosity
687-
tmp
712+
mtmp
688713
lbi
689714
clbi
690715
htmlTemplate
@@ -699,20 +724,24 @@ fromExecutable verbosity tmp lbi clbi htmlTemplate haddockVersion exe = do
699724

700725
fromForeignLib
701726
:: Verbosity
702-
-> SymbolicPath Pkg (Path.Dir Tmp)
727+
-> Maybe (SymbolicPath Pkg (Path.Dir Tmp))
728+
-- ^ 'Nothing' to prevent passing temporary directories for -hidir, -odir, and
729+
-- -stubdir to GHC through Haddock
703730
-> LocalBuildInfo
704731
-> ComponentLocalBuildInfo
705732
-> Maybe PathTemplate
706733
-- ^ template for HTML location
707-
-> Version
734+
-> Maybe Version
735+
-- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
736+
-- macro
708737
-> ForeignLib
709738
-> IO HaddockArgs
710-
fromForeignLib verbosity tmp lbi clbi htmlTemplate haddockVersion flib = do
739+
fromForeignLib verbosity mtmp lbi clbi htmlTemplate haddockVersion flib = do
711740
inFiles <- map snd `fmap` getFLibSourceFiles verbosity lbi flib clbi
712741
args <-
713742
mkHaddockArgs
714743
verbosity
715-
tmp
744+
mtmp
716745
lbi
717746
clbi
718747
htmlTemplate
@@ -768,7 +797,9 @@ getReexports LibComponentLocalBuildInfo{componentExposedModules = mods} =
768797
getReexports _ = []
769798

770799
getGhcCppOpts
771-
:: Version
800+
:: Maybe Version
801+
-- ^ 'Nothing' if the user requested not to define the __HADDOCK_VERSION__
802+
-- macro
772803
-> BuildInfo
773804
-> GhcOptions
774805
getGhcCppOpts haddockVersion bi =
@@ -778,16 +809,21 @@ getGhcCppOpts haddockVersion bi =
778809
}
779810
where
780811
needsCpp = EnableExtension CPP `elem` usedExtensions bi
781-
defines = [haddockVersionMacro]
782-
haddockVersionMacro =
783-
"-D__HADDOCK_VERSION__="
784-
++ show (v1 * 1000 + v2 * 10 + v3)
812+
defines =
813+
[ "-D__HADDOCK_VERSION__=" ++ show vn
814+
| Just vn <- [versionInt . versionNumbers <$> haddockVersion]
815+
]
785816
where
786-
(v1, v2, v3) = case versionNumbers haddockVersion of
787-
[] -> (0, 0, 0)
788-
[x] -> (x, 0, 0)
789-
[x, y] -> (x, y, 0)
790-
(x : y : z : _) -> (x, y, z)
817+
-- For some list xs = [x, y, z ...], versionInt xs results in
818+
-- x * 1000 + y * 10 + z. E.g.:
819+
-- >>> versionInt [2, 29, 0]
820+
-- 2290
821+
-- >>> versionInt [3, 4]
822+
-- 3040
823+
-- >>> versionInt []
824+
-- 0
825+
versionInt :: [Int] -> Int
826+
versionInt = foldr ((+) . uncurry (*)) 0 . zip [1000, 10, 1]
791827

792828
getGhcLibDir
793829
:: Verbosity
@@ -993,7 +1029,7 @@ renderPureArgs version comp platform args =
9931029
, isVersion 2 19
9941030
]
9951031
, argTargets $ args
996-
, maybe [] ((: []) . ("--lib=" ++)) . flagToMaybe . argLib $ args
1032+
, maybe [] ((: []) . (resourcesDirFlag ++)) . flagToMaybe . argResourcesDir $ args
9971033
]
9981034
where
9991035
-- See Note [Symbolic paths] in Distribution.Utils.Path
@@ -1037,6 +1073,9 @@ renderPureArgs version comp platform args =
10371073
verbosityFlag
10381074
| isVersion 2 5 = "--verbosity=1"
10391075
| otherwise = "--verbose"
1076+
resourcesDirFlag
1077+
| isVersion 2 29 = "--resources-dir="
1078+
| otherwise = "--lib="
10401079
haddockSupportsVisibility = version >= mkVersion [2, 26, 1]
10411080
haddockSupportsPackageName = version > mkVersion [2, 16]
10421081
haddockSupportsHyperlinkedSource = isVersion 2 17

0 commit comments

Comments
 (0)