From 1d58074dd12cc63bb095b4a4dc764127eb5d4788 Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Thu, 6 Aug 2026 15:26:01 -0400 Subject: [PATCH 1/7] For test-show-details, list options --- Cabal/src/Distribution/Simple/Setup/Test.hs | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/Cabal/src/Distribution/Simple/Setup/Test.hs b/Cabal/src/Distribution/Simple/Setup/Test.hs index 5a1563f2b70..718cde13305 100644 --- a/Cabal/src/Distribution/Simple/Setup/Test.hs +++ b/Cabal/src/Distribution/Simple/Setup/Test.hs @@ -194,11 +194,14 @@ testOptions' showOrParseArgs = , option [] ["show-details"] - ( "'always': always show results of individual test cases. " - ++ "'never': never show results of individual test cases. " - ++ "'failures': show results of failing test cases. " - ++ "'streaming': show results of test cases in real time." - ++ "'direct': send results of test cases in real time; no log file." + ( unlines + [ "Allowed values:" + , "- always: always show results of individual test cases," + , "- never: never show results of individual test cases," + , "- failures: show results of failing test cases," + , "- streaming: show results of test cases in real time," + , "- direct: send results of test cases in real time; no log file." + ] ) testShowDetails (\v flags -> flags{testShowDetails = v}) From 5a886629aa58420daeb56fd5d5a676be8025e0d6 Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Sat, 15 Aug 2026 14:20:45 -0400 Subject: [PATCH 2/7] Replace FILTER with values for test-show-details --- Cabal/src/Distribution/Simple/Setup/Test.hs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Cabal/src/Distribution/Simple/Setup/Test.hs b/Cabal/src/Distribution/Simple/Setup/Test.hs index 718cde13305..00b8121e98f 100644 --- a/Cabal/src/Distribution/Simple/Setup/Test.hs +++ b/Cabal/src/Distribution/Simple/Setup/Test.hs @@ -206,7 +206,7 @@ testOptions' showOrParseArgs = testShowDetails (\v flags -> flags{testShowDetails = v}) ( reqArg - "FILTER" + "always|never|failures|streaming|direct" ( parsecToReadE ( \_ -> "--show-details flag expects one of " From 466f6a2cb2fe8ddd3bd93dfb33b486d84b1f381d Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Sat, 15 Aug 2026 14:29:38 -0400 Subject: [PATCH 3/7] Sublist for remote-build-reporting options --- cabal-install/src/Distribution/Client/Setup.hs | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/cabal-install/src/Distribution/Client/Setup.hs b/cabal-install/src/Distribution/Client/Setup.hs index c1dd499eeac..7ce292a1b40 100644 --- a/cabal-install/src/Distribution/Client/Setup.hs +++ b/cabal-install/src/Distribution/Client/Setup.hs @@ -2739,7 +2739,13 @@ installOptions showOrParseArgs = , option [] ["remote-build-reporting"] - "Generate build reports to send to a remote server (none, anonymous or detailed)." + ( unlines + [ "Generate build reports to send to a remote server:" + , "- none: do not report," + , "- anonymous: report without identifying information," + , "- detailed: report with full details." + ] + ) installBuildReports (\v flags -> flags{installBuildReports = v}) ( reqArg From 8babe57718ce5f7d39f97250e8718d06bf15d75e Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Thu, 8 Oct 2026 12:44:38 -0400 Subject: [PATCH 4/7] Indent help description list items --- Cabal/src/Distribution/GetOpt.hs | 41 +++++++++++++------ .../src/Distribution/Client/Setup.hs | 4 +- 2 files changed, 31 insertions(+), 14 deletions(-) diff --git a/Cabal/src/Distribution/GetOpt.hs b/Cabal/src/Distribution/GetOpt.hs index 25c980a28ba..a6b5f71e5d7 100644 --- a/Cabal/src/Distribution/GetOpt.hs +++ b/Cabal/src/Distribution/GetOpt.hs @@ -38,6 +38,8 @@ module Distribution.GetOpt import Distribution.Compat.Prelude import Prelude () +import Data.List (stripPrefix) + -- | What to do with options following non-options data ArgOrder a = -- | no option processing after first non-option @@ -170,21 +172,36 @@ fmtLong (OptArg _ ad) lo = let opt = "--" ++ lo in opt ++ "[=" ++ ad ++ "]" +-- | Wrap text to the given width. Each line of the input is wrapped on its +-- own, so a description written with explicit line breaks, such as a list of +-- allowed values, keeps those breaks. A line that starts with a @- @ list +-- marker gets a hanging indent, so its continuation lines align with the text +-- after the marker. wrapText :: Int -> String -> [String] -wrapText width = map unwords . wrap 0 [] . words +wrapText width = concatMap wrapLine . lines where - wrap :: Int -> [String] -> [String] -> [[String]] - wrap 0 [] (w : ws) - | length w + 1 > width = - wrap (length w) [w] ws - wrap col line (w : ws) - | col + length w + 1 > width = - reverse line : wrap 0 [] (w : ws) - wrap col line (w : ws) = + wrapLine line = case stripPrefix listMarker line of + Just item -> + zipWith (++) (listMarker : repeat listIndent) (wrapWords (width - length listMarker) item) + Nothing -> wrapWords width line + + listMarker = "- " + listIndent = map (const ' ') listMarker + + wrapWords w = map unwords . wrap w 0 [] . words + + wrap :: Int -> Int -> [String] -> [String] -> [[String]] + wrap width' 0 [] (w : ws) + | length w + 1 > width' = + wrap width' (length w) [w] ws + wrap width' col line (w : ws) + | col + length w + 1 > width' = + reverse line : wrap width' 0 [] (w : ws) + wrap width' col line (w : ws) = let col' = col + length w + 1 - in wrap col' (w : line) ws - wrap _ [] [] = [] - wrap _ line [] = [reverse line] + in wrap width' col' (w : line) ws + wrap _ _ [] [] = [] + wrap _ _ line [] = [reverse line] -- | -- Process the command-line, and return the list of values that matched diff --git a/cabal-install/src/Distribution/Client/Setup.hs b/cabal-install/src/Distribution/Client/Setup.hs index 7ce292a1b40..a2eb4c9121d 100644 --- a/cabal-install/src/Distribution/Client/Setup.hs +++ b/cabal-install/src/Distribution/Client/Setup.hs @@ -3030,8 +3030,8 @@ initOptions _ = [ option ['i'] ["interactive"] - ( "Interactive mode. Creates a prompt tree for project creation. \n" - ++ "If -n/--non-interactive is issued, a simple project with inferred defaults \n" + ( "Interactive mode. Creates a prompt tree for project creation. " + ++ "If -n/--non-interactive is issued, a simple project with inferred defaults " ++ "is created. If --simple is issued, then sensible defaults will be chosen as well." ) IT.interactive From ae4ecda41cd22bd4a389f55c820b72d0316ac2dc Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Thu, 8 Oct 2026 12:57:41 -0400 Subject: [PATCH 5/7] Show help description list items --- Cabal/src/Distribution/Simple/Setup/Config.hs | 20 ++++++++--- .../src/Distribution/Client/Setup.hs | 34 +++++++++++++------ 2 files changed, 39 insertions(+), 15 deletions(-) diff --git a/Cabal/src/Distribution/Simple/Setup/Config.hs b/Cabal/src/Distribution/Simple/Setup/Config.hs index aa8222e5ce9..5c76e56ff30 100644 --- a/Cabal/src/Distribution/Simple/Setup/Config.hs +++ b/Cabal/src/Distribution/Simple/Setup/Config.hs @@ -541,9 +541,7 @@ configureOptions showOrParseArgs = , option "" ["profiling-detail"] - ( "Profiling detail level for executable and library (default, " - ++ "none, exported-functions, toplevel-functions, all-functions, late)." - ) + ("Profiling detail level for executable and library.\n" ++ profDetailLevelsHelp) configProfDetail (\v flags -> flags{configProfDetail = v}) ( reqArg' @@ -554,7 +552,7 @@ configureOptions showOrParseArgs = , option "" ["library-profiling-detail"] - "Profiling detail level for libraries only." + ("Profiling detail level for libraries only.\n" ++ profDetailLevelsHelp) configProfLibDetail (\v flags -> flags{configProfLibDetail = v}) ( reqArg' @@ -911,6 +909,20 @@ showProfDetailLevelFlag :: Flag ProfDetailLevel -> [String] showProfDetailLevelFlag NoFlag = [] showProfDetailLevelFlag (Flag dl) = [showProfDetailLevel dl] +-- | Help text listing the known profiling detail levels, one per line with +-- any aliases, so that the option descriptions stay in step with +-- 'knownProfDetailLevels'. +profDetailLevelsHelp :: String +profDetailLevelsHelp = + unlines ("Allowed values:" : punctuate [item primary aliases | (primary, aliases, _) <- knownProfDetailLevels]) + where + item primary [] = "- " ++ primary + item primary aliases = "- " ++ primary ++ " (or " ++ intercalate ", " aliases ++ ")" + + punctuate [] = [] + punctuate [x] = [x ++ "."] + punctuate (x : xs) = (x ++ ",") : punctuate xs + parsecPromisedComponent :: ParsecParser PromisedComponent parsecPromisedComponent = do pn <- parsec diff --git a/cabal-install/src/Distribution/Client/Setup.hs b/cabal-install/src/Distribution/Client/Setup.hs index a2eb4c9121d..e167c3f4bd1 100644 --- a/cabal-install/src/Distribution/Client/Setup.hs +++ b/cabal-install/src/Distribution/Client/Setup.hs @@ -524,10 +524,10 @@ globalCommand commands = , option [] ["http-transport"] - "Set a transport for http(s) requests. Accepts 'curl', 'wget', 'powershell', and 'plain-http'. (default: 'curl')" + "Set a transport for http(s) requests (default: curl)." globalHttpTransport (\v flags -> flags{globalHttpTransport = v}) - (reqArgFlag "HttpTransport") + (reqArgFlag "curl|wget|powershell|plain-http") , option [] ["store-dir", "storedir"] @@ -1955,11 +1955,14 @@ getCommand = , option [] ["index-state"] - ( "Use source package index state as it existed at a previous time. " - ++ "Accepts unix-timestamps (e.g. '@1474732068'), ISO8601 UTC timestamps " - ++ "(e.g. '2016-09-24T17:47:48Z'), or 'HEAD' (default: 'HEAD'). " - ++ "This determines which package versions are available as well as " - ++ ".cabal file revision is selected (unless --pristine is used)." + ( unlines + [ "Use source package index state as it existed at a previous time. Accepts:" + , "- a unix timestamp, e.g. '@1474732068'," + , "- an ISO8601 UTC timestamp, e.g. '2016-09-24T17:47:48Z'," + , "- 'HEAD', the default." + , "This determines which package versions are available as well as " + ++ ".cabal file revision is selected (unless --pristine is used)." + ] ) getIndexState (\v flags -> flags{getIndexState = v}) @@ -2685,9 +2688,12 @@ installOptions showOrParseArgs = , option [] ["index-state"] - ( "Use source package index state as it existed at a previous time. " - ++ "Accepts unix-timestamps (e.g. '@1474732068'), ISO8601 UTC timestamps " - ++ "(e.g. '2016-09-24T17:47:48Z'), or 'HEAD' (default: 'HEAD')." + ( unlines + [ "Use source package index state as it existed at a previous time. Accepts:" + , "- a unix timestamp, e.g. '@1474732068'," + , "- an ISO8601 UTC timestamp, e.g. '2016-09-24T17:47:48Z'," + , "- 'HEAD', the default." + ] ) installIndexState (\v flags -> flags{installIndexState = v}) @@ -3697,7 +3703,13 @@ optionSolverFlags , option [] ["prefer-version"] - "Select which version of a package that the solver should prefer. Oldest is useful to determine lower bounds in build-depends section. Latest will prefer the latest version. Installed-or-latest will prefer installed versions and the latest version otherwise." + ( unlines + [ "Select which version of a package that the solver should prefer:" + , "- oldest: useful to determine lower bounds in the build-depends section," + , "- latest: prefer the latest version," + , "- installed-or-latest: prefer installed versions and the latest version otherwise." + ] + ) getpo setpo ( reqArg From 624904b39e2a372fe5b772d4eedb4b8266f3ad49 Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Thu, 8 Oct 2026 13:04:37 -0400 Subject: [PATCH 6/7] Regenerate doc/cmd-*/*.txt --- doc/cmd-v1-help/configure.txt | 17 +++++++-- doc/cmd-v1-help/freeze.txt | 12 +++---- doc/cmd-v1-help/install.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v1-help/reconfigure.txt | 17 +++++++-- doc/cmd-v1-help/test.txt | 19 ++++++---- doc/cmd-v2-help/bench.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/build.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/configure.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/exec.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/fetch.txt | 12 +++---- doc/cmd-v2-help/freeze.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/gen-bounds.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/get.txt | 15 ++++---- doc/cmd-v2-help/haddock.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/help.txt | 7 ++-- doc/cmd-v2-help/install.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/list-bin.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/outdated.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/path.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/repl.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/run.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/target.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/test.txt | 63 ++++++++++++++++++++++----------- doc/cmd-v2-help/unpack.txt | 15 ++++---- doc/cmd-v2-help/update.txt | 63 ++++++++++++++++++++++----------- doc/setup-help/configure.txt | 17 +++++++-- doc/setup-help/test.txt | 19 ++++++---- 27 files changed, 831 insertions(+), 390 deletions(-) diff --git a/doc/cmd-v1-help/configure.txt b/doc/cmd-v1-help/configure.txt index 8ae0e879c7b..e042b41cee1 100644 --- a/doc/cmd-v1-help/configure.txt +++ b/doc/cmd-v1-help/configure.txt @@ -64,10 +64,23 @@ Flags for v1-configure: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) diff --git a/doc/cmd-v1-help/freeze.txt b/doc/cmd-v1-help/freeze.txt index 2357900bdf0..900d21123c8 100644 --- a/doc/cmd-v1-help/freeze.txt +++ b/doc/cmd-v1-help/freeze.txt @@ -56,12 +56,12 @@ Flags for v1-freeze: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. diff --git a/doc/cmd-v1-help/install.txt b/doc/cmd-v1-help/install.txt index 9ff8d062e2e..2a8cbeb3187 100644 --- a/doc/cmd-v1-help/install.txt +++ b/doc/cmd-v1-help/install.txt @@ -75,10 +75,23 @@ Flags for v1-install: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -250,12 +263,12 @@ Flags for v1-install: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -282,10 +295,11 @@ Flags for v1-install: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --symlink-bindir=DIR # Add symlinks to installed executables into this directory. @@ -295,7 +309,11 @@ Flags for v1-install: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -343,13 +361,18 @@ Flags for v1-install: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v1-help/reconfigure.txt b/doc/cmd-v1-help/reconfigure.txt index 8d32929356b..707d71b6fa4 100644 --- a/doc/cmd-v1-help/reconfigure.txt +++ b/doc/cmd-v1-help/reconfigure.txt @@ -63,10 +63,23 @@ Flags for v1-reconfigure: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) diff --git a/doc/cmd-v1-help/test.txt b/doc/cmd-v1-help/test.txt index 6732042f66a..2c1e85409e3 100644 --- a/doc/cmd-v1-help/test.txt +++ b/doc/cmd-v1-help/test.txt @@ -42,13 +42,18 @@ Flags for v1-test: --machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --fail-when-no-test-suites # Exit with failure when no test suites are diff --git a/doc/cmd-v2-help/bench.txt b/doc/cmd-v2-help/bench.txt index 3673a0135e5..4226f7c0758 100644 --- a/doc/cmd-v2-help/bench.txt +++ b/doc/cmd-v2-help/bench.txt @@ -68,10 +68,23 @@ Flags for bench: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -243,12 +256,12 @@ Flags for bench: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -275,10 +288,11 @@ Flags for bench: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -286,7 +300,11 @@ Flags for bench: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -334,13 +352,18 @@ Flags for bench: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/build.txt b/doc/cmd-v2-help/build.txt index 026d5f13a39..099d380e7cc 100644 --- a/doc/cmd-v2-help/build.txt +++ b/doc/cmd-v2-help/build.txt @@ -68,10 +68,23 @@ Flags for build: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -243,12 +256,12 @@ Flags for build: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -275,10 +288,11 @@ Flags for build: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -286,7 +300,11 @@ Flags for build: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -334,13 +352,18 @@ Flags for build: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/configure.txt b/doc/cmd-v2-help/configure.txt index 4fe69c01f31..757b96c55f3 100644 --- a/doc/cmd-v2-help/configure.txt +++ b/doc/cmd-v2-help/configure.txt @@ -81,10 +81,23 @@ Flags for configure: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -256,12 +269,12 @@ Flags for configure: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -288,10 +301,11 @@ Flags for configure: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -299,7 +313,11 @@ Flags for configure: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -347,13 +365,18 @@ Flags for configure: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/exec.txt b/doc/cmd-v2-help/exec.txt index e6418914ff0..d20731771eb 100644 --- a/doc/cmd-v2-help/exec.txt +++ b/doc/cmd-v2-help/exec.txt @@ -70,10 +70,23 @@ Flags for exec: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -245,12 +258,12 @@ Flags for exec: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -277,10 +290,11 @@ Flags for exec: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -288,7 +302,11 @@ Flags for exec: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -336,13 +354,18 @@ Flags for exec: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/fetch.txt b/doc/cmd-v2-help/fetch.txt index b66044ab234..5702b33df8d 100644 --- a/doc/cmd-v2-help/fetch.txt +++ b/doc/cmd-v2-help/fetch.txt @@ -55,12 +55,12 @@ Flags for fetch: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. diff --git a/doc/cmd-v2-help/freeze.txt b/doc/cmd-v2-help/freeze.txt index 923faf4f2eb..7a9e316d6c9 100644 --- a/doc/cmd-v2-help/freeze.txt +++ b/doc/cmd-v2-help/freeze.txt @@ -73,10 +73,23 @@ Flags for freeze: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -248,12 +261,12 @@ Flags for freeze: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -280,10 +293,11 @@ Flags for freeze: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -291,7 +305,11 @@ Flags for freeze: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -339,13 +357,18 @@ Flags for freeze: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/gen-bounds.txt b/doc/cmd-v2-help/gen-bounds.txt index 2343eb8c497..88a24e82ef6 100644 --- a/doc/cmd-v2-help/gen-bounds.txt +++ b/doc/cmd-v2-help/gen-bounds.txt @@ -59,10 +59,23 @@ Flags for gen-bounds: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -234,12 +247,12 @@ Flags for gen-bounds: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -266,10 +279,11 @@ Flags for gen-bounds: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -277,7 +291,11 @@ Flags for gen-bounds: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -325,13 +343,18 @@ Flags for gen-bounds: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/get.txt b/doc/cmd-v2-help/get.txt index 8f4331e5cf4..f90e5de9c21 100644 --- a/doc/cmd-v2-help/get.txt +++ b/doc/cmd-v2-help/get.txt @@ -17,13 +17,14 @@ Flags for get: # Copy the package's source repository (ie git clone, darcs get, etc as appropriate). --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). This determines which - package versions are available as well as - .cabal file revision is selected (unless - --pristine is used). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. + This determines which package versions are + available as well as .cabal file revision is + selected (unless --pristine is used). --only-package-description # Unpack only the package description file. --package-description-only # A synonym for --only-package-description. --pristine # Unpack the original pristine tarball, rather diff --git a/doc/cmd-v2-help/haddock.txt b/doc/cmd-v2-help/haddock.txt index 06647d8dd98..faf010e1e07 100644 --- a/doc/cmd-v2-help/haddock.txt +++ b/doc/cmd-v2-help/haddock.txt @@ -73,10 +73,23 @@ Flags for haddock: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -248,12 +261,12 @@ Flags for haddock: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -280,10 +293,11 @@ Flags for haddock: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -291,7 +305,11 @@ Flags for haddock: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -339,13 +357,18 @@ Flags for haddock: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/help.txt b/doc/cmd-v2-help/help.txt index dba7ffe6948..f4044a696c5 100644 --- a/doc/cmd-v2-help/help.txt +++ b/doc/cmd-v2-help/help.txt @@ -105,10 +105,9 @@ Global flags: --config-file=FILE # Set an alternate location for the config file --ignore-expiry # Ignore expiry dates on signed metadata (use only in exceptional circumstances) - --http-transport=HttpTransport - # Set a transport for http(s) requests. Accepts - 'curl', 'wget', 'powershell', and - 'plain-http'. (default: 'curl') + --http-transport=curl|wget|powershell|plain-http + # Set a transport for http(s) requests (default: + curl). --store-dir=DIR # The location of the build store --active-repositories=REPOS # The active package repositories (set to ':none' to disable all repositories) diff --git a/doc/cmd-v2-help/install.txt b/doc/cmd-v2-help/install.txt index 2ec898208b7..bd984d5d6e4 100644 --- a/doc/cmd-v2-help/install.txt +++ b/doc/cmd-v2-help/install.txt @@ -51,10 +51,23 @@ Flags for install: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -226,12 +239,12 @@ Flags for install: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -258,10 +271,11 @@ Flags for install: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -269,7 +283,11 @@ Flags for install: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -317,13 +335,18 @@ Flags for install: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/list-bin.txt b/doc/cmd-v2-help/list-bin.txt index 4813a871a17..c437833c6b0 100644 --- a/doc/cmd-v2-help/list-bin.txt +++ b/doc/cmd-v2-help/list-bin.txt @@ -60,10 +60,23 @@ Flags for list-bin: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -235,12 +248,12 @@ Flags for list-bin: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -267,10 +280,11 @@ Flags for list-bin: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -278,7 +292,11 @@ Flags for list-bin: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -326,13 +344,18 @@ Flags for list-bin: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/outdated.txt b/doc/cmd-v2-help/outdated.txt index 7c8ac302dde..de49622dc8e 100644 --- a/doc/cmd-v2-help/outdated.txt +++ b/doc/cmd-v2-help/outdated.txt @@ -61,10 +61,23 @@ Flags for outdated: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -236,12 +249,12 @@ Flags for outdated: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -268,10 +281,11 @@ Flags for outdated: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -279,7 +293,11 @@ Flags for outdated: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -327,13 +345,18 @@ Flags for outdated: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/path.txt b/doc/cmd-v2-help/path.txt index 85d6a0fcf66..8e12880d3e4 100644 --- a/doc/cmd-v2-help/path.txt +++ b/doc/cmd-v2-help/path.txt @@ -62,10 +62,23 @@ Flags for path: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -237,12 +250,12 @@ Flags for path: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -269,10 +282,11 @@ Flags for path: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -280,7 +294,11 @@ Flags for path: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -328,13 +346,18 @@ Flags for path: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/repl.txt b/doc/cmd-v2-help/repl.txt index 7a8d67a106d..4a46b18251b 100644 --- a/doc/cmd-v2-help/repl.txt +++ b/doc/cmd-v2-help/repl.txt @@ -71,10 +71,23 @@ Flags for repl: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -246,12 +259,12 @@ Flags for repl: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -278,10 +291,11 @@ Flags for repl: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -289,7 +303,11 @@ Flags for repl: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -337,13 +355,18 @@ Flags for repl: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/run.txt b/doc/cmd-v2-help/run.txt index 315e1f8ec1f..46322d47942 100644 --- a/doc/cmd-v2-help/run.txt +++ b/doc/cmd-v2-help/run.txt @@ -74,10 +74,23 @@ Flags for run: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -249,12 +262,12 @@ Flags for run: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -281,10 +294,11 @@ Flags for run: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -292,7 +306,11 @@ Flags for run: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -340,13 +358,18 @@ Flags for run: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/target.txt b/doc/cmd-v2-help/target.txt index 7ee4373a095..a64079a9f08 100644 --- a/doc/cmd-v2-help/target.txt +++ b/doc/cmd-v2-help/target.txt @@ -90,10 +90,23 @@ Flags for target: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -265,12 +278,12 @@ Flags for target: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -297,10 +310,11 @@ Flags for target: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -308,7 +322,11 @@ Flags for target: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -356,13 +374,18 @@ Flags for target: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/test.txt b/doc/cmd-v2-help/test.txt index 5011fa949e6..9f3575d1ddc 100644 --- a/doc/cmd-v2-help/test.txt +++ b/doc/cmd-v2-help/test.txt @@ -70,10 +70,23 @@ Flags for test: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -245,12 +258,12 @@ Flags for test: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -277,10 +290,11 @@ Flags for test: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -288,7 +302,11 @@ Flags for test: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -336,13 +354,18 @@ Flags for test: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/cmd-v2-help/unpack.txt b/doc/cmd-v2-help/unpack.txt index 415b4eb007d..d7e9e291bec 100644 --- a/doc/cmd-v2-help/unpack.txt +++ b/doc/cmd-v2-help/unpack.txt @@ -17,13 +17,14 @@ Flags for unpack: # Copy the package's source repository (ie git clone, darcs get, etc as appropriate). --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). This determines which - package versions are available as well as - .cabal file revision is selected (unless - --pristine is used). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. + This determines which package versions are + available as well as .cabal file revision is + selected (unless --pristine is used). --only-package-description # Unpack only the package description file. --package-description-only # A synonym for --only-package-description. --pristine # Unpack the original pristine tarball, rather diff --git a/doc/cmd-v2-help/update.txt b/doc/cmd-v2-help/update.txt index ff6cdee8feb..eb2fd4eea26 100644 --- a/doc/cmd-v2-help/update.txt +++ b/doc/cmd-v2-help/update.txt @@ -60,10 +60,23 @@ Flags for update: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) @@ -235,12 +248,12 @@ Flags for update: section. --prefer-version=oldest|latest|installed-or-latest # Select which version of a package that the - solver should prefer. Oldest is useful to - determine lower bounds in build-depends - section. Latest will prefer the latest - version. Installed-or-latest will prefer - installed versions and the latest version - otherwise. + solver should prefer: + - oldest: useful to determine lower bounds in + the build-depends section, + - latest: prefer the latest version, + - installed-or-latest: prefer installed + versions and the latest version otherwise. --shadow-installed-packages # If multiple package instances of the same version are installed, treat all but one as shadowed. @@ -267,10 +280,11 @@ Flags for update: build the given packages --dependencies-only # A synonym for --only-dependencies --index-state=STATE # Use source package index state as it existed - at a previous time. Accepts unix-timestamps - (e.g. '@1474732068'), ISO8601 UTC timestamps - (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' - (default: 'HEAD'). + at a previous time. Accepts: + - a unix timestamp, e.g. '@1474732068', + - an ISO8601 UTC timestamp, e.g. + '2016-09-24T17:47:48Z', + - 'HEAD', the default. --root-cmd=COMMAND # (No longer supported, do not use.) --build-summary=TEMPLATE # Save build summaries to file (name template can use $pkgid, $compiler, $os, $arch) @@ -278,7 +292,11 @@ Flags for update: $pkgid, $compiler, $os, $arch) --remote-build-reporting=LEVEL # Generate build reports to send to a remote - server (none, anonymous or detailed). + server: + - none: do not report, + - anonymous: report without identifying + information, + - detailed: report with full details. --report-planning-failure # Generate build reports when the dependency solver fails. This is used by the Hackage build bot. @@ -326,13 +344,18 @@ Flags for update: --test-machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --test-show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --test-show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --test-keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --test-fail-when-no-test-suites diff --git a/doc/setup-help/configure.txt b/doc/setup-help/configure.txt index 4d89ab66c29..9708ff5f7f4 100644 --- a/doc/setup-help/configure.txt +++ b/doc/setup-help/configure.txt @@ -64,10 +64,23 @@ Flags for configure: --disable-executable-profiling # Disable Executable profiling (DEPRECATED) --profiling-detail=level # Profiling detail level for executable and - library (default, none, exported-functions, - toplevel-functions, all-functions, late). + library. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). --library-profiling-detail=level # Profiling detail level for libraries only. + Allowed values: + - default, + - none, + - exported-functions (or exported), + - toplevel-functions (or toplevel, top), + - all-functions (or all), + - late-toplevel (or late). -O[n], --enable-optimization[=n] # Build with optimization (n is 0--2, default is 1) diff --git a/doc/setup-help/test.txt b/doc/setup-help/test.txt index 3ebe170302e..7100bb87bae 100644 --- a/doc/setup-help/test.txt +++ b/doc/setup-help/test.txt @@ -25,13 +25,18 @@ Flags for test: --machine-log=TEMPLATE # Produce a machine-readable log file (name template can use $pkgid, $compiler, $os, $arch, $result) - --show-details=FILTER # 'always': always show results of individual - test cases. 'never': never show results of - individual test cases. 'failures': show - results of failing test cases. 'streaming': - show results of test cases in real - time.'direct': send results of test cases in - real time; no log file. + --show-details=always|never|failures|streaming|direct + # Allowed values: + - always: always show results of individual + test cases, + - never: never show results of individual test + cases, + - failures: show results of failing test + cases, + - streaming: show results of test cases in + real time, + - direct: send results of test cases in real + time; no log file. --keep-tix-files # Keep .tix files for HPC between test runs --test-wrapper=FILE # Run test through a wrapper. --fail-when-no-test-suites # Exit with failure when no test suites are From 397445785778fc32742eb8d2606de2f4cea55da1 Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Thu, 8 Oct 2026 13:46:23 -0400 Subject: [PATCH 7/7] Add changelog entry --- changelog.d/pr-12424.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 changelog.d/pr-12424.md diff --git a/changelog.d/pr-12424.md b/changelog.d/pr-12424.md new file mode 100644 index 00000000000..b0df44b5b16 --- /dev/null +++ b/changelog.d/pr-12424.md @@ -0,0 +1,18 @@ +--- +synopsis: Keep line breaks and indent list items in command help text +packages: [Cabal, cabal-install] +prs: 12424 +issues: 12422 +--- + +`Distribution.GetOpt.usageInfo` used to re-flow an option's description as a +single run of words, so a description written with explicit line breaks lost +them. It now wraps each line on its own, and a line that starts with a `- ` +list marker gets a hanging indent, so its continuation lines align with the +text after the marker. + +The descriptions of `--show-details`, `--remote-build-reporting`, +`--prefer-version`, `--index-state`, `--profiling-detail`, +`--library-profiling-detail` and `--http-transport` now list their allowed +values one per line, and the placeholders of `--show-details`, +`--remote-build-reporting` and `--http-transport` name those values.