diff --git a/ChangeLog.md b/ChangeLog.md index 737dd19720..739a0421d2 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -31,6 +31,9 @@ Other enhancements: * Add option of the form `--doctest-option=` to `stack build`, where `doctest` is a program recognised by versions of the Cabal library from `1.24.0.0`. +* Experimental: Add flag `--haddock-for-hackage` to Stack's `build` command + (including the `haddock` synonym for `build --haddock`) to enable building + with flags to generate Haddock documentation suitable for upload to Hackage. Bug fixes: @@ -231,8 +234,8 @@ Other enhancements: `STACK_ROOT` environment variable. * Add `stack path --global-config`, to yield the full path of Stack's user-specific global YAML configuration file (`config.yaml`). -* Add an experimental option, `allow-newer-deps`, which allows users to - specify a subset of dependencies for which version bounds should be ignored +* Experimental: Add option `allow-newer-deps`, which allows users to specify a + subset of dependencies for which version bounds should be ignored (`allow-newer-deps: ['foo', 'bar']`). This field has no effect unless `allow-newer` is enabled. @@ -784,7 +787,7 @@ Major changes: * Remove the `stack image` command. With the advent of Docker multistage builds, this functionality is no longer useful. For an example, please see [Building Haskell Apps with Docker](https://www.fpcomplete.com/blog/2017/12/building-haskell-apps-with-docker). -* Support building GHC from source (experimental) +* Experimental: Support building GHC from source * Stack now supports building and installing GHC from source. The built GHC is uniquely identified by a commit id and an Hadrian "flavour" (Hadrian is the newer GHC build system), hence `compiler` can be set to use a GHC @@ -1667,11 +1670,10 @@ Other enhancements: [#3126](https://github.com/commercialhaskell/stack/issues/3126) * When using Nix, nix-shell now depends always on git to prevent runtime errors while fetching metadata -* The `stack unpack` command now accepts a form where an explicit - Hackage revision hash is specified, e.g. `stack unpack - foo-1.2.3@gitsha1:deadbeef`. Note that this should be considered - _experimental_, Stack will likely move towards a different hash - format in the future. +* Experimental: The `stack unpack` command now accepts a form where an explicit + Hackage revision hash is specified, e.g. + `stack unpack foo-1.2.3@gitsha1:deadbeef`. Note that Stack will likely move + towards a different hash format in the future. * Binary "stack upgrade" will now warn if the installed executable is not on the PATH or shadowed by another entry. * Allow running tests on tarball created by sdist and upload @@ -2286,7 +2288,7 @@ Other enhancements: * Fix too much rebuilding when enabling/disabling profiling flags. * `stack build pkg-1.0` will now build `pkg-1.0` even if the snapshot specifies a different version (it introduces a temporary extra-dep) -* Experimental support for `--split-objs` added +* Experimental: Support for `--split-objs` added [#1284](https://github.com/commercialhaskell/stack/issues/1284). * `git` packages with submodules are supported by passing the `--recursive` flag to `git clone`. @@ -2765,7 +2767,7 @@ Other enhancements: [#1070](https://github.com/commercialhaskell/stack/pull/1070) * Use Stack-installed GHCs for `stack init --solver` [#1072](https://github.com/commercialhaskell/stack/issues/1072) -* New experimental `stack query` command +* Experimental: Add `stack query` command [#1087](https://github.com/commercialhaskell/stack/issues/1087) * By default, Stack no longer rebuilds a package due to GHC options changes. This behavior can be tweaked with the `rebuild-ghc-options` setting. diff --git a/doc/build_command.md b/doc/build_command.md index 49c6a3b79d..4f798ae81e 100644 --- a/doc/build_command.md +++ b/doc/build_command.md @@ -12,11 +12,11 @@ stack build [TARGET] [--dry-run] [--pedantic] [--fast] [--ghc-options OPTIONS] [--[no-]library-stripping] [--[no-]executable-stripping] [--[no-]haddock] [--haddock-arguments HADDOCK_ARGS] [--[no-]open] [--[no-]haddock-deps] [--[no-]haddock-internal] - [--[no-]haddock-hyperlink-source] [--[no-]copy-bins] - [--[no-]copy-compiler-tool] [--[no-]prefetch] [--[no-]keep-going] - [--[no-]keep-tmp-files] [--[no-]force-dirty] [--[no-]test] - [--[no-]rerun-tests] [--ta|--test-arguments TEST_ARGS] [--coverage] - [--no-run-tests] [--test-suite-timeout ARG] + [--[no-]haddock-hyperlink-source] [--[no-]haddock-for-hackage] + [--[no-]copy-bins] [--[no-]copy-compiler-tool] [--[no-]prefetch] + [--[no-]keep-going] [--[no-]keep-tmp-files] [--[no-]force-dirty] + [--[no-]test] [--[no-]rerun-tests] [--ta|--test-arguments TEST_ARGS] + [--coverage] [--no-run-tests] [--test-suite-timeout ARG] [--[no-]tests-allow-stdin] [--[no-]bench] [--ba|--benchmark-arguments BENCH_ARGS] [--no-run-benchmarks] [--[no-]reconfigure] [--cabal-verbosity VERBOSITY | @@ -234,18 +234,58 @@ Default: Enabled (if building Haddock documnentation) Unset the flag to disable building Haddock documentation for dependencies. +### `--[no-]haddock-for-haddock` flag + +:octicons-beaker-24: Experimental + +:octicons-tag-24: UNRELEASED + +Default: Disabled + +Set the flag to build with flags to generate Haddock documentation suitable for +upload to Hackage. + +For each local package, the generated Haddock documentation files are in +directory `doc\html\-docs\`, relative to Stack's dist work +directory (see `stack path --dist-dir`). + +If the flag is set: + +* the [`--[no-]haddock-hyperlink-source`](#no-haddock-hyperlink-source-flag) + flag is ignored and `--haddock-hyperlink-source` is implied; and +* the [`--[no-]haddock-internal`](#no-haddock-hyperlink-internal-flag) flag is + ignored and `--no-haddock-internal` is implied. + +!!! note + + If set, Haddock will warn that `-source-*` options are ignored when + `--hyperlinked-source` is enabled. That is due to a known bug in Cabal + (the libiary). + +!!! note + + If set, Cabal (the library) will report that documentation has been created + in `index.html` and `.txt` files. Those files do not exist. + That false report is due to a known bug in Cabal (the library). + ### `--[no-]haddock-hyperlink-source` flag Default: Enabled Unset the flag to disable building building hyperlinked source for Haddock. +If the [`--haddock-for-hackage`](#no-haddock-for-haddock-flag) flag is passed, +this flag is ignored. + ### `--[no-]haddock-internal` flag Default: Disabled Set the flag to enable building Haddock documentation for internal modules. +If the [`--haddock-for-hackage`](#no-haddock-for-haddock-flag) flag is passed, +this flag is ignored. + ### `--[no-]keep-going` flag Default (`stack build`): Disabled diff --git a/doc/path_command.md b/doc/path_command.md index 3f96f84e50..b70b675a38 100644 --- a/doc/path_command.md +++ b/doc/path_command.md @@ -23,7 +23,7 @@ Pass the following flags for information about specific files or locations: |--compiler-exe |The GHC executable. | |--compiler-tools-bin |The directory containing binaries specific to a particular compiler.| |--config-location |Stack's project-level YAML configuration file (`stack.yaml`).| -|--dist-dir |The dist working directory, relative to the package directory.| +|--dist-dir |The dist work directory, relative to the package directory.| |--extra-include-dirs |Extra include directories. | |--extra-library-dirs |Extra library directories. | |--ghc-package-path |The `GHC_PACKAGE_PATH` environment variable. | diff --git a/doc/yaml_configuration.md b/doc/yaml_configuration.md index fa832f4ac1..12dc3f1a17 100644 --- a/doc/yaml_configuration.md +++ b/doc/yaml_configuration.md @@ -439,7 +439,10 @@ build: # - "--css=/home/user/my-css" open-haddocks: false # --open haddock-deps: false # if unspecified, defaults to true if haddock is set - haddock-internal: false + haddock-for-hackage: false # if specified, implies haddock-internal: false and + # haddock-hyperlink-source: true + haddock-internal: false # ignored, if haddock-for-hackage: true + haddock-hyperlink-source: true # ignored, if haddock-for-hackage: true # These are inadvisable to use in your global configuration, as they make the # Stack build command line behave quite differently. diff --git a/src/Stack/Build/Execute.hs b/src/Stack/Build/Execute.hs index 5223492924..ac79b89e66 100644 --- a/src/Stack/Build/Execute.hs +++ b/src/Stack/Build/Execute.hs @@ -1673,6 +1673,7 @@ singleBuild ac@ActionContext {..} ee@ExecuteEnv {..} task@Task {..} installedMap && maybe True (Set.notMember pname . curatorSkipHaddock) mcurator expectHaddockFailure = maybe False (Set.member pname . curatorExpectHaddockFailure) + isHaddockForHackage = boptsHaddockForHackage eeBuildOpts fulfillHaddockExpectations mcurator action | expectHaddockFailure mcurator = do eres <- tryAny $ action KeepOpen @@ -1956,11 +1957,9 @@ singleBuild ac@ActionContext {..} ee@ExecuteEnv {..} task@Task {..} installedMap mcurator <- view $ buildConfigL.to bcCurator when (doHaddock mcurator package) $ do - announce "haddock" - let sourceFlag = - [ "--haddock-option=--hyperlinked-source" - | boptsHaddockHyperlinkSource eeBuildOpts - ] + announce $ if isHaddockForHackage + then "haddock for Hackage" + else "haddock" -- For GHC 8.4 and later, provide the --quickjump option. actualCompiler <- view actualCompilerVersionL @@ -1970,19 +1969,29 @@ singleBuild ac@ActionContext {..} ee@ExecuteEnv {..} task@Task {..} installedMap | ghcVer >= mkVersion [8, 4] -> ["--haddock-option=--quickjump"] _ -> [] - fulfillHaddockExpectations mcurator $ \keep -> - cabal0 keep KeepTHLoading $ concat - [ [ "haddock" - , "--html" - , "--hoogle" - , "--html-location=../$pkg-$version/" - ] - , sourceFlag - , ["--internal" | boptsHaddockInternal eeBuildOpts] - , [ "--haddock-option=" <> opt - | opt <- hoAdditionalArgs (boptsHaddockOpts eeBuildOpts) ] - , quickjump - ] + fulfillHaddockExpectations mcurator $ \keep -> do + let args = concat + ( if isHaddockForHackage + then + [ [ "--for-hackage" ] ] + else + [ [ "--html" + , "--hoogle" + , "--html-location=../$pkg-$version/" + ] + , [ "--haddock-option=--hyperlinked-source" + | boptsHaddockHyperlinkSource eeBuildOpts + ] + , [ "--internal" | boptsHaddockInternal eeBuildOpts ] + , quickjump + ] + <> [ [ "--haddock-option=" <> opt + | opt <- hoAdditionalArgs (boptsHaddockOpts eeBuildOpts) + ] + ] + ) + + cabal0 keep KeepTHLoading $ "haddock" : args let hasLibrary = case packageLibraries package of diff --git a/src/Stack/Config/Build.hs b/src/Stack/Config/Build.hs index 464d7bbc3e..7876c4ec14 100644 --- a/src/Stack/Config/Build.hs +++ b/src/Stack/Config/Build.hs @@ -41,6 +41,7 @@ buildOptsFromMonoid BuildOptsMonoid{..} = BuildOpts , boptsHaddockInternal = fromFirstFalse buildMonoidHaddockInternal , boptsHaddockHyperlinkSource = fromFirstTrue buildMonoidHaddockHyperlinkSource + , boptsHaddockForHackage = fromFirstFalse buildMonoidHaddockForHackage , boptsInstallExes = fromFirstFalse buildMonoidInstallExes , boptsInstallCompilerTool = fromFirstFalse buildMonoidInstallCompilerTool , boptsPreFetch = fromFirstFalse buildMonoidPreFetch diff --git a/src/Stack/Options/BuildMonoidParser.hs b/src/Stack/Options/BuildMonoidParser.hs index 569d6452a0..ca1ca4f43f 100644 --- a/src/Stack/Options/BuildMonoidParser.hs +++ b/src/Stack/Options/BuildMonoidParser.hs @@ -43,6 +43,7 @@ buildOptsMonoidParser hide0 = BuildOptsMonoid <*> haddockDeps <*> haddockInternal <*> haddockHyperlinkSource + <*> haddockForHackage <*> copyBins <*> copyCompilerTool <*> preFetch @@ -142,6 +143,11 @@ buildOptsMonoidParser hide0 = BuildOptsMonoid "building hyperlinked source for Haddock documentation (like \ \'haddock --hyperlinked-source')." hide + haddockForHackage = firstBoolFlagsFalse + "haddock-for-hackage" + "building with flags to generate Haddock documentation suitable for upload \ + \to Hackage." + hide copyBins = firstBoolFlagsFalse "copy-bins" "copying binaries to local-bin (see 'stack path')." diff --git a/src/Stack/Types/BuildOpts.hs b/src/Stack/Types/BuildOpts.hs index ffee7d57b5..765e44744a 100644 --- a/src/Stack/Types/BuildOpts.hs +++ b/src/Stack/Types/BuildOpts.hs @@ -67,8 +67,10 @@ data BuildOpts = BuildOpts -- ^ Build haddocks for all symbols and packages, like -- @cabal haddock --internal@ , boptsHaddockHyperlinkSource :: !Bool - -- ^ Build hyperlinked source if possible. Fallback to @hscolour@. Disable - -- for no sources. + -- ^ Build hyperlinked source. Disable for no sources. + , boptsHaddockForHackage :: !Bool + -- ^ Build with flags to generate Haddock documentation suitable to upload + -- to Hackage. , boptsInstallExes :: !Bool -- ^ Install executables to user path after building? , boptsInstallCompilerTool :: !Bool @@ -122,6 +124,7 @@ defaultBuildOpts = BuildOpts , boptsHaddockInternal = defaultFirstFalse buildMonoidHaddockInternal , boptsHaddockHyperlinkSource = defaultFirstTrue buildMonoidHaddockHyperlinkSource + , boptsHaddockForHackage = defaultFirstFalse buildMonoidHaddockForHackage , boptsInstallExes = defaultFirstFalse buildMonoidInstallExes , boptsInstallCompilerTool = defaultFirstFalse buildMonoidInstallCompilerTool , boptsPreFetch = defaultFirstFalse buildMonoidPreFetch @@ -236,6 +239,7 @@ data BuildOptsMonoid = BuildOptsMonoid , buildMonoidHaddockDeps :: !(First Bool) , buildMonoidHaddockInternal :: !FirstFalse , buildMonoidHaddockHyperlinkSource :: !FirstTrue + , buildMonoidHaddockForHackage :: !FirstFalse , buildMonoidInstallExes :: !FirstFalse , buildMonoidInstallCompilerTool :: !FirstFalse , buildMonoidPreFetch :: !FirstFalse @@ -275,6 +279,8 @@ instance FromJSON (WithJSONWarnings BuildOptsMonoid) where FirstFalse <$> o ..:? buildMonoidHaddockInternalArgName buildMonoidHaddockHyperlinkSource <- FirstTrue <$> o ..:? buildMonoidHaddockHyperlinkSourceArgName + buildMonoidHaddockForHackage <- + FirstFalse <$> o ..:? buildMonoidHaddockForHackageArgName buildMonoidInstallExes <- FirstFalse <$> o ..:? buildMonoidInstallExesArgName buildMonoidInstallCompilerTool <- @@ -336,6 +342,9 @@ buildMonoidHaddockInternalArgName = "haddock-internal" buildMonoidHaddockHyperlinkSourceArgName :: Text buildMonoidHaddockHyperlinkSourceArgName = "haddock-hyperlink-source" +buildMonoidHaddockForHackageArgName :: Text +buildMonoidHaddockForHackageArgName = "haddock-for-hackage" + buildMonoidInstallExesArgName :: Text buildMonoidInstallExesArgName = "copy-bins"