fix(Cabal, cabal-install): List global flags in the help text of every command

Cabal/src/Distribution/Simple/Command.hs

@@ -61,6 +61,7 @@ module Distribution.Simple.Command
     -- * Option Descriptions
   , OptDescr (..)
   , fmapOptDescr
+  , commandOptionsUsageInfo
   , Description
   , SFlags
   , LFlags
@@ -467,6 +468,11 @@ commandHelp command pname =
   where
     cname = commandName command
 
+-- | Render a table of options (given as 'OptionField's) for inclusion in a
+-- help text, in the same format as the options section of 'commandHelp'.
+commandOptionsUsageInfo :: String -> [OptionField flags] -> String
+commandOptionsUsageInfo header = GetOpt.usageInfo header . concatMap viewAsGetOpt
+
 -- | Default "usage" documentation text for commands.
 usageDefault :: String -> String -> String
 usageDefault name pname =
@@ -708,7 +714,7 @@ commandsRunWithFallback globalCommand commands defaultCommand args =
           case lookupCommand name of
             [Command _ _ action _] ->
               case action ("--help" : cmdArgs') of
-                CommandHelp help -> pure $ CommandHelp help
+                CommandHelp help -> pure $ CommandReadyToGo (flags, CommandHelp help)
                 CommandList _ -> pure $ CommandList []
                 _ -> pure $ CommandHelp globalHelp
             _ -> do

cabal-install/src/Distribution/Client/Main.hs

@@ -197,8 +197,10 @@ import Distribution.Simple.Command
   , CommandSpec (..)
   , CommandType (..)
   , CommandUI (..)
+  , ShowOrParseArgs (..)
   , commandAddAction
   , commandFromSpec
+  , commandOptionsUsageInfo
   , commandShowOptions
   , commandsRunWithFallback
   , defaultCommandFallback
@@ -324,6 +326,18 @@ main args = do
 
   mainWorker . (++ args1) =<< expandResponse args0
 
+-- | The section listing the global flags, appended to the help text of
+-- every command, so that global options such as @--store-dir@ can be
+-- discovered there (see issue #7587).
+globalFlagsSection :: String
+globalFlagsSection =
+  "\n"
+    ++ commandOptionsUsageInfo
+      "Global flags:"
+      (commandOptions (globalCommand []) ShowArgs)
+    ++ "\nGlobal flags must be given before the command, e.g.\n"
+    ++ "`cabal --store-dir=DIR build`.\n"
+
 -- | Check whether assertions are enabled and print a warning in that case.
 warnIfAssertionsAreEnabled :: IO ()
 warnIfAssertionsAreEnabled =
@@ -405,6 +419,7 @@ mainWorker args = do
     printCommandHelp help = do
       pname <- getProgName
       putStr (help pname)
+      putStr globalFlagsSection
     printGlobalHelp help = do
       pname <- getProgName
       configFile <- defaultConfigFile

cabal-testsuite/PackageTests/Help/GlobalFlagsInCommandHelp/global-flags-in-command-help.out

@@ -0,0 +1,2 @@
+# cabal build
+# cabal --help

cabal-testsuite/PackageTests/Help/GlobalFlagsInCommandHelp/global-flags-in-command-help.test.hs

@@ -0,0 +1,15 @@
+import Test.Cabal.Prelude
+
+main = cabalTest $ do
+  -- The help of an individual command should mention the global flags.
+  buildHelp <- cabal' "build" ["--help"]
+  assertOutputContains "Global flags:" buildHelp
+  assertOutputContains "--store-dir=DIR" buildHelp
+
+  -- The same help text is reachable via `cabal help build`.
+  buildHelp2 <- cabal_raw' ["help", "build"] Nothing
+  assertOutputContains "--store-dir=DIR" buildHelp2
+
+  -- For comparison, the global help has always listed `--store-dir`.
+  globalHelp <- cabal' "--help" []
+  assertOutputContains "--store-dir=DIR" globalHelp

changelog.d/12299.md

@@ -0,0 +1,41 @@
+---
+synopsis: List global flags in the help text of every command
+packages: [Cabal, cabal-install]
+prs: 12299
+issues: 7587
+---
+
+Example of the new `cabal build --help` output:
+
+```diff
+  Examples:
+    cabal build
+      Build the package in the current directory or all packages in the project
+    cabal build pkgname
+      Build the package named pkgname in the project
+    cabal build ./pkgfoo
+      Build the package in the ./pkgfoo directory
+    cabal build cname
+      Build the component named cname in the project
+    cabal build cname --enable-profiling
+      Build the component in profiling mode (including dependencies as needed)
++
++Global flags:
++ -V, --version                # Print version information
++ --full-version               # Print full version information with git
++                                revision (if available) and compiler
++ --numeric-version            # Print just the version number
++ --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')
++ --store-dir=DIR              # The location of the build store
++ --active-repositories=REPOS  # The active package repositories (set to
++                                ':none' to disable all repositories)
++
++Global flags must be given before the command, e.g.
++`cabal --store-dir=DIR build`.
+```

doc/cmd-v1-help/bench.txt

@@ -54,3 +54,22 @@ case with the nix-style commands.
 
 For more information, see:
 https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+
+Global flags:
+ -V, --version                # Print version information
+ --full-version               # Print full version information with git
+                                revision (if available) and compiler
+ --numeric-version            # Print just the version number
+ --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')
+ --store-dir=DIR              # The location of the build store
+ --active-repositories=REPOS  # The active package repositories (set to
+                                ':none' to disable all repositories)
+
+Global flags must be given before the command, e.g.
+`cabal --store-dir=DIR build`.

doc/cmd-v1-help/build.txt

@@ -41,3 +41,22 @@ case with the nix-style commands.
 
 For more information, see:
 https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+
+Global flags:
+ -V, --version                # Print version information
+ --full-version               # Print full version information with git
+                                revision (if available) and compiler
+ --numeric-version            # Print just the version number
+ --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')
+ --store-dir=DIR              # The location of the build store
+ --active-repositories=REPOS  # The active package repositories (set to
+                                ':none' to disable all repositories)
+
+Global flags must be given before the command, e.g.
+`cabal --store-dir=DIR build`.

doc/cmd-v1-help/clean.txt

@@ -24,3 +24,22 @@ case with the nix-style commands.
 
 For more information, see:
 https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+
+Global flags:
+ -V, --version                # Print version information
+ --full-version               # Print full version information with git
+                                revision (if available) and compiler
+ --numeric-version            # Print just the version number
+ --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')
+ --store-dir=DIR              # The location of the build store
+ --active-repositories=REPOS  # The active package repositories (set to
+                                ':none' to disable all repositories)
+
+Global flags must be given before the command, e.g.
+`cabal --store-dir=DIR build`.

doc/cmd-v1-help/configure.txt

@@ -224,3 +224,22 @@ case with the nix-style commands.
 
 For more information, see:
 https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+
+Global flags:
+ -V, --version                # Print version information
+ --full-version               # Print full version information with git
+                                revision (if available) and compiler
+ --numeric-version            # Print just the version number
+ --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')
+ --store-dir=DIR              # The location of the build store
+ --active-repositories=REPOS  # The active package repositories (set to
+                                ':none' to disable all repositories)
+
+Global flags must be given before the command, e.g.
+`cabal --store-dir=DIR build`.

doc/cmd-v1-help/copy.txt

@@ -29,3 +29,22 @@ case with the nix-style commands.
 
 For more information, see:
 https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+
+Global flags:
+ -V, --version                # Print version information
+ --full-version               # Print full version information with git
+                                revision (if available) and compiler
+ --numeric-version            # Print just the version number
+ --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')
+ --store-dir=DIR              # The location of the build store
+ --active-repositories=REPOS  # The active package repositories (set to
+                                ':none' to disable all repositories)
+
+Global flags must be given before the command, e.g.
+`cabal --store-dir=DIR build`.

doc/cmd-v1-help/freeze.txt

@@ -84,3 +84,22 @@ case with the nix-style commands.
 
 For more information, see:
 https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+
+Global flags:
+ -V, --version                # Print version information
+ --full-version               # Print full version information with git
+                                revision (if available) and compiler
+ --numeric-version            # Print just the version number
+ --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')
+ --store-dir=DIR              # The location of the build store
+ --active-repositories=REPOS  # The active package repositories (set to
+                                ':none' to disable all repositories)
+
+Global flags must be given before the command, e.g.
+`cabal --store-dir=DIR build`.

doc/cmd-v1-help/gen-bounds.txt

@@ -20,3 +20,22 @@ case with the nix-style commands.
 
 For more information, see:
 https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+
+Global flags:
+ -V, --version                # Print version information
+ --full-version               # Print full version information with git
+                                revision (if available) and compiler
+ --numeric-version            # Print just the version number
+ --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')
+ --store-dir=DIR              # The location of the build store
+ --active-repositories=REPOS  # The active package repositories (set to
+                                ':none' to disable all repositories)
+
+Global flags must be given before the command, e.g.
+`cabal --store-dir=DIR build`.

doc/cmd-v1-help/haddock.txt

@@ -58,3 +58,22 @@ case with the nix-style commands.
 
 For more information, see:
 https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+
+Global flags:
+ -V, --version                # Print version information
+ --full-version               # Print full version information with git
+                                revision (if available) and compiler
+ --numeric-version            # Print just the version number
+ --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')
+ --store-dir=DIR              # The location of the build store
+ --active-repositories=REPOS  # The active package repositories (set to
+                                ':none' to disable all repositories)
+
+Global flags must be given before the command, e.g.
+`cabal --store-dir=DIR build`.

doc/cmd-v1-help/install.txt

@@ -394,3 +394,22 @@ case with the nix-style commands.
 
 For more information, see:
 https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+
+Global flags:
+ -V, --version                # Print version information
+ --full-version               # Print full version information with git
+                                revision (if available) and compiler
+ --numeric-version            # Print just the version number
+ --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')
+ --store-dir=DIR              # The location of the build store
+ --active-repositories=REPOS  # The active package repositories (set to
+                                ':none' to disable all repositories)
+
+Global flags must be given before the command, e.g.
+`cabal --store-dir=DIR build`.

doc/cmd-v1-help/reconfigure.txt

@@ -220,3 +220,22 @@ case with the nix-style commands.
 
 For more information, see:
 https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+
+Global flags:
+ -V, --version                # Print version information
+ --full-version               # Print full version information with git
+                                revision (if available) and compiler
+ --numeric-version            # Print just the version number
+ --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')
+ --store-dir=DIR              # The location of the build store
+ --active-repositories=REPOS  # The active package repositories (set to
+                                ':none' to disable all repositories)
+
+Global flags must be given before the command, e.g.
+`cabal --store-dir=DIR build`.

doc/cmd-v1-help/register.txt

@@ -31,3 +31,22 @@ case with the nix-style commands.
 
 For more information, see:
 https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
+
+Global flags:
+ -V, --version                # Print version information
+ --full-version               # Print full version information with git
+                                revision (if available) and compiler
+ --numeric-version            # Print just the version number
+ --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')
+ --store-dir=DIR              # The location of the build store
+ --active-repositories=REPOS  # The active package repositories (set to
+                                ':none' to disable all repositories)
+
+Global flags must be given before the command, e.g.
+`cabal --store-dir=DIR build`.