Skip to content

Commit 4466310

Browse files
alexbiehlalexbiehl
committed
Haddock: Generate haddock for components
Currently settings `documentation: true` enables documentation generation via haddock for your whole package, including tests and benchmarks. However, there are additional flags to control generation of documentation for this "second class" documentation targets, which are currently not honored at the cabal-install side of things. Namely, `tests`, `benchmarks`, `executables`, etc. provided under the `haddock` section in your `$CABAL_HOME/config`. This patch adds a more sensible approach to documentation generation via haddock. Also enabling `new-haddock` to generate documentation for single components instead whole packages. The behaviour works like this: - Setting `documentation: true` or passing `--enable-documentation` to cabal-install enable documentation for any component in the build plan honoring the respective flags for tests, benchmarks, exes, foreignlibs, etc. - Invoking new-haddock with a target selector will make sure the respective flags for "second class" doc targets are set correctly. E.g. $ new-haddock tests Will generate documentation for the testsuite of your package event if you have `tests: false` in your haddock section.
1 parent 85f31c8 commit 4466310

File tree

9 files changed

+107
-21
lines changed

9 files changed

+107
-21
lines changed

‎Cabal/Distribution/Simple.hs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -329,7 +329,7 @@ haddockAction hooks flags args = do
329329

330330
hookedAction preHaddock haddockHook postHaddock
331331
(return lbi { withPrograms = progs })
332-
hooks flags' args
332+
hooks flags' { haddockArgs = args } args
333333

334334
cleanAction :: UserHooks -> CleanFlags -> Args -> IO ()
335335
cleanAction hooks flags args = do

‎Cabal/Distribution/Simple/Haddock.hs

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ import Distribution.Types.ForeignLib
3636
import Distribution.Types.UnqualComponentName
3737
import Distribution.Types.ComponentLocalBuildInfo
3838
import Distribution.Types.ExecutableScope
39+
import Distribution.Types.LocalBuildInfo
40+
import Distribution.Types.TargetInfo
3941
import Distribution.Package
4042
import qualified Distribution.ModuleName as ModuleName
4143
import Distribution.PackageDescription as PD hiding (Flag)
@@ -46,6 +48,7 @@ import Distribution.Simple.Program
4648
import Distribution.Simple.PreProcess
4749
import Distribution.Simple.Setup
4850
import Distribution.Simple.Build
51+
import Distribution.Simple.BuildTarget
4952
import Distribution.Simple.InstallDirs
5053
import Distribution.Simple.LocalBuildInfo hiding (substPathTemplate)
5154
import Distribution.Simple.BuildPaths
@@ -199,7 +202,18 @@ haddock pkg_descr lbi suffixes flags' = do
199202
, fromFlags (haddockTemplateEnv lbi (packageId pkg_descr)) flags
200203
, fromPackageDescription haddockTarget pkg_descr ]
201204

202-
withAllComponentsInBuildOrder pkg_descr lbi $ \component clbi -> do
205+
targets <- readTargetInfos verbosity pkg_descr lbi (haddockArgs flags)
206+
207+
let
208+
targets' =
209+
case targets of
210+
[] -> allTargetsInBuildOrder' pkg_descr lbi
211+
_ -> targets
212+
213+
for_ targets' $ \target -> do
214+
let component = targetComponent target
215+
clbi = targetCLBI target
216+
203217
componentInitialBuildSteps (flag haddockDistPref) pkg_descr lbi clbi verbosity
204218
preprocessComponent pkg_descr component lbi clbi False verbosity suffixes
205219
let

‎Cabal/Distribution/Simple/Setup.hs

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1470,7 +1470,8 @@ data HaddockFlags = HaddockFlags {
14701470
haddockDistPref :: Flag FilePath,
14711471
haddockKeepTempFiles:: Flag Bool,
14721472
haddockVerbosity :: Flag Verbosity,
1473-
haddockCabalFilePath :: Flag FilePath
1473+
haddockCabalFilePath :: Flag FilePath,
1474+
haddockArgs :: [String]
14741475
}
14751476
deriving (Show, Generic)
14761477

@@ -1494,7 +1495,8 @@ defaultHaddockFlags = HaddockFlags {
14941495
haddockDistPref = NoFlag,
14951496
haddockKeepTempFiles= Flag False,
14961497
haddockVerbosity = Flag normal,
1497-
haddockCabalFilePath = mempty
1498+
haddockCabalFilePath = mempty,
1499+
haddockArgs = mempty
14981500
}
14991501

15001502
haddockCommand :: CommandUI HaddockFlags
@@ -1504,8 +1506,10 @@ haddockCommand = CommandUI
15041506
, commandDescription = Just $ \_ ->
15051507
"Requires the program haddock, version 2.x.\n"
15061508
, commandNotes = Nothing
1507-
, commandUsage = \pname ->
1508-
"Usage: " ++ pname ++ " haddock [FLAGS]\n"
1509+
, commandUsage = usageAlternatives "haddock" $
1510+
[ "[FLAGS]"
1511+
, "COMPONENTS [FLAGS]"
1512+
]
15091513
, commandDefaultFlags = defaultHaddockFlags
15101514
, commandOptions = \showOrParseArgs ->
15111515
haddockOptions showOrParseArgs

‎Cabal/Distribution/Simple/UserHooks.hs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,7 @@ emptyUserHooks
207207
preDoctest = rn,
208208
doctestHook = ru,
209209
postDoctest = ru,
210-
preHaddock = rn,
210+
preHaddock = rn',
211211
haddockHook = ru,
212212
postHaddock = ru,
213213
preTest = rn',

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -413,7 +413,8 @@ instance Semigroup SavedConfig where
413413
haddockDistPref = combine haddockDistPref,
414414
haddockKeepTempFiles = combine haddockKeepTempFiles,
415415
haddockVerbosity = combine haddockVerbosity,
416-
haddockCabalFilePath = combine haddockCabalFilePath
416+
haddockCabalFilePath = combine haddockCabalFilePath,
417+
haddockArgs = lastNonEmpty haddockArgs
417418
}
418419
where
419420
combine = combine' savedHaddockFlags

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

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -366,11 +366,12 @@ packageFileMonitorKeyValues elab =
366366
--
367367
elab_config =
368368
elab {
369-
elabBuildTargets = [],
370-
elabTestTargets = [],
369+
elabBuildTargets = [],
370+
elabTestTargets = [],
371371
elabBenchTargets = [],
372-
elabReplTarget = Nothing,
373-
elabBuildHaddocks = False
372+
elabReplTarget = Nothing,
373+
elabHaddockTargets = [],
374+
elabBuildHaddocks = False
374375
}
375376

376377
-- The second part is the value used to guard the build step. So this is
@@ -1217,7 +1218,7 @@ buildInplaceUnpackedPackage verbosity
12171218
-- Haddock phase
12181219
whenHaddock $
12191220
annotateFailureNoLog HaddocksFailed $ do
1220-
setup haddockCommand haddockFlags []
1221+
setup haddockCommand haddockFlags haddockArgs
12211222
let haddockTarget = elabHaddockForHackage pkg
12221223
when (haddockTarget == Cabal.ForHackage) $ do
12231224
let dest = distDirectory </> name <.> "tar.gz"
@@ -1304,6 +1305,7 @@ buildInplaceUnpackedPackage verbosity
13041305
haddockCommand = Cabal.haddockCommand
13051306
haddockFlags _ = setupHsHaddockFlags pkg pkgshared
13061307
verbosity builddir
1308+
haddockArgs = setupHsHaddockArgs pkg
13071309

13081310
scriptOptions = setupHsScriptOptions rpkg pkgshared
13091311
srcdir builddir

‎cabal-install/Distribution/Client/ProjectConfig/Legacy.hs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -733,7 +733,8 @@ convertToLegacyPerPackageConfig PackageConfig {..} =
733733
haddockDistPref = mempty,
734734
haddockKeepTempFiles = mempty,
735735
haddockVerbosity = mempty,
736-
haddockCabalFilePath = mempty
736+
haddockCabalFilePath = mempty,
737+
haddockArgs = mempty
737738
}
738739

739740

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

Lines changed: 49 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ module Distribution.Client.ProjectPlanning (
5656
setupHsCopyFlags,
5757
setupHsRegisterFlags,
5858
setupHsHaddockFlags,
59+
setupHsHaddockArgs,
5960

6061
packageHashInputs,
6162

@@ -1727,6 +1728,8 @@ elaborateInstallPlan verbosity platform compiler compilerprogdb pkgConfigDB
17271728
elabTestTargets = []
17281729
elabBenchTargets = []
17291730
elabReplTarget = Nothing
1731+
elabHaddockTargets = []
1732+
17301733
elabBuildHaddocks =
17311734
perPkgOptionFlag pkgid False packageConfigDocumentation
17321735

@@ -2437,6 +2440,7 @@ pkgHasEphemeralBuildTargets elab =
24372440
isJust (elabReplTarget elab)
24382441
|| (not . null) (elabTestTargets elab)
24392442
|| (not . null) (elabBenchTargets elab)
2443+
|| (not . null) (elabHaddockTargets elab)
24402444
|| (not . null) [ () | ComponentTarget _ subtarget <- elabBuildTargets elab
24412445
, subtarget /= WholeComponent ]
24422446

@@ -2535,11 +2539,22 @@ setRootTargets targetAction perPkgTargetsMap =
25352539
(Just tgts, TargetActionBuild) -> elab { elabBuildTargets = tgts }
25362540
(Just tgts, TargetActionTest) -> elab { elabTestTargets = tgts }
25372541
(Just tgts, TargetActionBench) -> elab { elabBenchTargets = tgts }
2538-
(Just [tgt], TargetActionRepl) -> elab { elabReplTarget = Just tgt }
2539-
(Just _, TargetActionHaddock) -> elab { elabBuildHaddocks = True }
2542+
(Just [tgt], TargetActionRepl) -> elab { elabReplTarget = Just tgt
2543+
, elabBuildHaddocks = False }
2544+
(Just tgts, TargetActionHaddock) ->
2545+
foldr setElabHaddockTargets (elab { elabHaddockTargets = tgts
2546+
, elabBuildHaddocks = True }) tgts
25402547
(Just _, TargetActionRepl) ->
25412548
error "pruneInstallPlanToTargets: multiple repl targets"
25422549

2550+
setElabHaddockTargets tgt elab
2551+
| isTestComponentTarget tgt = elab { elabHaddockTestSuites = True }
2552+
| isBenchComponentTarget tgt = elab { elabHaddockBenchmarks = True }
2553+
| isForeignLibComponentTarget tgt = elab { elabHaddockForeignLibs = True }
2554+
| isExeComponentTarget tgt = elab { elabHaddockExecutables = True }
2555+
| isSubLibComponentTarget tgt = elab { elabHaddockInternal = True }
2556+
| otherwise = elab
2557+
25432558
-- | Assuming we have previously set the root build targets (i.e. the user
25442559
-- targets but not rev deps yet), the first pruning pass does two things:
25452560
--
@@ -2560,14 +2575,16 @@ pruneInstallPlanPass1 pkgs =
25602575
roots = mapMaybe find_root pkgs'
25612576

25622577
prune elab = PrunedPackage elab' (pruneOptionalDependencies elab')
2563-
where elab' = addOptionalStanzas elab
2578+
where elab' =
2579+
setDocumentation
2580+
$ addOptionalStanzas elab
25642581

25652582
find_root (InstallPlan.Configured (PrunedPackage elab _)) =
25662583
if not (null (elabBuildTargets elab)
25672584
&& null (elabTestTargets elab)
25682585
&& null (elabBenchTargets elab)
25692586
&& isNothing (elabReplTarget elab)
2570-
&& not (elabBuildHaddocks elab))
2587+
&& null (elabHaddockTargets elab))
25712588
then Just (installedUnitId elab)
25722589
else Nothing
25732590
find_root _ = Nothing
@@ -2613,6 +2630,26 @@ pruneInstallPlanPass1 pkgs =
26132630
<> optionalStanzasWithDepsAvailable availablePkgs elab pkg
26142631
addOptionalStanzas elab = elab
26152632

2633+
setDocumentation :: ElaboratedConfiguredPackage -> ElaboratedConfiguredPackage
2634+
setDocumentation elab@ElaboratedConfiguredPackage { elabPkgOrComp = ElabComponent comp } =
2635+
elab {
2636+
elabBuildHaddocks =
2637+
elabBuildHaddocks elab && documentationEnabled (compSolverName comp) elab
2638+
}
2639+
2640+
where
2641+
documentationEnabled c =
2642+
case c of
2643+
CD.ComponentLib -> const True
2644+
CD.ComponentSubLib _ -> elabHaddockInternal
2645+
CD.ComponentFLib _ -> elabHaddockForeignLibs
2646+
CD.ComponentExe _ -> elabHaddockExecutables
2647+
CD.ComponentTest _ -> elabHaddockTestSuites
2648+
CD.ComponentBench _ -> elabHaddockBenchmarks
2649+
CD.ComponentSetup -> const False
2650+
2651+
setDocumentation elab = elab
2652+
26162653
-- Calculate package dependencies but cut out those needed only by
26172654
-- optional stanzas that we've determined we will not enable.
26182655
-- These pruned deps are not persisted in this pass since they're based on
@@ -3159,7 +3196,7 @@ setupHsConfigureFlags (ReadyPackage elab@ElaboratedConfiguredPackage{..})
31593196
configVanillaLib = toFlag elabVanillaLib
31603197
configSharedLib = toFlag elabSharedLib
31613198
configStaticLib = toFlag elabStaticLib
3162-
3199+
31633200
configDynExe = toFlag elabDynExe
31643201
configGHCiLib = toFlag elabGHCiLib
31653202
configProfExe = mempty
@@ -3391,9 +3428,15 @@ setupHsHaddockFlags (ElaboratedConfiguredPackage{..}) _ verbosity builddir =
33913428
haddockDistPref = toFlag builddir,
33923429
haddockKeepTempFiles = mempty, --TODO: from build settings
33933430
haddockVerbosity = toFlag verbosity,
3394-
haddockCabalFilePath = mempty
3431+
haddockCabalFilePath = mempty,
3432+
haddockArgs = mempty
33953433
}
33963434

3435+
setupHsHaddockArgs :: ElaboratedConfiguredPackage -> [String]
3436+
-- TODO: Does the issue #3335 affects test as well
3437+
setupHsHaddockArgs elab =
3438+
map (showComponentTarget (packageId elab)) (elabHaddockTargets elab)
3439+
33973440
{-
33983441
setupHsTestFlags :: ElaboratedConfiguredPackage
33993442
-> ElaboratedSharedConfig
@@ -3582,4 +3625,3 @@ inplaceBinRoot
35823625
inplaceBinRoot layout config package
35833626
= distBuildDirectory layout (elabDistDirParams config package)
35843627
</> "build"
3585-

‎cabal-install/Distribution/Client/ProjectPlanning/Types.hs

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,11 @@ module Distribution.Client.ProjectPlanning.Types (
4545
showBenchComponentTarget,
4646
SubComponentTarget(..),
4747

48+
isSubLibComponentTarget,
49+
isForeignLibComponentTarget,
50+
isExeComponentTarget,
4851
isTestComponentTarget,
52+
isBenchComponentTarget,
4953

5054
-- * Setup script
5155
SetupScriptStyle(..),
@@ -289,6 +293,8 @@ data ElaboratedConfiguredPackage
289293
elabTestTargets :: [ComponentTarget],
290294
elabBenchTargets :: [ComponentTarget],
291295
elabReplTarget :: Maybe ComponentTarget,
296+
elabHaddockTargets :: [ComponentTarget],
297+
292298
elabBuildHaddocks :: Bool,
293299

294300
--pkgSourceDir ? -- currently passed in later because they can use temp locations
@@ -667,6 +673,22 @@ showBenchComponentTarget :: PackageId -> ComponentTarget -> Maybe String
667673
showBenchComponentTarget _ (ComponentTarget (CBenchName n) _) = Just $ display n
668674
showBenchComponentTarget _ _ = Nothing
669675

676+
isBenchComponentTarget :: ComponentTarget -> Bool
677+
isBenchComponentTarget (ComponentTarget (CBenchName _) _) = True
678+
isBenchComponentTarget _ = False
679+
680+
isForeignLibComponentTarget :: ComponentTarget -> Bool
681+
isForeignLibComponentTarget (ComponentTarget (CFLibName _) _) = True
682+
isForeignLibComponentTarget _ = False
683+
684+
isExeComponentTarget :: ComponentTarget -> Bool
685+
isExeComponentTarget (ComponentTarget (CExeName _) _ ) = True
686+
isExeComponentTarget _ = False
687+
688+
isSubLibComponentTarget :: ComponentTarget -> Bool
689+
isSubLibComponentTarget (ComponentTarget (CSubLibName _) _) = True
690+
isSubLibComponentTarget _ = False
691+
670692
---------------------------
671693
-- Setup.hs script policy
672694
--

0 commit comments

Comments
 (0)