Activity

1. philderbeast commented on Oct 9, 2026

   

   philderbeast

   on Oct 9, 2026

   Last edited by philderbeast

   CollaboratorAuthor

   More actions

   Here's the AI-assisted research on that.

   Options accepted per command, and which of them apply

   Checked against master at 0b16f4f. Accepted options come from cabal <command> --list-options, long options only. Each option accepted by configure or build was then run through cabal configure <option> to record the cabal.project.local field it lands in, which gives its section; ProjectConfig/Legacy.hs shows which flag fields are never converted; and the command actions in cabal-install/src/Distribution/Client/Cmd*.hs show which sections each command reads.

   Sections

   section	consumed by
   S: plan and solver settings	configure, build, repl, run, install, haddock, test, bench, exec, freeze, target, gen-bounds, outdated
   P: per-package build settings	build, repl, run, install, haddock, test, bench, exec, freeze, target, gen-bounds, outdated
   B: build-phase settings	build, repl, run, install, haddock, test, bench
   H: haddock settings	haddock
   T: test settings	test
   M: benchmark settings	bench
   I: not converted by any v2 command	no command

   16 options every nix-style command accepts and none uses

   The convertLegacy* functions in ProjectConfig/Legacy.hs read the command-line flag records into the project configuration by pattern matching, and they never name these fields (or bind them to _), so the values are parsed and dropped by every v2 command. The planner then computes IPID, CID, deterministic and the like for itself in elaborateInstallPlan. The = mempty lines in convertToLegacy* are the reverse direction and a symptom of this, not the cause. --dry-run, --only-dependencies and --only-download are different: they are not persisted either, but they are build-phase settings read at run time.

   --allow-depending-on-private-libs, --avoid-reinstalls, --cid, --coverage-for, --disable-deterministic, --disable-response-files, --enable-deterministic, --global, --ignore-build-tools, --instantiate-with, --ipid, --reinstall, --root-cmd, --shadow-installed-packages, --upgrade-dependencies, --user

   Plus --only, which v2 commands accept but never show in help.

   An earlier version of this comment counted 22 by reading the = mempty lines. Four of those are live in v2 for at least one command and stay: --enable/--disable-append and --enable/--disable-backup are read by configure straight from the flags to back up or append to cabal.project.local; --force-reinstalls is read by install --lib to overwrite packages already in the environment file; --dependencies-only is an alias of --only-dependencies, same field, so it works everywhere.

   These 16 cannot be deleted from the v1 option lists: the v1 commands still use them, and ~/.config/cabal/config derives its fields from the same lists (Distribution.Client.Config), where user-install, reinstall, root-cmd and the rest are real fields. The v2-only route is to select names in nixStyleOptions, the idiom #8556 used to drop the install directories from install.

   Per command

   "Applies" counts the options in the sections the command reads plus its own command-specific options. The counts predate the correction above: add --dependencies-only to every command, --enable/--disable-append and --enable/--disable-backup to configure, and --force-reinstalls to install; and --enable/--disable-benchmarks count as S, not M, see the section lists below. "Persisted only" counts options configure writes to cabal.project.local without acting on them itself. Counts include the three --list-options placeholders --with-PROG, --PROG-option and --PROG-options, and exclude --help and --list-options.

   command	accepts	applies	by section	own	persisted only	never used	basis
   configure	176	37	S=37	0	118	16	runs the solver to check the plan; persists P, B, H, T and M to cabal.project.local for later commands
   update	177	0	none	0	0	16	establishes the repository context only; reads projectConfigShared for repositories and the config file
   build	177	123	S=37 P=72 B=13	1	0	16	plans and runs the build phase; H applies when --enable-documentation is on
   repl	185	131	S=38 P=72 B=13	8	0	16	plans and builds dependencies
   freeze	177	110	S=38 P=72	0	0	16	plans only, to write the freeze file
   haddock	178	145	S=38 P=72 B=13 H=21	1	0	16	plans and runs the build phase for documentation
   install	169	115	S=38 P=58 B=13	6	0	16	plans and builds, then installs; H applies when --enable-documentation is on
   run	177	123	S=38 P=72 B=13	0	0	16	plans and builds, then runs the executable
   test	177	131	S=38 P=72 B=13 T=8	0	0	16	plans, builds and runs test suites
   bench	177	127	S=38 P=72 B=13 M=4	0	0	16	plans, builds and runs benchmarks
   exec	176	109	S=37 P=72	0	0	16	plans only, to compute the environment; reads dry-run and only-download from the build settings
   target	177	110	S=38 P=72	0	0	16	plans only, to resolve targets
   gen-bounds	176	109	S=37 P=72	0	0	16	plans only
   outdated	187	120	S=38 P=72	10	0	16	plans only, against the index and freeze files

   Related issues

   • --upgrade-dependencies should be marked as deprecated in v2- commands (and a hundred other options as well) #7437, --upgrade-dependencies should be marked as deprecated in v2- commands (and a hundred other options as well). Open since 2021 with the re: options label. Generalised in its first comment to every v2-* command having flags it does not use, with a proposal to show only the relevant flags per command and add a way to dump them all; the maintainers asked for an enumerating issue to track the work. A later comment proposes the mechanism: an optionHidden field on OptionField, --help listing only unhidden options, and --all-help for the full list. The tables above are that enumeration.
   • Commandline flags for cabal update seem to be wrong #9288, Commandline flags for cabal update seem to be wrong. Closed as a duplicate of --upgrade-dependencies should be marked as deprecated in v2- commands (and a hundred other options as well) #7437. The update row above, 177 options accepted and none applied, is its evidence.
   • cabal v2-install silently ignores --run-tests, but docs suggests it should work #11254 and cabal v2-install ignores flag --run-tests #7267, cabal v2-install silently ignores --run-tests. --run-tests is persisted as a per-package setting, so the section-level count above treats it as applying to install; these issues show that an option can be read by a command's section and still do nothing for that command, which is why the counts here are an upper bound on what applies.
   • --disable-library-vanilla does not seem to work with new-configure #4565, --disable-library-vanilla does not seem to work with new-configure. Same family as the previous two.
   • Cloak v2 and v1 help sections. #7979, Cloak v2 and v1 help sections, and Inconsistent --help output formatting #5377, Inconsistent --help output formatting. About the shape of the help rather than which options it lists.
   • PR Add installDirs (datadir, etc) to new-build and remove them from new-install #8556 removed --bindir and the other install directories from install after a comment on --upgrade-dependencies should be marked as deprecated in v2- commands (and a hundred other options as well) #7437 reported --bindir being silently ignored there. That is the precedent for dropping an option from one command's help, and the reason install accepts 14 fewer options than the other nix-style commands.

   No issue records that 22 options are converted to mempty by every v2 command.

   Suggested grouping of commands

   The sections a command reads sort the fourteen nix-style commands into four groups, and the three remaining commands already have option sets of their own. If each command's help listed only the sections it reads, plus its own options, this is what each group would show.

   group	commands	sections read	help would list	instead of
   build	build, run, repl, install	S, P, B	108 shared, plus the command's own	163 shared
   build with a phase of its own	haddock, test, bench	S, P, B, and H, T or M respectively	129, 116 or 112 shared, plus its own	163 shared
   plan only	freeze, target, gen-bounds, outdated, exec	S, P	95 shared, plus the command's own	163 shared
   persist the configuration	configure	S at run time; persists P, B, H, T and M	141 shared: everything that is persisted	163 shared
   repository only	update	none	the global options only	163 shared
   own option set	clean, sdist, haddock-project	not nix-style	7, 11 and 26	unchanged

   Two things fall out of the grouping regardless of how it is drawn:

   • The 16 never-used options could leave every command's help, since no command acts on them.
   • --enable-documentation is the one option that makes a section apply outside its group: with it on, the haddock settings matter to the build group too. The help for build, run, repl and install would either keep the 21 haddock options for that case or point at haddock --help.

   The counts are the shared options each group would still list, with the three --list-options placeholders included. Section sizes: S 39, P 58, B 13, H 21, T 8, M 2, never used 16. --enable/--disable-tests and --enable/--disable-benchmarks are solver inputs, which optional stanzas to solve for, so both pairs sit in S.

   Options by section (as accepted by build)

   S: plan and solver settings (39): --allow-boot-library-installs, --allow-newer, --allow-older, --builddir, --cabal-lib-version, --constraint, --count-conflicts, --disable-benchmarks, --disable-documentation, --disable-per-component, --disable-tests, --enable-benchmarks, --enable-documentation, --enable-per-component, --enable-tests, --extra-prog-path, --fine-grained-conflicts, --ghc, --ghcjs, --independent-goals, --index-state, --max-backjumps, --minimize-conflict-set, --package-db, --prefer-oldest, --prefer-version, --preference, --project-dir, --project-file, --project-file-parser, --reject-unconstrained-dependencies, --reorder-goals, --solver, --strong-flags, --uhc, --verbose, --with-compiler, --with-hc-pkg, --write-ghc-environment-files

   P: per-package build settings (72): --PROG-option, --PROG-options, --bindir, --bytecodelibdir, --configure-option, --datadir, --datasubdir, --disable-build-info, --disable-coverage, --disable-debug-info, --disable-executable-dynamic, --disable-executable-profiling, --disable-executable-static, --disable-executable-stripping, --disable-library-bytecode, --disable-library-coverage, --disable-library-for-ghci, --disable-library-profiling, --disable-library-stripping, --disable-library-vanilla, --disable-optimisation, --disable-optimization, --disable-profiling, --disable-profiling-shared, --disable-relocatable, --disable-shared, --disable-split-objs, --disable-split-sections, --disable-static, --docdir, --dynlibdir, --enable-build-info, --enable-coverage, --enable-debug-info, --enable-executable-dynamic, --enable-executable-profiling, --enable-executable-static, --enable-executable-stripping, --enable-library-bytecode, --enable-library-coverage, --enable-library-for-ghci, --enable-library-profiling, --enable-library-stripping, --enable-library-vanilla, --enable-optimisation, --enable-optimization, --enable-profiling, --enable-profiling-shared, --enable-relocatable, --enable-shared, --enable-split-objs, --enable-split-sections, --enable-static, --extra-framework-dirs, --extra-include-dirs, --extra-lib-dirs, --extra-lib-dirs-static, --flags, --haddockdir, --htmldir, --libdir, --libexecdir, --libexecsubdir, --library-profiling-detail, --libsubdir, --prefix, --profiling-detail, --program-prefix, --program-suffix, --run-tests, --sysconfdir, --with-PROG

   B: build-phase settings (13): --build-log, --build-summary, --build-timings, --dry-run, --jobs, --keep-going, --keep-temp-files, --offline, --only-dependencies, --only-download, --remote-build-reporting, --report-planning-failure, --semaphore

   H: haddock settings (21): --doc-index-file, --haddock-all, --haddock-base-url, --haddock-benchmarks, --haddock-contents-location, --haddock-css, --haddock-executables, --haddock-for-hackage, --haddock-hoogle, --haddock-hscolour-css, --haddock-html, --haddock-html-location, --haddock-hyperlink-source, --haddock-hyperlink-sources, --haddock-hyperlinked-source, --haddock-internal, --haddock-output-dir, --haddock-quickjump, --haddock-resources-dir, --haddock-tests, --haddock-use-unicode

   T: test settings (8): --test-fail-when-no-test-suites, --test-keep-tix-files, --test-log, --test-machine-log, --test-option, --test-options, --test-show-details, --test-wrapper

   M: benchmark settings (2): --benchmark-option, --benchmark-options

   Not accepted by every nix-style command: the fourteen install directories (--prefix, --bindir, --libdir, --libsubdir, --dynlibdir, --bytecodelibdir, --libexecdir, --libexecsubdir, --datadir, --datasubdir, --docdir, --htmldir, --haddockdir, --sysconfdir) are removed from install, and --ignore-project is absent from configure, build, exec and gen-bounds.

   Command-specific options

   command	options of its own
   build	--only-configure
   repl	--build-depends, --disable-multi-repl, --enable-multi-repl, --no-transitive-deps, --repl-multi-file, --repl-no-load, --repl-options, --with-repl
   haddock	--open
   haddock-project	--PROG-option, --all, --benchmarks, --builddir, --cabal-file, --css, --executables, --foreign-libraries, --ghc-options, --hackage, --haddock-all, --haddock-options, --help, --hoogle, --hscolour-css, --html-location, --internal, --keep-temp-files, --output, --prologue, --resources-dir, --tests, --use-unicode, --verbose, --with-ghc, --with-haddock
   install	--env, --install-method, --installdir, --lib, --overwrite-policy, --package-env
   clean	--builddir, --help, --project-dir, --project-file, --project-file-parser, --save-config, --verbose
   sdist	--builddir, --help, --ignore-project, --list-only, --null-sep, --output-directory, --outputdir, --project-dir, --project-file, --project-file-parser, --verbose
   outdated	--exit-code, --freeze-file, --ignore, --minor, --new-freeze-file, --project-context, --quiet, --simple-output, --v1-freeze-file, --v2-freeze-file
2. philderbeast

   added

   type: enhancement

   needs triage

   on Oct 9, 2026
3. philderbeast

   added a sub-issue on Oct 9, 2026

   • Remove v1 options that v2 command don't use #12431
4. Mikolaj

   changed the title [-]Remove options that don't apply to a command[/-] [+]Remove options from the help display that don't apply to a command[/+] on Oct 14, 2026
5. Mikolaj

   added

   re: optionsConcerning command-line optionsConcerning command-line options

   re: user experienceUser experience (UX) issueUser experience (UX) issue

   attention: pr-welcome

   and removed

   needs triage

   on Oct 14, 2026