From 76269cf4baaed3b95c5a98674286f3a803c883fc 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 925fcd47cd246872504ce93d29148efa116a6e6a 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 3614f97dbefd0dee8a398e469dd430cbb6836ce8 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 cf04e4df81d060ceec69e955c062eef33016bd90 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 9bf34d2519a9ab61b7bb9d5fde40cfbc506d9303 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 40bcd24b46c..de781ec7dd6 100644 --- a/Cabal/src/Distribution/Simple/Setup/Config.hs +++ b/Cabal/src/Distribution/Simple/Setup/Config.hs @@ -542,9 +542,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' @@ -555,7 +553,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' @@ -912,6 +910,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 d75d2320fa1d9bcef00712b44b77e2891e982888 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 7059ef5d400..8b938e2b504 100644 --- a/doc/cmd-v1-help/configure.txt +++ b/doc/cmd-v1-help/configure.txt @@ -65,10 +65,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 b4937a719cc..d735c6865e8 100644 --- a/doc/cmd-v1-help/install.txt +++ b/doc/cmd-v1-help/install.txt @@ -76,10 +76,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) @@ -251,12 +264,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. @@ -283,10 +296,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. @@ -296,7 +310,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. @@ -344,13 +362,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 15d821d1358..f9fabb2e32f 100644 --- a/doc/cmd-v1-help/reconfigure.txt +++ b/doc/cmd-v1-help/reconfigure.txt @@ -64,10 +64,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 c5ba5a99f02..8702bc8abff 100644 --- a/doc/cmd-v2-help/bench.txt +++ b/doc/cmd-v2-help/bench.txt @@ -69,10 +69,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) @@ -244,12 +257,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. @@ -276,10 +289,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) @@ -287,7 +301,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. @@ -335,13 +353,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 c4d2f57a62f..989925a3a66 100644 --- a/doc/cmd-v2-help/build.txt +++ b/doc/cmd-v2-help/build.txt @@ -69,10 +69,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) @@ -244,12 +257,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. @@ -276,10 +289,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) @@ -287,7 +301,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. @@ -335,13 +353,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 c97f66063b1..5b2ff83d360 100644 --- a/doc/cmd-v2-help/configure.txt +++ b/doc/cmd-v2-help/configure.txt @@ -82,10 +82,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) @@ -257,12 +270,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. @@ -289,10 +302,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) @@ -300,7 +314,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. @@ -348,13 +366,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 ea4368e9cd8..58bda1cb14d 100644 --- a/doc/cmd-v2-help/exec.txt +++ b/doc/cmd-v2-help/exec.txt @@ -71,10 +71,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) @@ -246,12 +259,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. @@ -278,10 +291,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) @@ -289,7 +303,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. @@ -337,13 +355,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 64269ce7f8e..290ff76c9e5 100644 --- a/doc/cmd-v2-help/freeze.txt +++ b/doc/cmd-v2-help/freeze.txt @@ -74,10 +74,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) @@ -249,12 +262,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. @@ -281,10 +294,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) @@ -292,7 +306,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. @@ -340,13 +358,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 8764aac5bda..40e88d3b01c 100644 --- a/doc/cmd-v2-help/gen-bounds.txt +++ b/doc/cmd-v2-help/gen-bounds.txt @@ -60,10 +60,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) @@ -235,12 +248,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. @@ -267,10 +280,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) @@ -278,7 +292,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. @@ -326,13 +344,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 2e5046e47f7..8ecb53cc721 100644 --- a/doc/cmd-v2-help/haddock.txt +++ b/doc/cmd-v2-help/haddock.txt @@ -74,10 +74,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) @@ -249,12 +262,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. @@ -281,10 +294,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) @@ -292,7 +306,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. @@ -340,13 +358,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 8850a2a2890..80cef6d5ff6 100644 --- a/doc/cmd-v2-help/install.txt +++ b/doc/cmd-v2-help/install.txt @@ -52,10 +52,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) @@ -227,12 +240,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. @@ -259,10 +272,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) @@ -270,7 +284,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. @@ -318,13 +336,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 3b8b8f01156..e89a8684b3b 100644 --- a/doc/cmd-v2-help/list-bin.txt +++ b/doc/cmd-v2-help/list-bin.txt @@ -61,10 +61,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) @@ -236,12 +249,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. @@ -268,10 +281,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) @@ -279,7 +293,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. @@ -327,13 +345,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 85a07dd7493..ed69a013331 100644 --- a/doc/cmd-v2-help/outdated.txt +++ b/doc/cmd-v2-help/outdated.txt @@ -62,10 +62,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) @@ -237,12 +250,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. @@ -269,10 +282,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) @@ -280,7 +294,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. @@ -328,13 +346,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 74f4a3b3355..04bdbc6eec2 100644 --- a/doc/cmd-v2-help/path.txt +++ b/doc/cmd-v2-help/path.txt @@ -63,10 +63,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) @@ -238,12 +251,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. @@ -270,10 +283,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) @@ -281,7 +295,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. @@ -329,13 +347,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 2913c652167..08ca8bb225f 100644 --- a/doc/cmd-v2-help/repl.txt +++ b/doc/cmd-v2-help/repl.txt @@ -72,10 +72,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) @@ -247,12 +260,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. @@ -279,10 +292,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) @@ -290,7 +304,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. @@ -338,13 +356,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 f8dd2b32a58..490a33ac339 100644 --- a/doc/cmd-v2-help/run.txt +++ b/doc/cmd-v2-help/run.txt @@ -75,10 +75,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) @@ -250,12 +263,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. @@ -282,10 +295,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) @@ -293,7 +307,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. @@ -341,13 +359,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 6dddae62364..8e3ba6894bb 100644 --- a/doc/cmd-v2-help/target.txt +++ b/doc/cmd-v2-help/target.txt @@ -91,10 +91,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) @@ -266,12 +279,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. @@ -298,10 +311,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) @@ -309,7 +323,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. @@ -357,13 +375,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 00c529d1a3b..1a33cb8b640 100644 --- a/doc/cmd-v2-help/test.txt +++ b/doc/cmd-v2-help/test.txt @@ -71,10 +71,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) @@ -246,12 +259,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. @@ -278,10 +291,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) @@ -289,7 +303,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. @@ -337,13 +355,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 cc4e6a3ea26..96d3ffe03af 100644 --- a/doc/cmd-v2-help/update.txt +++ b/doc/cmd-v2-help/update.txt @@ -61,10 +61,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) @@ -236,12 +249,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. @@ -268,10 +281,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) @@ -279,7 +293,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. @@ -327,13 +345,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 a5b3587cdd3..be80163fc6e 100644 --- a/doc/setup-help/configure.txt +++ b/doc/setup-help/configure.txt @@ -65,10 +65,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 2f45daee456536671d722aa0fadd8ad70646c513 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.