`--upgrade-dependencies` should be marked as deprecated in v2- commands (and a hundred other options as well)

[Mikolaj]

Describe the bug

I'm religiously using --upgrade-dependencies, but I'm told it's placebo:

In v2-build, --upgrade-dependencies doesn't do anything, as the build-plan never re-uses existing packages, right?
It should be an outdated flag...

If so (please verify), it should be marked deprecated, at least in the commandline and web documentation, with an explanation the desired behaviour is now the default.

Edit: let's generalize this task as per @fendor's comment just below.

[fendor]

I think the issue is way bigger than only this. Every v2-* has at least a dozen flags it doesn't actually use or are deprecated since before I first used cabal.

The real task should be to revamp the flags for each command, which would improve the user experience immensely:

• Only show flags that are usually relevant for a command
• Introduce a different way to dump all available flags
  • E.g. cabal help <subcommand> or cabal build --show-all-options

In my opinion, this is something cabal really needs to be more accessible.

[Mikolaj]

Fully agree. And if you do this per-command then we don't need to wait for removal of v1- commands and v1-exclusive options.

[jneira]

I think we could link a dozen or so issues about flags not being honoured with v2 commands. However some of them express the desire to make them work effectively. So the deprecation would be temporary. Not sure how we could signal ("it still does not work but we aim to do it") those cases: maybe we could include some note in the option help about

[jneira]

I think the issue is way bigger than only this. Every v2-* has at least a dozen flags it doesn't actually use or are deprecated since before I first used cabal.

what do you think about create a specific, generic issue, if we are planning to tacke it in a generic way?
We could link all the issues of flags not being honoured and classify them there.
I am sure there are dragons in that path so advise from experienced maintainers would be great

[fendor]

A specific, maybe enumerating issue would be nice, or at least a place where the efforts can be tracked.
What would be the best way to track? Github Project style? One big issue, summarising efforts for each command?

[fendor]

To push this forward, I want to propose the following migration:

• Introduce a new-flag --all-help
  • It behaves identical to current --help
• Extend OptionField with optionHidden :: Bool
• Set every occurrence of optionHidden = False
• Make --help only show options that are enabled by optionHidden = False
• In cabal-install, override defaultNixStyleFlags to optionHidden = True
  • This will now hide every non-command specific flag. Not enough, we want to see some usually useful flags.
• Introduce small library that conveniently allows devs to show or hide certain options.

Example of how I imagine the cabal cli could look like:

> cabal build --help
  Compile targets within the project.

Usage: cabal build [TARGETS] [FLAGS]

Build one or more targets from within the project. The available targets are
the packages in the project as well as individual components within those
packages, including libraries, executables, test-suites or benchmarks. Targets
can be specified by name or location. If no target is specified then the
default is to build the package in the current directory.

Dependencies are built or rebuilt as necessary. Additional configuration flags
can be specified on the command line and these extend the project
configuration from the 'cabal.project', 'cabal.project.local' and other files.

Flags for build:
 -h, --help                     Show this help text
 -v, --verbose[=n]              Control verbosity (n is 0--3, default
                                verbosity level is 1)
 --cabal-file=PATH              use this Cabal file
 --project-file=FILE            Set the name of the cabal.project file to
                                search for in parent directories
 --builddir=DIR                 The directory where Cabal puts generated build
                                files (default dist)
 -f, --flags=FLAGS              Force values for the given flags in Cabal
                                conditionals in the .cabal file. E.g.,
                                --flags="debug -usebytestrings" forces the
                                flag "debug" to true and "usebytestrings" to
                                false.
 -w, --with-compiler=PATH       give the path to a particular compiler
 --enable-profiling             Enable Executable and library profiling
 -O, --enable-optimization[=n]  Build with optimization (n is 0--2, default is
                                1)
 --enable-debug-info[=n]        Emit debug info (n is 0--3, default is 0)
 --enable-documentation         Enable building of documentation
 --dry-run                      Do not install anything, only print what would
                                be installed.
 --only-download                Do not build anything, only fetch the
                                packages.
 --only-configure               Instead of performing a full build just run
                                the configure step
 --only-dependencies            Install only the dependencies necessary to
                                build the given packages
 -j, --jobs[=NUM]               Run NUM jobs simultaneously (or '$ncpus' if no
                                NUM is given).
 --keep-going                   After a build failure, continue to build other
                                unaffected packages.

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)

Now it only shows flags that seem immediately helpful to the user. However, note that we do not change the behaviour in the slightest, this is only a UX change.

While this arguably still looks rather massive in comparison to something like cargo:

`cargo-build --help`

> cargo-build 
Compile a local package and all of its dependencies

USAGE:
    cargo build [OPTIONS]

OPTIONS:
    -q, --quiet                      Do not print cargo log messages
    -p, --package <SPEC>...          Package to build (see `cargo help pkgid`)
        --workspace                  Build all packages in the workspace
        --exclude <SPEC>...          Exclude packages from the build
        --all                        Alias for --workspace (deprecated)
    -j, --jobs <N>                   Number of parallel jobs, defaults to # of CPUs
        --lib                        Build only this package's library
        --bin <NAME>...              Build only the specified binary
        --bins                       Build all binaries
        --example <NAME>...          Build only the specified example
        --examples                   Build all examples
        --test <NAME>...             Build only the specified test target
        --tests                      Build all tests
        --bench <NAME>...            Build only the specified bench target
        --benches                    Build all benches
        --all-targets                Build all targets
        --release                    Build artifacts in release mode, with optimizations
        --profile <PROFILE-NAME>     Build artifacts with the specified profile
        --features <FEATURES>...     Space or comma separated list of features to activate
        --all-features               Activate all available features
        --no-default-features        Do not activate the `default` feature
        --target <TRIPLE>...         Build for the target triple
        --target-dir <DIRECTORY>     Directory for all generated artifacts
        --out-dir <PATH>             Copy final artifacts to this directory (unstable)
        --manifest-path <PATH>       Path to Cargo.toml
        --ignore-rust-version        Ignore `rust-version` specification in packages
        --message-format <FMT>...    Error format
        --build-plan                 Output the build plan in JSON (unstable)
        --unit-graph                 Output build graph in JSON (unstable)
        --future-incompat-report     Outputs a future incompatibility report at the end of the build (unstable)
    -v, --verbose                    Use verbose output (-vv very verbose/build.rs output)
        --color <WHEN>               Coloring: auto, always, never
        --frozen                     Require Cargo.lock and cache are up to date
        --locked                     Require Cargo.lock is up to date
        --offline                    Run without accessing the network
        --config <KEY=VALUE>...      Override a configuration value (unstable)
    -Z <FLAG>...                     Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
    -h, --help                       Prints help information

Run `cargo help build` for more detailed information.

I think this would still be a massive improvement.

[mgajda]

Last two days on Munihac, I spent a lot of time trying to fix cabal new-install option --bindir just to learn that it is no longer supported.

It would be nice to at least show the warning Option --bindir is now ignored when it is used.
Especially that there is option --installdir that does the same for recent cabal versions.
Should I file a separate ticket for it?

[Mikolaj]

Thank you for the separate ticket. A separate PR would be amazing, too. :)

[gbaz]

Incidentally, #8556 will remove --bindir as an option from new-install.