Option --store-dir not mentioned in help text of build

[andreasabel]

E.g. cabal build --help mentions many options like --builddir=DIR, but not --store-dir.

Issue lifted from #6866 (comment).

Docs at: https://cabal.readthedocs.io/en/latest/cabal-project.html#cmdoption-store-dir

Btw, not sure this option actually exists:

$ cabal build --storedir=.
cabal: unrecognized 'build' option `--storedir=.'

$ cabal build --store-dir=.
cabal: unrecognized 'build' option `--store-dir=.'

$ cabal configure --store-dir=.
cabal: unrecognized 'configure' option `--store-dir=.'

$ cabal install --store-dir=.
cabal: unrecognized 'install' option `--store-dir=.'

[Mikolaj]

The following works:

cabal --store-dir=. build

which matches the option not being a part of help text for build. However, it seems to be a global flag, which means it should be listed in cabal help, but it isn't. I may be missing something here, e.g., a third place options can be listed?

[fgaz]

However, it seems to be a global flag, which means it should be listed in cabal help, but it isn't. I may be missing something here, e.g., a third place options can be listed?

it isn't shown because it's listed in argsNotShown instead of argsShown.

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

Lines 370 to 400 in 7d4ce47

	argsNotShown :: [OptionField GlobalFlags]
	argsNotShown = [
	option [] ["remote-repo"]
	"The name and url for a remote repository"
	globalRemoteRepos (\v flags -> flags { globalRemoteRepos = v })
	(reqArg' "NAME:URL" (toNubList . maybeToList . readRemoteRepo) (map showRemoteRepo . fromNubList))
	,option [] ["local-no-index-repo"]
	"The name and a path for a local no-index repository"
	globalLocalNoIndexRepos (\v flags -> flags { globalLocalNoIndexRepos = v })
	(reqArg' "NAME:PATH" (toNubList . maybeToList . readLocalRepo) (map showLocalRepo . fromNubList))
	,option [] ["remote-repo-cache"]
	"The location where downloads from all remote repos are cached"
	globalCacheDir (\v flags -> flags { globalCacheDir = v })
	(reqArgFlag "DIR")
	,option [] ["logs-dir", "logsdir"]
	"The location to put log files"
	globalLogsDir (\v flags -> flags { globalLogsDir = v })
	(reqArgFlag "DIR")
	,option [] ["world-file"]
	"The location of the world file"
	globalWorldFile (\v flags -> flags { globalWorldFile = v })
	(reqArgFlag "FILE")
	,option [] ["store-dir", "storedir"]
	"The location of the nix-local-build store"
	globalStoreDir (\v flags -> flags { globalStoreDir = v })
	(reqArgFlag "DIR")

The original PR (#4623) does not state a reason for putting it there. I'd be in support of moving it to argsShown though (together with logs-dir maybe). I also occasionally use that flag.

Ping @alexbiehl who originally added the flag

[jneira]

It is a global flag so it is listed in cabal help and should be put before the subcommand:

PS D:\dev\ws\haskell\cabal> cabal --help
Command line interface to the Haskell Cabal infrastructure.

See http://www.haskell.org/cabal/ for more information.

Usage: cabal.exe [GLOBAL FLAGS] [COMMAND [FLAGS]]

.........

Global flags:
 -h, --help                     Show this help text
 -V, --version                  Print version information
 --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')
 --enable-nix                   Enable Nix integration: run commands through
                                nix-shell if a 'shell.nix' file exists
 --disable-nix                  Disable Nix integration: run commands through
                                nix-shell if a 'shell.nix' file exists
 --store-dir=DIR                The location of the build store
 --active-repositories=REPOS    The active package repositories (set to
                                ':none' to disable all repositories)

So the help tell us where we should put global flags and lists store-dir as one of them.

@andreasabel maybe we should close this? or change the title at least

[gbaz]

This was resolved by #7624

[andreasabel]

I think if a global option affects a command it should also be listed in the help text for this command.
This excludes e.g. --version (which is really a command written as a flag), but includes --store-dir for build.
I find the rigid hierarchical take of optparse-applicative on options not the most user-friendly. As user I would expect e.g. --store-dir and build can commute on the command line.

[jneira]

Well you cant set it after the build command so imo it would be pretty surprising for a user see it listed in cabal build --help and not being able to do cabal build --store-dir
Otoh other globalcabal flags affect the build command: --config-file, --http-transport, --active-repositories. Arguably --store-dir is more closely related but still.
And being global they should be listed in almost all commands.

Maybe we could do just that, list all global flags in all cabal command --help with the same format as cabal help, so we would achieve the same goal, being consistent at same time.

And improve the error when you set a general flag after a command instead:

PS D:\dev\ws\haskell\cabal> cabal build --store-dir=D:\sd
Error: cabal.exe: unrecognized 'build' option `--store-dir=D:\sd'

PS D:\dev\ws\haskell\cabal> cabal build --store-dir=D:\sd
`--store-dir` option is a global flag and should be set before the command

but that is another issue.

[jneira]

but that is another issue.

this one: #7704